@wirecat/cli-core 0.503.0 → 0.505.0

package/CHANGELOG.md

@@ -7,6 +7,42 @@ shape of this file.
 
 ## Unreleased
 
+## 0.505.0 — 31.10.2026
+
+### Added
+
+- **`appDoctorCommand` takes `--online`, and a messenger's and an app's `doctor` now say one thing.** Both use the
+  summary "the state this installation is in, without connecting unless --online" and the option text "also connect
+  once and read the account; sends nothing" (one constant, `doctor-text.ts`). Without the flag the answer is as before
+  and nothing is called. With it, `online` joins the answer: `{ ok, duration_ms, version: { current, latest, newer } }`,
+  plus the fields of the new `AppDoctorOptions.online(env)` hook, where a CLI checks its own service (a login, a folder
+  read); a throw there is `ok: false` with `error_code` and `error`, never a failed command. `version` comes from npm
+  (the `latestVersion` that `upgrade` uses) when the CLI passes the new `AppDoctorOptions.packageName`; without it that
+  check is left out. The command's effects are now `REMOTE_READ`, as the messenger's.
+
+## 0.504.0 — 31.10.2026
+
+### Added
+
+- **`projects evidence --sync-first` in messenger CLIs: `projectsCommand(messenger)`.** A CLI
+  that mounts it reads a project's evidence from its profile's stored messages; `--sync-first` (off by default, not on
+  MCP) first syncs the project's linked chats the store does not hold back to `--since-time`, within `--sync-time`
+  (3 minutes), one chat at a time. A chat the time cut stays partial with its `missing` and `next`. The command is
+  declared a fetch (`remote: read`, `local: write`) because of `--sync-first`; cli-base fixes effects per command.
+  It prints what people wrote, so the `messages` permission guards it.
+- **`gatherStoredProject`** (services) and **`projectAnswerParts`, `projectEvidenceText`, `projectWindowOf`,
+  `projectCutoffTime`** (cli): memo's `projects evidence` over a store, moved here so memo and the messenger CLIs
+  share it. The host resolves the sources and names its own sync command in the text.
+
+### Changed — may break callers
+
+- **`gatherProjectEvidence`'s fetch port is per linked chat.** `ProjectSourceFetcher` (one fetch per source, no
+  caller) is replaced by `ProjectChatFetcher`: `fetch({ account, chatId, after, before, until, signal, onProgress })` →
+  `{ state: "complete" | "partial" | "failed", reason? }`. `fetch: "before-read"` now needs the `coverage` port too,
+  takes `budgets.maxFetchMs`, and fetches only linked chats the store does not hold for the window. The result's
+  `fetch` lists those chats (`ProjectChatFetched`) instead of one row per source; `ProjectFetchState` is gone. The
+  read budgets, `maxElapsedMs` included, start after the fetch.
+
 ## 0.503.0 — 31.10.2026
 
 ### Added

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

@@ -9,6 +9,15 @@ export interface AppDoctorOptions {
     oauthClient?: (env: NodeJS.ProcessEnv) => {
         client: "wirecat" | "own";
     };
+    /** The npm package, so `--online` can say whether a newer version is published; without it that check is left out. */
+    packageName?: string;
+    /**
+     * What `--online` checks of the service: a login, a folder read. Its fields join the `online` answer, and `ok: false`
+     * (or a throw, reported as `error_code` and `error`) makes the whole check fail without failing the command.
+     */
+    online?: (env: NodeJS.ProcessEnv) => Promise<{
+        ok: boolean;
+    } & Record<string, unknown>>;
 }
 /**
  * Run when everything else is broken, so a problem in the config file or the OAuth setting is a field, never a throw.
@@ -103,5 +112,9 @@ export declare const appDoctorReport: (app: AppIdentity, configuration: Configur
     };
     fixes: string[] | never[];
 };
-/** `doctor` for a CLI that is not a messenger: gcal, drive, zoom. A messenger's is `doctorCommand(messenger)`. */
+/**
+ * `doctor` for a CLI that is not a messenger: gcal, drive, zoom. A messenger's is `doctorCommand(messenger)`, and both
+ * say the same thing: the state from disk, and only with `--online` a call out. Here that call is `options.online`
+ * and, with `options.packageName`, whether npm has a newer version.
+ */
 export declare const appDoctorCommand: (app: AppIdentity, configuration: Configuration, options?: AppDoctorOptions) => Command;

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

@@ -2,15 +2,48 @@ import { existsSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { CliError, configFilePath, resolvePaths } from "@wirecat/cli-base";
 import { annotate } from "@wirecat/cli-base/commands";
+import { isNewer, latestVersion } from "@wirecat/cli-base/update";
 import { Command } from "commander";
 import { envName, readOnlyLockOf } from "../ports/app.js";
 import { storePath } from "../store/path.js";
 import { environmentOf, outputFor } from "./context.js";
-import { LOCAL_READ } from "./effects.js";
+import { DOCTOR_ONLINE_OPTION, DOCTOR_SUMMARY } from "./doctor-text.js";
+import { REMOTE_READ } from "./effects.js";
 import { itemOf, renderAnswer } from "./envelope.js";
 import { privateFiles } from "./messenger/private-files.js";
 import { unknownPermissionIssues } from "./permission-keys.js";
 import { profileFree } from "./profile.js";
+const onlineCheck = async (app, env, fetcher, options) => {
+    const started = Date.now();
+    let service = { ok: true };
+    if (options.online)
+        try {
+            service = await options.online(env);
+        }
+        catch (error) {
+            service = {
+                ok: false,
+                error_code: error instanceof CliError ? error.code : "generic_failure",
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    const latest = options.packageName
+        ? await latestVersion(options.packageName, fetcher, { timeoutMs: 3000 })
+        : undefined;
+    return {
+        ...service,
+        duration_ms: Date.now() - started,
+        ...(options.packageName
+            ? {
+                version: {
+                    current: app.version,
+                    latest: latest ?? null,
+                    newer: latest !== undefined && isNewer(latest, app.version),
+                },
+            }
+            : {}),
+    };
+};
 const failure = (error) => {
     if (error instanceof CliError)
         return error.message;
@@ -85,17 +118,26 @@ export const appDoctorReport = (app, configuration, env, command, options = {})
         };
     }
 };
-/** `doctor` for a CLI that is not a messenger: gcal, drive, zoom. A messenger's is `doctorCommand(messenger)`. */
+/**
+ * `doctor` for a CLI that is not a messenger: gcal, drive, zoom. A messenger's is `doctorCommand(messenger)`, and both
+ * say the same thing: the state from disk, and only with `--online` a call out. Here that call is `options.online`
+ * and, with `options.packageName`, whether npm has a newer version.
+ */
 export const appDoctorCommand = (app, configuration, options = {}) => profileFree(annotate(new Command("doctor"), {
-    effects: LOCAL_READ,
+    effects: REMOTE_READ,
     examples: [`${app.command} doctor`, `${app.command} doctor --json`],
 }))
-    .description("check this installation: version, paths, config, profiles, store; no keyring or network")
-    .action(function () {
-    const env = environmentOf(this).env ?? process.env;
+    .description(DOCTOR_SUMMARY)
+    .option("--online", DOCTOR_ONLINE_OPTION)
+    .action(async function () {
+    const environment = environmentOf(this);
+    const env = environment.env ?? process.env;
     const { report, fixes } = appDoctorReport(app, configuration, env, this, options);
+    const online = this.opts().online
+        ? await onlineCheck(app, env, environment.fetch ?? fetch, options)
+        : undefined;
     const output = outputFor(this);
-    renderAnswer(this, output, itemOf(report));
+    renderAnswer(this, output, itemOf(online ? { ...report, online } : report));
     for (const fix of fixes)
         output.renderer.note(`to make it private: ${fix}`);
 });

package/dist/cli/doctor-text.d.ts

@@ -0,0 +1,2 @@
+export declare const DOCTOR_SUMMARY = "the state this installation is in, without connecting unless --online";
+export declare const DOCTOR_ONLINE_OPTION = "also connect once and read the account; sends nothing";

package/dist/cli/doctor-text.js

@@ -0,0 +1,2 @@
+export const DOCTOR_SUMMARY = "the state this installation is in, without connecting unless --online";
+export const DOCTOR_ONLINE_OPTION = "also connect once and read the account; sends nothing";

package/dist/cli/index.d.ts

@@ -109,11 +109,12 @@ export { window, withPaging } from "./paging.js";
 export { type CommandPermissions, commandPathKey, commandPermissions, knownBeside, knownPermissionKeys, type PermissionKeyOf, type PermissionKeySource, refuseUnknownPermissionKeys, unknownPermissionIssues, unknownPermissionKeys, } from "./permission-keys.js";
 export { asFirstWord, commandWords, liftProfile, profileFree, refuseCommandName, rootOf, takesProfile, usableProfileName, } from "./profile.js";
 export { createProgram, type ProgramDefinition, type ProgramOptions, type RunOptions, run } from "./program.js";
+export { type ProjectTextHints, projectAnswerParts, projectCutoffTime, projectEvidenceText, projectWindowOf, } from "./project-evidence.js";
 export { fieldsOf, projectFields } from "./result-fields.js";
 export { type Config, type Configuration, count, first, flag, fromFile, type GlobalFlags, NONE_NAMED, namedProfile, type ProfileKind, plain, type ResolveOptions, type Settings, type SettingsExtension, type SettingsExtensionContext, type Source, settingsFor, } from "./settings.js";
 export { type PermissionAnswer, readSetupAnswers, type SetupAnswers, setupPermissionCeiling } from "./setup-answers.js";
 export { AGENTS, type Agent, agentFor, screenFor } from "./setup-screen.js";
-export { accountCommand, addMeetingBatchCommand, addMeetingPreparationCommand, addMeetingProjectCandidatesCommand, addMeetingSeriesInventoryCommand, appDoctorCommand, appMcpCommand, attachmentsCommand, botAdminsCommand, botCommand, botMcpCommand, botMembersCommand, botMessagesCommand, callsCommand, chatsCommand, commandsCommand, completeCommand, configCommand, contactsCommand, conversationsCommand, deleteCommand, doctorCommand, editCommand, floodCommand, forwardCommand, generatedApiCommand, guideCommand, imagesCommand, inboxCommand, markReadCommand, mcpCommand, mentionsCommand, messagesCommand, metadataCommand, modelCatalogueCommand, modelsCommand, pinCommand, pollsCommand, reactionsCommand, recipientsCommand, repliesCommand, reviewCommand, runsCommand, scheduleCommand, searchCommand, searchesCommand, sendCommand, sendsCommand, serveCommand, serverCommand, skillCommand, starCommands, statsCommand, stickersCommand, storeCommand, tagsCommand, tasksCommand, tasksStatsCommand, topicsCommand, unpinCommand, upgradeCommand, watchCommand, } from "./shared-command-exports.js";
+export { accountCommand, addMeetingBatchCommand, addMeetingPreparationCommand, addMeetingProjectCandidatesCommand, addMeetingSeriesInventoryCommand, appDoctorCommand, appMcpCommand, attachmentsCommand, botAdminsCommand, botCommand, botMcpCommand, botMembersCommand, botMessagesCommand, callsCommand, chatsCommand, commandsCommand, completeCommand, configCommand, contactsCommand, conversationsCommand, deleteCommand, doctorCommand, editCommand, floodCommand, forwardCommand, generatedApiCommand, guideCommand, imagesCommand, inboxCommand, markReadCommand, mcpCommand, mentionsCommand, messagesCommand, metadataCommand, modelCatalogueCommand, modelsCommand, pinCommand, pollsCommand, projectsCommand, reactionsCommand, recipientsCommand, repliesCommand, reviewCommand, runsCommand, scheduleCommand, searchCommand, searchesCommand, sendCommand, sendsCommand, serveCommand, serverCommand, skillCommand, starCommands, statsCommand, stickersCommand, storeCommand, tagsCommand, tasksCommand, tasksStatsCommand, topicsCommand, unpinCommand, upgradeCommand, watchCommand, } from "./shared-command-exports.js";
 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";

package/dist/cli/index.js

@@ -99,11 +99,12 @@ export { window, withPaging } from "./paging.js";
 export { commandPathKey, commandPermissions, knownBeside, knownPermissionKeys, refuseUnknownPermissionKeys, unknownPermissionIssues, unknownPermissionKeys, } from "./permission-keys.js";
 export { asFirstWord, commandWords, liftProfile, profileFree, refuseCommandName, rootOf, takesProfile, usableProfileName, } from "./profile.js";
 export { createProgram, run } from "./program.js";
+export { projectAnswerParts, projectCutoffTime, projectEvidenceText, projectWindowOf, } from "./project-evidence.js";
 export { fieldsOf, projectFields } from "./result-fields.js";
 export { count, first, flag, fromFile, NONE_NAMED, namedProfile, plain, settingsFor, } from "./settings.js";
 export { readSetupAnswers, setupPermissionCeiling } from "./setup-answers.js";
 export { AGENTS, agentFor, screenFor } from "./setup-screen.js";
-export { accountCommand, addMeetingBatchCommand, addMeetingPreparationCommand, addMeetingProjectCandidatesCommand, addMeetingSeriesInventoryCommand, appDoctorCommand, appMcpCommand, attachmentsCommand, botAdminsCommand, botCommand, botMcpCommand, botMembersCommand, botMessagesCommand, callsCommand, chatsCommand, commandsCommand, completeCommand, configCommand, contactsCommand, conversationsCommand, deleteCommand, doctorCommand, editCommand, floodCommand, forwardCommand, generatedApiCommand, guideCommand, imagesCommand, inboxCommand, markReadCommand, mcpCommand, mentionsCommand, messagesCommand, metadataCommand, modelCatalogueCommand, modelsCommand, pinCommand, pollsCommand, reactionsCommand, recipientsCommand, repliesCommand, reviewCommand, runsCommand, scheduleCommand, searchCommand, searchesCommand, sendCommand, sendsCommand, serveCommand, serverCommand, skillCommand, starCommands, statsCommand, stickersCommand, storeCommand, tagsCommand, tasksCommand, tasksStatsCommand, topicsCommand, unpinCommand, upgradeCommand, watchCommand, } from "./shared-command-exports.js";
+export { accountCommand, addMeetingBatchCommand, addMeetingPreparationCommand, addMeetingProjectCandidatesCommand, addMeetingSeriesInventoryCommand, appDoctorCommand, appMcpCommand, attachmentsCommand, botAdminsCommand, botCommand, botMcpCommand, botMembersCommand, botMessagesCommand, callsCommand, chatsCommand, commandsCommand, completeCommand, configCommand, contactsCommand, conversationsCommand, deleteCommand, doctorCommand, editCommand, floodCommand, forwardCommand, generatedApiCommand, guideCommand, imagesCommand, inboxCommand, markReadCommand, mcpCommand, mentionsCommand, messagesCommand, metadataCommand, modelCatalogueCommand, modelsCommand, pinCommand, pollsCommand, projectsCommand, reactionsCommand, recipientsCommand, repliesCommand, reviewCommand, runsCommand, scheduleCommand, searchCommand, searchesCommand, sendCommand, sendsCommand, serveCommand, serverCommand, skillCommand, starCommands, statsCommand, stickersCommand, storeCommand, tagsCommand, tasksCommand, tasksStatsCommand, topicsCommand, unpinCommand, upgradeCommand, watchCommand, } from "./shared-command-exports.js";
 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";

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

@@ -10,6 +10,7 @@ import { FloodMemory, floodPathFor } from "../../sends/flood.js";
 import { SendJournal, sendsPathFor } from "../../sends/journal.js";
 import { storePath } from "../../store/path.js";
 import { baseContext, environmentOf, outputFor } from "../context.js";
+import { DOCTOR_ONLINE_OPTION, DOCTOR_SUMMARY } from "../doctor-text.js";
 import { destroysNothing, LOCAL_WRITE, NO_EFFECTS, REMOTE_READ } from "../effects.js";
 import { itemOf, renderAnswer, snakeKeys } from "../envelope.js";
 import { unknownPermissionIssues } from "../permission-keys.js";
@@ -28,8 +29,8 @@ import { storeSummary } from "./store-maintenance-command.js";
  */
 export const doctorCommand = (messenger) => {
     const command = annotate(new Command("doctor"), { effects: REMOTE_READ })
-        .description("the state this installation is in, without connecting unless --online")
-        .option("--online", "also connect once and read the account; sends nothing")
+        .description(DOCTOR_SUMMARY)
+        .option("--online", DOCTOR_ONLINE_OPTION)
         .action(async function () {
         const { online } = this.opts();
         const { report, renderer, fixes = [] } = await diagnose(this, messenger);

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

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+import { type Messenger } from "./context.js";
+export declare const projectsCommand: (messenger: Messenger) => Command;

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

@@ -0,0 +1,134 @@
+import { CliError } from "@wirecat/cli-base";
+import { annotate, annotateOption } from "@wirecat/cli-base/commands";
+import { Command, Option } from "commander";
+import { parseDuration } from "../../domain/duration.js";
+import { FETCHING } from "../../services/archive.js";
+import { gatherStoredProject } from "../../services/stored-project-gathering.js";
+import { FETCH } from "../effects.js";
+import { itemOf, renderAnswer, snakeKeys } from "../envelope.js";
+import { positiveCount } from "../paging.js";
+import { projectAnswerParts, projectCutoffTime, projectEvidenceText, projectWindowOf } from "../project-evidence.js";
+import { lineOf } from "../steps.js";
+import { messengerContext } from "./context.js";
+const collect = (value, previous) => [...previous, value];
+const upTo = (most, flag) => (value) => {
+    const n = Number(value);
+    if (!/^\d+$/.test(value) || n > most)
+        throw new CliError("validation_error", `${flag} takes a whole number from 0 to ${most}`);
+    return n;
+};
+/** More than any chat one fetch budget can bring; the budget, not the count, ends a long chat. */
+const FETCH_LIMIT = 1_000_000;
+/** This profile's account, the only one its connection can sync. */
+const sourcesOf = async (store, account) => {
+    const stored = (await store.accounts.storedAccounts()).find((one) => one.provider === account.provider && one.account === account.account);
+    if (!stored)
+        throw new CliError("not_found", "the store holds nothing of this profile's account yet; sync a chat first", {
+            param: "profile",
+        });
+    return {
+        sources: [{ kind: "message", accountId: stored.id, provider: stored.provider, account: stored.account }],
+        unread: [],
+        scope: "explicit",
+    };
+};
+/**
+ * `archive.fetch` back to the window start, one linked chat at a time. Only this profile's account is a source, so
+ * the gathering never asks for another account's chat.
+ */
+const archiveFetcher = (withServices, messenger) => {
+    const fetching = messenger.fetching ?? FETCHING;
+    return {
+        fetch: async ({ chatId, after, signal, onProgress }) => {
+            const result = await withServices((services) => services.archive.fetch(chatId, {
+                limit: FETCH_LIMIT,
+                pageSize: fetching.page,
+                pauseMs: parseDuration(fetching.pause, "pause"),
+                sinceMs: after,
+                catchUp: false,
+                note: () => { },
+                stop: signal,
+                onPage: ({ fetched, oldest }) => onProgress?.({ fetched, oldest }),
+            }));
+            if (result.issue)
+                return { state: "partial", reason: result.issue.code };
+            if (result.stopped)
+                return { state: "partial", reason: "fetch-budget" };
+            return result.complete || result.reachedSince ? { state: "complete" } : { state: "partial", reason: "limit" };
+        },
+    };
+};
+/** Off MCP: a tool call ends at about a minute, too soon for a sync, which would fail the whole answer. */
+const cliOnly = (flags, description, value) => {
+    const option = new Option(flags, description);
+    if (value !== undefined)
+        option.default(value);
+    return annotateOption(option, { mcp: false });
+};
+export const projectsCommand = (messenger) => {
+    const projects = new Command("projects").description("what the store holds about the owner's projects");
+    const app = messenger.app.command;
+    projects.addCommand(annotate(new Command("evidence"), {
+        output: { entity: "project_evidence" },
+        examples: [`${app} personal projects evidence "Harbour" --since-time 30d --sync-first`],
+        // Declared as a fetch for --sync-first; without it nothing leaves this machine, and a fetch is never a write elsewhere.
+        effects: FETCH,
+        cooperative: true,
+        partial: true,
+    })
+        .summary("what this account's stored messages hold about a project, linked chats included")
+        .description("cited references about a project in this profile's stored messages. The project's name, key, each alias and " +
+        "each --alias, --context-query and --contact name is its own search; their hits are joined. Every message of " +
+        "a chat confirmed as the project's is read too, and so is what a confirmed person member wrote. Reads what the " +
+        "store holds; with --sync-first it first syncs the project's linked chats the store does not hold for the window")
+        .argument("<project>", "an existing project's id, key, exact name or alias, or a new project's name")
+        .option("--alias <name>", "another name of the project, searched on its own; repeat for more", collect, [])
+        .option("--context-query <words>", "more words that all appear in one text; repeat for another", collect, [])
+        .option("--contact <person>", "a name to search, or person:<id> to read what that person wrote", collect, [])
+        .option("--since-time <time>", "how far back: days (90d, at most 730d) or a start date (2026-09-01)", "60d")
+        .option("--before-time <time>", "fixed exclusive end: ISO 8601 timestamp with UTC offset")
+        .option("--limit <n>", "new references at most, up to 500; 100 if not given", positiveCount("--limit"))
+        .option("--max-pages <pages>", "store pages read at most this run, up to 512", positiveCount("--max-pages"))
+        .option("--cursor <cursor>", "continue a stopped search from its checkpoint, with the same options")
+        .option("--before-n <n>", "messages before each message hit, at most 5", upTo(5, "--before-n"), 2)
+        .option("--after-n <n>", "messages after each message hit, at most 5", upTo(5, "--after-n"), 2)
+        .option("--no-catch-up", "read the search index as it is, without indexing new text first")
+        .addOption(cliOnly("--sync-first", "first sync the linked chats this account does not hold back to --since-time; off by default"))
+        .addOption(cliOnly("--sync-time <duration>", "time for all of --sync-first's syncs together; 3m if not given", "3m"))
+        .action(async function (project) {
+        const options = this.opts();
+        const context = messengerContext(this, messenger);
+        const maxFetchMs = parseDuration(options.syncTime, "--sync-time");
+        const gather = (store, account, fetcher) => sourcesOf(store, account).then((sources) => gatherStoredProject(store, {
+            project,
+            sources,
+            ...projectWindowOf(options.sinceTime),
+            ...(options.beforeTime === undefined ? {} : { asOf: projectCutoffTime(options.beforeTime) }),
+            limit: options.limit ?? 100,
+            catchUp: options.catchUp,
+            beforeN: options.beforeN,
+            afterN: options.afterN,
+            ...(options.alias.length ? { aliases: options.alias } : {}),
+            ...(options.contextQuery.length ? { keywords: options.contextQuery } : {}),
+            ...(options.contact.length ? { people: options.contact } : {}),
+            ...(options.maxPages === undefined ? {} : { maxReads: options.maxPages }),
+            ...(options.cursor === undefined ? {} : { checkpoint: options.cursor }),
+            ...(fetcher ? { fetcher, maxFetchMs, onFetchProgress: progressNote(context.renderer.note) } : {}),
+        }));
+        const fetcher = options.syncFirst
+            ? archiveFetcher((work) => context.withServices(work, { name: "projects evidence fetch" }), messenger)
+            : undefined;
+        const found = await context.withStore((store, account) => gather(store, account, fetcher));
+        const parts = projectAnswerParts(options.sinceTime, found);
+        renderAnswer(this, context, itemOf(snakeKeys(found), parts), () => projectEvidenceText(found, {
+            sync: (one, since) => one.provider === messenger.provider
+                ? lineOf(this, `projects evidence ${quote(project)} --since-time ${since} --sync-first`)
+                : null,
+            showDocument: "the notes app that imported it",
+        }));
+    }));
+    return projects;
+};
+const quote = (text) => (/^[\w:.-]+$/.test(text) ? text : `"${text.replace(/(["\\$`])/g, "\\$1")}"`);
+/** A line per saved page, counts only; a timed heartbeat with titles is the sync-progress work's (cli-core#2121). */
+const progressNote = (note) => ({ chat, index, of, fetched }) => note(`chat ${index + 1} of ${of} · ${chat} · ${fetched} messages so far`);

package/dist/cli/project-evidence.d.ts

@@ -0,0 +1,50 @@
+import type { StoredProjectGathering } from "../services/stored-project-gathering.js";
+/** Days back (`90d`) or a start date (`2026-09-01`); either way the run freezes its end, so a resume keeps it. */
+export declare const projectWindowOf: (value: string) => {
+    days: number;
+} | {
+    after: number;
+};
+export declare const projectCutoffTime: (value: string) => number;
+/**
+ * The zone a typed start date was read in, and the window the run used, in UTC. `complete` is "the answer is whole":
+ * reads finished and every linked chat held in full; the answer's own `complete` stays "reads finished".
+ */
+export declare const projectAnswerParts: (sinceTime: string, found: StoredProjectGathering) => {
+    next?: ({
+        kind: "command";
+        step: string;
+        command: string;
+        args: {
+            [x: string]: unknown;
+        };
+        line?: string | undefined;
+        why: string;
+        safe_to_auto_execute: boolean;
+    } | {
+        kind: "user_action";
+        step: string;
+        why: string;
+        safe_to_auto_execute: false;
+    })[] | undefined;
+    missing?: {
+        field: string;
+        why: string;
+        step?: string | undefined;
+    }[] | undefined;
+    meta: {
+        timezone?: string | undefined;
+        window: {
+            since: string;
+            until: string;
+        };
+        complete: boolean;
+    };
+};
+export interface ProjectTextHints {
+    /** The command that syncs one linked chat back to `since` (`YYYY-MM-DD`), or null when no command here can. */
+    sync: (chat: StoredProjectGathering["linkedChats"][number], since: string) => string | null;
+    /** How to open a document too large to read here. */
+    showDocument: string;
+}
+export declare const projectEvidenceText: (found: StoredProjectGathering, hints: ProjectTextHints) => string;

package/dist/cli/project-evidence.js

@@ -0,0 +1,142 @@
+import { CliError } from "@wirecat/cli-base";
+import * as v from "valibot";
+import { dateWindow, momentOf } from "../services/moment.js";
+import { coverageGaps } from "./messenger/search-answers.js";
+/** Days back (`90d`) or a start date (`2026-09-01`); either way the run freezes its end, so a resume keeps it. */
+export const projectWindowOf = (value) => {
+    const days = /^([1-9]\d{0,2})d$/.exec(value)?.[1];
+    if (days !== undefined && Number(days) <= 730)
+        return { days: Number(days) };
+    if (/^\d{4}-\d{2}-\d{2}(T[\d:.]+(Z|[+-]\d{2}:\d{2})?)?$/.test(value))
+        return { after: momentOf(value, "--since-time") };
+    throw new CliError("validation_error", `--since-time takes 1d to 730d or a date, such as 90d or 2026-09-01 — not ${value}`, { param: "since_time" });
+};
+export const projectCutoffTime = (value) => {
+    const parsed = v.safeParse(v.pipe(v.string(), v.isoTimestamp()), value);
+    const at = parsed.success ? Date.parse(parsed.output) : Number.NaN;
+    const date = parsed.success ? Date.parse(`${parsed.output.slice(0, 10)}T00:00:00.000Z`) : Number.NaN;
+    if (!parsed.success ||
+        !/(Z|[+-]\d{2}:\d{2})$/.test(parsed.output) ||
+        !Number.isFinite(at) ||
+        at < 1 ||
+        !Number.isFinite(date) ||
+        new Date(date).toISOString().slice(0, 10) !== parsed.output.slice(0, 10))
+        throw new CliError("validation_error", "--before-time needs a real ISO 8601 timestamp with a UTC offset", {
+            param: "before_time",
+        });
+    return at;
+};
+const coverageRows = ({ linkedChats }) => linkedChats.flatMap((one) => one.completeness === null || one.held === null
+    ? []
+    : [{ chatId: one.chat, title: one.title, completeness: one.completeness, held: one.held }]);
+/**
+ * The zone a typed start date was read in, and the window the run used, in UTC. `complete` is "the answer is whole":
+ * reads finished and every linked chat held in full; the answer's own `complete` stays "reads finished".
+ */
+export const projectAnswerParts = (sinceTime, found) => {
+    const { window } = found;
+    const { timezone } = dateWindow({ sinceTime }).meta;
+    const { next, missing } = coverageGaps(coverageRows(found), 0, new Date(window.after).toISOString());
+    return {
+        ...(next.length ? { next } : {}),
+        ...(missing.length ? { missing } : {}),
+        meta: {
+            ...(timezone === undefined ? {} : { timezone }),
+            window: { since: new Date(window.after).toISOString(), until: new Date(window.before).toISOString() },
+            complete: found.complete && found.completeness === "complete",
+        },
+    };
+};
+const LABELS = {
+    "person-only": "  [person only]",
+    sender: "  [sent by contact]",
+    "linked-chat": "  [linked chat]",
+};
+const day = (at) => new Date(at).toISOString().slice(0, 10);
+const FETCH_STATES = {
+    complete: "synced",
+    partial: "synced in part",
+    failed: "not synced",
+    skipped: "not synced, the fetch time ran out first",
+};
+export const projectEvidenceText = (found, hints) => {
+    const lanes = new Map(found.lanes.map((lane) => [
+        lane.id,
+        `${lane.query ?? lane.chat ?? `what ${lane.people.join(", ")} wrote`} (${lane.kinds.join(", ")})`,
+    ]));
+    const linked = found.items.filter((item) => item.context === "linked-chat").length;
+    const sent = found.items.filter((item) => item.context === "sender").length;
+    const unreadSenders = found.lanes.filter((lane) => lane.kinds.includes("sender") && !found.units.some((unit) => unit.lane === lane.id));
+    const failed = found.units.filter((unit) => unit.state === "failed" || unit.state === "unavailable");
+    const lines = [
+        `${found.project.name}${found.projectRef ? ` — ${found.projectRef}` : ""}: ${found.items.length} new references, ` +
+            `${day(found.window.after)} to ${day(found.window.before)}, ${found.scope.sources.length} sources`,
+        `as of: ${new Date(found.window.asOf).toISOString()} (exclusive end; reuse --before-time to repeat this window)`,
+        `searched: ${[...lanes.values()].join("; ")}`,
+        ...found.items.map((item) => `${day(item.at)}  ${item.ref}${LABELS[item.context] ?? ""}\n    ${item.text}` +
+            (item.around ?? [])
+                .map((one) => `\n      ${one.found ? "(hit) " : ""}${one.sender ? `${one.sender}: ` : ""}${one.text}`)
+                .join("")),
+    ];
+    const people = found.people.slice(0, 8);
+    const morePeople = found.people.length - people.length + found.peopleOmitted;
+    if (people.length)
+        lines.push(`people who wrote these: ${people.map((one) => `${one.name} (${one.items})`).join(", ")}` +
+            `${morePeople ? ` and ${morePeople} more` : ""} — by stored contact, not by names in the text; yours left out`);
+    if (linked)
+        lines.push(`${linked} of these come from the project's linked chats and name nothing: membership, not a word match`);
+    if (sent)
+        lines.push(`${sent} of these were written by a contact and may name nothing: matched by sender, not words`);
+    for (const lane of unreadSenders)
+        lines.push(`${lane.people.join(", ")}: no stored identity in the selected sources, so nothing they wrote was read`);
+    if (found.mentions.items.length)
+        lines.push(`also names: ${found.mentions.items
+            .slice(0, 8)
+            .map((one) => `${one.target.kind} ${one.target.name} (${one.matches.length})`)
+            .join(", ")} — words found, not membership`);
+    if (found.matchedAgain.length)
+        lines.push(`${found.matchedAgain.length} earlier references found again`);
+    if (found.oversized.length)
+        lines.push(`too large to read here: ${found.oversized.map((one) => `${one.ref} (${Math.ceil(one.bytes / 1024)} KiB)`).join(", ")}` +
+            ` — open each with ${hints.showDocument}`);
+    if (failed.length)
+        lines.push(`${failed.length} reads failed or had no source: see --json units`);
+    if (found.index.state === "failed" || found.index.state === "unavailable")
+        lines.push(`the search index could not be brought up to date first (${found.index.code ?? found.index.state})`);
+    const pending = [
+        ...new Set(found.units.filter((unit) => unit.issue?.startsWith("index-")).map((unit) => found.scope.sources[unit.source])),
+    ];
+    if (pending.length)
+        lines.push(`not yet searchable: new text in ${pending.map((one) => `${one?.provider}:${one?.account}`).join(", ")} ` +
+            "is still waiting for the search index, so it was not found");
+    if (pending.some((one) => one?.kind === "mail" || one?.kind === "document") && found.index.state === "as-is")
+        lines.push("leave out --no-catch-up to index new mail and documents first");
+    if (pending.some((one) => one?.kind === "meeting"))
+        lines.push("index stored transcript cues through the meeting provider's indexing workflow; mail/document catch-up does not index them");
+    if (found.unreadSources.length)
+        lines.push(`not read: ${found.unreadSources
+            .map((one) => `${one.source} (${one.kind}${one.reason ? `, ${one.reason}` : ""})`)
+            .join(", ")}`);
+    for (const one of found.fetch)
+        lines.push(`${one.chat}: ${FETCH_STATES[one.state] ?? one.state} before reading` +
+            `${one.reason && one.state !== "skipped" ? ` (${one.reason})` : ""}`);
+    const held = (one) => one.completeness?.state === "unknown" || !one.held?.oldestAt
+        ? "never fetched"
+        : `held from ${one.held.oldestAt.slice(0, 10)} only`;
+    for (const one of found.linkedChats)
+        if (one.completeness !== null && one.completeness.state !== "complete") {
+            const sync = hints.sync(one, day(found.window.after));
+            lines.push(`${one.title ?? one.ref}: ${held(one)}${one.state === "pending" ? ", not read this run" : ""}` +
+                (sync ? ` — sync it: ${sync}` : ""));
+        }
+    const capped = found.linkedChats.filter((one) => one.capped);
+    if (capped.length)
+        lines.push(`linked chats with more to read, left for --cursor so one chat does not fill the run: ${capped
+            .map((one) => `${one.ref} (${one.items} this run)`)
+            .join(", ")}`);
+    if (found.checkpoint)
+        lines.push(`stopped${found.stopped ? ` at the ${found.stopped} budget` : ""}; continue with the same options and`, `--cursor ${found.checkpoint}`);
+    else
+        lines.push("every read finished; a finished search does not prove there is nothing more");
+    return lines.join("\n");
+};

package/dist/cli/shared-command-exports.d.ts

@@ -775,6 +775,7 @@ export declare const tagsCommand: (messenger: import("./index.js").Messenger) =>
 export declare const tasksCommand: (messenger: import("./index.js").Messenger) => import("commander").Command;
 export declare const tasksStatsCommand: (messenger: import("./index.js").Messenger) => import("commander").Command;
 export declare const topicsCommand: (messenger: import("./index.js").Messenger) => import("commander").Command;
+export declare const projectsCommand: (messenger: import("./index.js").Messenger) => import("commander").Command;
 export declare const watchCommand: (messenger: import("./index.js").Messenger) => import("commander").Command;
 export declare const runsCommand: (app: import("./entry.js").AppIdentity) => import("commander").Command;
 export declare const skillCommand: (app: import("./entry.js").AppIdentity, skill: URL) => import("commander").Command;

package/dist/cli/shared-command-exports.js

@@ -36,6 +36,7 @@ import { pinCommand as pinCommandDefinition, starCommands as starCommandsDefinit
 import { metadataCommand as metadataCommandDefinition } from "./messenger/metadata-command.js";
 import { modelsCommand as modelsCommandDefinition } from "./messenger/models-command.js";
 import { pollsCommand as pollsCommandDefinition } from "./messenger/polls-command.js";
+import { projectsCommand as projectsCommandDefinition } from "./messenger/projects-command.js";
 import { reactionsCommand as reactionsCommandDefinition } from "./messenger/reactions-command.js";
 import { callsCommand as callsCommandDefinition, stickersCommand as stickersCommandDefinition, } from "./messenger/records-command.js";
 import { repliesCommand as repliesCommandDefinition } from "./messenger/replies-command.js";
@@ -112,6 +113,7 @@ export const tagsCommand = sharedCommand(tagsCommandDefinition);
 export const tasksCommand = sharedCommand(tasksCommandDefinition);
 export const tasksStatsCommand = sharedCommand(tasksStatsCommandDefinition);
 export const topicsCommand = sharedCommand(topicsCommandDefinition);
+export const projectsCommand = sharedCommand(projectsCommandDefinition);
 export const watchCommand = sharedCommand(watchCommandDefinition);
 export const runsCommand = sharedCommand(runsCommandDefinition);
 export const skillCommand = sharedCommand(skillCommandDefinition);

package/dist/errors/reasons.js

@@ -88,6 +88,7 @@ const OTHERS = [
     validation("memory.evidence-required", "a memory needs its evidence"),
     validation("memory.scope-required", "a memory needs its scope"),
     ["model.not-downloaded", "not_found", "the model is not downloaded on this machine"],
+    ["person.no-owner", "not_found", "no person is marked as the owner in the store"],
     ["transcription.no-key", "authentication_error", "no OpenAI key is set for transcription"],
     validation("transcription.too-large", "the audio is over the transcription provider's size limit"),
     [

package/dist/sends/permissions.js

@@ -322,7 +322,7 @@ const HOUSEKEEPING = new Set([
 const BOT_HOUSEKEEPING = new Set(["auth", "list", "sends", "recipients", "mcp"]);
 const STORE_MAINTENANCE = new Set(["info", "check", "copies"]);
 /** Commands outside `messages` that print what people wrote, so `deny messages` reaches them too. */
-const SHOW_MESSAGES = new Set(["inbox", "review", "watch", "serve", "store", "conversations"]);
+const SHOW_MESSAGES = new Set(["inbox", "review", "watch", "serve", "store", "conversations", "projects"]);
 export const readKeysForCommand = (path) => {
     if (path[0] === "bot")
         return readKeysForCommand(path.slice(1)).map((key) => `bot.${key}`);

package/dist/services/index.d.ts

@@ -9,13 +9,14 @@ export type { MediaArchiveEntry, MediaIdentity } from "./media-archive-manifest.
 export type { MoveMediaArchiveOptions } from "./media-archive-move.js";
 export { moveMediaArchive } from "./media-archive-move.js";
 export { type DownloadedModel, downloadImageModel, downloadTextModel, type ModelDownloadOptions, } from "./model-downloads.js";
-export type { ProjectEvidenceContext, ProjectEvidenceItem, ProjectEvidencePerson, ProjectGathering, ProjectGatheringPorts, ProjectGatheringStop, ProjectIndexCatchUp, ProjectSourceFetcher, } from "./project-gathering.js";
+export type { ProjectChatFetcher, ProjectChatFetchProgress, ProjectChatFetchRequest, ProjectEvidenceContext, ProjectEvidenceItem, ProjectEvidencePerson, ProjectGathering, ProjectGatheringPorts, ProjectGatheringStop, ProjectIndexCatchUp, } from "./project-gathering.js";
 export { gatherProjectEvidence } from "./project-gathering.js";
 export type { ProjectNeighbour, ProjectNeighbourReader } from "./project-gathering-around.js";
 export { documentPassage, storedMessageNeighbours, storedNeighbours } from "./project-gathering-around.js";
 export type { EvidenceMention, EvidenceMentions } from "./project-gathering-mentions.js";
 export { findEvidenceMentions } from "./project-gathering-mentions.js";
-export type { ProjectFetchState, ProjectGatheringBudgets, ProjectGatheringRequest, ProjectLane, ProjectLaneKind, ProjectLinkedChat, ProjectPerson, ProjectSender, ProjectUnitState, } from "./project-gathering-request.js";
+export type { ProjectChatFetched, ProjectGatheringBudgets, ProjectGatheringRequest, ProjectLane, ProjectLaneKind, ProjectLinkedChat, ProjectPerson, ProjectSender, ProjectUnitState, } from "./project-gathering-request.js";
+export { canonicalProjectRef, gatherStoredProject, type StoredProjectGathering, type StoredProjectInput, } from "./stored-project-gathering.js";
 import { type AccountService } from "./account.js";
 import { type AdminService } from "./admin.js";
 import { type AdminStatisticsService } from "./admin-statistics.js";

package/dist/services/index.js

@@ -8,6 +8,7 @@ export { downloadImageModel, downloadTextModel, } from "./model-downloads.js";
 export { gatherProjectEvidence } from "./project-gathering.js";
 export { documentPassage, storedMessageNeighbours, storedNeighbours } from "./project-gathering-around.js";
 export { findEvidenceMentions } from "./project-gathering-mentions.js";
+export { canonicalProjectRef, gatherStoredProject, } from "./stored-project-gathering.js";
 import { accountService } from "./account.js";
 import { adminService } from "./admin.js";
 import { adminStatisticsService } from "./admin-statistics.js";

package/dist/services/project-gathering-request.d.ts

@@ -52,6 +52,8 @@ export interface ProjectGatheringBudgets {
     maxPageBytes?: number;
     maxElapsedMs?: number;
     maxItems?: number;
+    /** All `fetch: before-read` chat fetches together. */
+    maxFetchMs?: number;
 }
 export type ProjectLaneKind = "project" | "key" | "alias" | "keyword" | "person" | "sender" | "linked-chat";
 export interface ProjectLane {
@@ -76,7 +78,13 @@ export interface ProjectUnitProgress {
     } | null;
     code: string | null;
 }
-export type ProjectFetchState = "fetched" | "unsupported" | "failed" | "not-requested";
+/** A linked chat's fetch before the reads: `skipped` when the budget ran out before it started. */
+export interface ProjectChatFetched {
+    chat: string;
+    state: "complete" | "partial" | "failed" | "skipped";
+    reason: string | null;
+    elapsedMs: number;
+}
 export interface ProjectGatheringCheckpoint {
     version: 1;
     runKey: string;
@@ -84,11 +92,8 @@ export interface ProjectGatheringCheckpoint {
     after: number;
     before: number;
     asOf: number;
-    fetched: {
-        state: ProjectFetchState;
-        history: "complete" | "partial" | "unknown" | null;
-        code: string | null;
-    }[];
+    /** The first invocation's chat fetches, carried so a resumed run reports them without fetching again. */
+    fetched: ProjectChatFetched[];
     units: ProjectUnitProgress[];
     /** Present only when the run reads linked chats: a hash of their references. */
     linkedChats?: string;

package/dist/services/project-gathering-request.js

@@ -21,6 +21,7 @@ const BUDGETS = {
     maxPageBytes: [65536, 262144],
     maxElapsedMs: [60000, 600000],
     maxItems: [100, 500],
+    maxFetchMs: [180000, 1800000],
 };
 const fail = (message, param) => {
     throw new CliError("validation_error", message, param ? { param } : undefined);

package/dist/services/project-gathering.d.ts

@@ -2,22 +2,38 @@ import type { ContextEvidenceItem, ContextEvidenceReader, ContextIndex, ContextS
 import type { AccountKey } from "../store/types.js";
 import type { ChatCoverage } from "./chat-coverage.js";
 import { type ProjectNeighbour, type ProjectNeighbourReader } from "./project-gathering-around.js";
-import { type ProjectFetchState, type ProjectGatheringRequest, type ProjectLane } from "./project-gathering-request.js";
-/** A connector's history fetch into the store; the store reads that follow find what it saved. */
-export interface ProjectSourceFetcher {
-    fetch(request: {
-        source: ContextSource;
-        after: number;
-        before: number;
-        signal?: AbortSignal;
-    }): Promise<{
-        status: "fetched" | "unsupported";
-        history: "complete" | "partial" | "unknown";
+import { type ProjectChatFetched, type ProjectGatheringRequest, type ProjectLane } from "./project-gathering-request.js";
+/** One linked chat's history into the store, back to `after`; the reads that follow find what it saved. */
+export interface ProjectChatFetchRequest {
+    account: AccountKey;
+    chatId: string;
+    after: number;
+    before: number;
+    /** Aborts when the run's fetch budget is spent; a fetcher stops there and keeps what it saved. */
+    signal: AbortSignal;
+    /** When that budget ends, by the run's clock: a fetcher that runs a process gives it this much time to stop itself. */
+    until: number;
+    onProgress?: (progress: ProjectChatFetchProgress) => void;
+}
+export interface ProjectChatFetchProgress {
+    fetched: number;
+    oldest: number | null;
+}
+export interface ProjectChatFetcher {
+    fetch(request: ProjectChatFetchRequest): Promise<{
+        state: "complete" | "partial" | "failed";
+        reason?: string;
     }>;
 }
 export interface ProjectGatheringPorts {
     evidence: ContextEvidenceReader;
-    fetcher?: ProjectSourceFetcher;
+    fetcher?: ProjectChatFetcher;
+    /** Each linked chat's fetch as it goes, for a heartbeat; never message text. */
+    onFetchProgress?: (progress: ProjectChatFetchProgress & {
+        chat: string;
+        index: number;
+        of: number;
+    }) => void;
     index?: ContextIndex;
     neighbours?: ProjectNeighbourReader;
     /** What the store holds of the named chats of one account, e.g. `chatCoverage` over the store. */
@@ -103,12 +119,7 @@ export declare const gatherProjectEvidence: (ports: ProjectGatheringPorts, reque
         items?: number | undefined;
         capped?: boolean | undefined;
     }[];
-    fetch: {
-        state: ProjectFetchState;
-        history: "complete" | "partial" | "unknown" | null;
-        code: string | null;
-        source: number;
-    }[];
+    fetch: ProjectChatFetched[];
     index: ProjectIndexCatchUp;
     units: {
         lane: string;

package/dist/services/project-gathering.js

@@ -15,6 +15,84 @@ const contextOf = (lane) => lane.kinds.includes("linked-chat")
         : lane.kinds.every((k) => k === "person")
             ? "person-only"
             : "project";
+/** Complete, or up to date with no gaps and held back past the window start: nothing a fetch would add. */
+const heldForWindow = (row, after) => {
+    if (!row)
+        return false;
+    const { state, upToDate, gaps } = row.completeness;
+    if (state === "complete")
+        return upToDate !== false;
+    const oldest = row.held.oldestAt === null ? Number.NaN : Date.parse(row.held.oldestAt);
+    return upToDate === true && !gaps && oldest <= after;
+};
+/**
+ * Brings the linked chats the store does not hold for the window up to date, one at a time, inside one time budget
+ * for all of them. A chat cut by the budget stays partial and the next one is not started, so a run never waits
+ * longer than the budget whatever the fetcher does.
+ */
+const fetchLinkedChats = async (ports, plan, window, now, signal) => {
+    const wanted = [];
+    for (const linked of plan.linkedChats) {
+        if (linked.source === null)
+            continue;
+        const account = { provider: linked.provider, account: linked.account };
+        const [row] = await ports.coverage(account, [linked.chat]);
+        if (!heldForWindow(row, window.after))
+            wanted.push({ ...linked, account });
+    }
+    const deadline = now() + plan.budgets.maxFetchMs;
+    const results = [];
+    for (const [index, linked] of wanted.entries()) {
+        signal?.throwIfAborted();
+        const started = now();
+        const left = deadline - started;
+        if (left <= 0) {
+            results.push({ chat: linked.ref, state: "skipped", reason: "fetch-budget", elapsedMs: 0 });
+            continue;
+        }
+        const budget = new AbortController();
+        const timer = setTimeout(() => budget.abort(new CliError("timeout", "the fetch budget ran out")), left);
+        const onProgress = ports.onFetchProgress;
+        try {
+            const answer = await ports.fetcher.fetch({
+                account: linked.account,
+                chatId: linked.chat,
+                after: window.after,
+                before: window.before,
+                until: deadline,
+                signal: signal ? AbortSignal.any([signal, budget.signal]) : budget.signal,
+                ...(onProgress
+                    ? { onProgress: (progress) => onProgress({ ...progress, chat: linked.ref, index, of: wanted.length }) }
+                    : {}),
+            });
+            if (!["complete", "partial", "failed"].includes(answer?.state))
+                throw new CliError("invalid_response", "chat fetch returned an unknown state");
+            const cut = budget.signal.aborted || now() > deadline;
+            results.push({
+                chat: linked.ref,
+                state: cut && answer.state === "complete" ? "partial" : answer.state,
+                reason: answer.reason ?? (cut && answer.state !== "failed" ? "fetch-budget" : null),
+                elapsedMs: now() - started,
+            });
+        }
+        catch (error) {
+            signal?.throwIfAborted();
+            if (!(error instanceof CliError))
+                throw error;
+            const cut = budget.signal.aborted;
+            results.push({
+                chat: linked.ref,
+                state: cut ? "partial" : "failed",
+                reason: cut ? "fetch-budget" : error.code,
+                elapsedMs: now() - started,
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    return results;
+};
 export const gatherProjectEvidence = async (ports, request) => {
     if (!ports?.evidence || typeof ports.evidence.read !== "function")
         throw new CliError("configuration_error", "stored context reads are unavailable in this store");
@@ -27,38 +105,22 @@ export const gatherProjectEvidence = async (ports, request) => {
     // A default that cannot finish one round would leave whole searches or sources unread; an explicit one is kept.
     if (request.budgets?.maxReads === undefined)
         plan.budgets.maxReads = Math.min(512, Math.max(48, units.length));
-    if (previous && (previous.units.length !== units.length || previous.fetched.length !== plan.sources.length))
+    if (previous && previous.units.length !== units.length)
         throw new CliError("validation_error", "invalid project gathering checkpoint", { param: "checkpoint" });
     const progress = previous?.units.map((u) => ({ ...u })) ??
         units.map(() => ({ state: "pending", pages: 0, cursor: null, code: null }));
-    const fetched = previous?.fetched.map((f) => ({ ...f })) ??
-        plan.sources.map(() => ({ state: "not-requested", history: null, code: null }));
+    let fetched = previous?.fetched.map((f) => ({ ...f })) ?? [];
     const seen = new Set(previous?.seen ?? []);
     const signal = plan.signal;
     const queries = plan.lanes.flatMap((lane) => (lane.query === null ? [] : [lane.query]));
-    if (plan.fetch === "before-read" && !ports.fetcher)
-        throw new CliError("configuration_error", "this host cannot fetch source history; use fetch none", {
+    if (plan.fetch === "before-read" && (!ports.fetcher || !ports.coverage))
+        throw new CliError("configuration_error", "this host cannot fetch chat history; use fetch none", {
             param: "fetch",
         });
-    if (plan.fetch === "before-read" && ports.fetcher)
-        for (const [index, source] of plan.sources.entries()) {
-            if (fetched[index]?.state !== "not-requested")
-                continue;
-            signal?.throwIfAborted();
-            try {
-                const answer = await ports.fetcher.fetch({ source, after: window.after, before: window.before, signal });
-                if (!["fetched", "unsupported"].includes(answer?.status) ||
-                    !["complete", "partial", "unknown"].includes(answer?.history))
-                    throw new CliError("invalid_response", "source fetch returned an unknown status");
-                fetched[index] = { state: answer.status, history: answer.history, code: null };
-            }
-            catch (error) {
-                signal?.throwIfAborted();
-                if (!(error instanceof CliError))
-                    throw error;
-                fetched[index] = { state: "failed", history: null, code: error.code };
-            }
-        }
+    if (plan.fetch === "before-read" && ports.fetcher && ports.coverage && previous === null)
+        fetched = await fetchLinkedChats(ports, plan, window, now, signal);
+    // The fetch has its own budget; the reads keep theirs whole.
+    const readFrom = now();
     const indexed = { state: "as-is", mail: 0, documents: 0, code: null };
     const kinds = [...new Set(plan.sources.map((source) => source.kind))].filter((kind) => kind !== "message");
     if (plan.index === "update" && kinds.length) {
@@ -173,7 +235,7 @@ export const gatherProjectEvidence = async (ports, request) => {
                     ? "reads"
                     : usage.readBytes >= plan.budgets.maxReadBytes
                         ? "read-bytes"
-                        : now() - started >= plan.budgets.maxElapsedMs
+                        : now() - readFrom >= plan.budgets.maxElapsedMs
                             ? "elapsed"
                             : usage.items >= plan.budgets.maxItems
                                 ? "items"
@@ -348,7 +410,7 @@ export const gatherProjectEvidence = async (ports, request) => {
         scope: { origin: plan.scope, sources: plan.sources },
         lanes: plan.lanes,
         linkedChats: linkedRows,
-        fetch: fetched.map((f, index) => ({ source: index, ...f })),
+        fetch: fetched,
         index: indexed,
         units: units.map((unit, index) => ({
             lane: unit.lane.id,

package/dist/services/stored-project-gathering.d.ts

@@ -0,0 +1,50 @@
+import type { ContextSource } from "../context/evidence.js";
+import type { MessageStore } from "../store/store.js";
+import { gatherProjectEvidence, type ProjectChatFetcher, type ProjectGatheringPorts } from "./project-gathering.js";
+import { type EvidenceMentions } from "./project-gathering-mentions.js";
+export interface StoredProjectInput {
+    project: string;
+    /** The sources the host resolved from its `--source`, and those it could not read. */
+    sources: {
+        sources: ContextSource[];
+        unread: {
+            source: string;
+            kind: string;
+            reason?: "unknown-provider" | "out-of-scope";
+        }[];
+        scope: "explicit" | "all-connected";
+    };
+    aliases?: string[];
+    keywords?: string[];
+    people?: string[];
+    days?: number;
+    after?: number;
+    asOf?: number;
+    checkpoint?: string;
+    maxReads?: number;
+    limit?: number;
+    catchUp?: boolean;
+    beforeN?: number;
+    afterN?: number;
+    /** Syncs the linked chats the store does not hold for the window before reading; off when left out. */
+    fetcher?: ProjectChatFetcher;
+    maxFetchMs?: number;
+    onFetchProgress?: ProjectGatheringPorts["onFetchProgress"];
+    signal?: AbortSignal;
+}
+/** `project:<id>`, or the one project a key, name or alias names; several or none is refused, never guessed. */
+export declare const canonicalProjectRef: (store: MessageStore, reference: string) => Promise<string>;
+export type StoredProjectGathering = Awaited<ReturnType<typeof gatherProjectEvidence>> & {
+    projectRef: string | null;
+    unreadSources: {
+        source: string;
+        kind: string;
+        reason?: "out-of-scope" | "linked-chat-limit" | "member-limit" | "no-identity" | "unknown-provider";
+    }[];
+    mentions: EvidenceMentions;
+};
+/**
+ * `projects evidence` over a whole store: the project's names, key and aliases, the given words and contacts, its
+ * confirmed person members and its confirmed linked chats, in the sources the host resolved.
+ */
+export declare const gatherStoredProject: (store: MessageStore, input: StoredProjectInput) => Promise<StoredProjectGathering>;

package/dist/services/stored-project-gathering.js

@@ -0,0 +1,207 @@
+import { CliError } from "@wirecat/cli-base";
+import { formatReference, parseReference } from "../domain/references.js";
+import { chatCoverage } from "./chat-coverage.js";
+import { gatherProjectEvidence } from "./project-gathering.js";
+import { storedNeighbours } from "./project-gathering-around.js";
+import { findEvidenceMentions } from "./project-gathering-mentions.js";
+const PROJECT_ID = /^project:[1-9]\d*$/;
+/** `project:<id>`, or the one project a key, name or alias names; several or none is refused, never guessed. */
+export const canonicalProjectRef = async (store, reference) => {
+    if (PROJECT_ID.test(reference)) {
+        const catalog = await store.knowledge.vocabulary({ kind: "project" });
+        if (!catalog.entries.some((entry) => entry.id === reference.slice(8)))
+            throw new CliError("not_found", "the owner project is unavailable");
+        return reference;
+    }
+    const found = await store.knowledge.resolveVocabulary(reference, { kind: "project" });
+    const [entry] = found.matches;
+    if (found.matches.length !== 1 || !entry)
+        throw new CliError(found.matches.length ? "validation_error" : "not_found", found.matches.length
+            ? `${reference} names ${found.matches.length} projects; give one by its key or project:<id>`
+            : `no project ${reference}`, { candidates: found.matches.map((one) => ({ id: one.id, key: one.key, name: one.name })) });
+    return `project:${entry.id}`;
+};
+/**
+ * An existing project brings its name and aliases; any other name is gathered as given. An id that names no
+ * project, or a name that matches several, is refused rather than guessed.
+ */
+const projectOf = async (store, reference) => {
+    const id = /^(project:)?[1-9]\d*$/.test(reference);
+    let ref;
+    try {
+        ref = await canonicalProjectRef(store, id && !reference.startsWith("project:") ? `project:${reference}` : reference);
+    }
+    catch (error) {
+        if (!id && error instanceof CliError && error.code === "not_found")
+            return { ref: null, name: reference, key: null, aliases: [] };
+        throw error;
+    }
+    const entry = (await store.knowledge.vocabulary({ kind: "project" })).entries.find((one) => one.id === ref.slice(8));
+    if (!entry)
+        throw new CliError("not_found", "the owner project is unavailable");
+    return { ref, name: entry.name, key: entry.key, aliases: entry.aliases.map((alias) => alias.name) };
+};
+/** `person:me` as the owner's `person:<uid>`; any other reference as written. */
+const withOwner = async (store, reference) => {
+    if (reference.trim() !== "person:me")
+        return reference;
+    const owner = await store.people.owner();
+    if (owner === undefined || owner.identities.length === 0)
+        throw new CliError("not_found", "person:me: no person is marked as you in the store; mark yours with `<messenger> <profile> contacts link <your id> me`", { reason: "person.no-owner" });
+    return `person:${owner.uid}`;
+};
+const sendersOf = (person) => person.identities.map((identity) => ({ provider: identity.provider, id: String(identity.id) }));
+/**
+ * A `person:<id>` is read by what their stored identities wrote, and searched only by the short names the owner gave
+ * them: their stored name is a messenger display name («Степа Stefan Grachev AVITO M A») that no message spells out.
+ * Any other text is a name.
+ */
+const contactOf = async (store, contact) => {
+    const reference = await withOwner(store, contact);
+    if (!reference.startsWith("person:"))
+        return [{ name: contact }];
+    const person = await store.people.personByUid(reference.slice("person:".length));
+    if (!person)
+        throw new CliError("not_found", `no person ${contact}`, { param: "contact" });
+    const senders = sendersOf(person);
+    const aliases = new Set();
+    for (const identity of person.identities)
+        for (const account of identity.accounts) {
+            const alias = await store.people
+                .privateContact({ provider: identity.provider, account }, identity.id)
+                .then((one) => one.alias)
+                .catch((error) => {
+                if (error instanceof CliError && error.code === "not_found")
+                    return null;
+                throw error;
+            });
+            if (alias)
+                aliases.add(alias);
+        }
+    if (!senders.length && !aliases.size)
+        throw new CliError("validation_error", `${contact} has no stored identity or alias to search by; pass a name the texts use to --contact`, { param: "contact" });
+    const names = [...aliases].map((name) => ({ name, reference: contact }));
+    return senders.length ? [{ reference: contact, senders }, ...names] : names;
+};
+const LINKED_CHATS = 16;
+const CORE_LIMIT = 16;
+/** Confirmed `person` members, in a stable order, so a cut at the lane limit always drops the same ones. */
+const memberRefsOf = async (store, project) => {
+    if (!project)
+        return [];
+    const refs = [];
+    for (const relation of await store.knowledge.relations(null, project))
+        if (relation.confirmed &&
+            relation.kind === "member-of" &&
+            relation.to === project &&
+            /^person:.+/.test(relation.from))
+            refs.push(relation.from);
+    return [...new Set(refs)].sort();
+};
+/**
+ * Members are read by what their identities wrote, like `--contact person:<id>` but without the owner's aliases:
+ * a short alias would add a text lane that matches mentions, and membership is about who wrote, not who was named.
+ */
+const memberLanesOf = async (store, project, given, room) => {
+    const lanes = [];
+    const left = [];
+    for (const reference of (await memberRefsOf(store, project)).filter((one) => !given.has(one))) {
+        const person = await store.people.personByUid(reference.slice("person:".length));
+        const senders = person ? sendersOf(person) : [];
+        if (!senders.length)
+            left.push({ source: reference, kind: "member", reason: "no-identity" });
+        else if (lanes.length >= room)
+            left.push({ source: reference, kind: "member", reason: "member-limit" });
+        else
+            lanes.push({ reference, senders });
+    }
+    return { lanes, left };
+};
+/** Only links the owner confirmed: a suggested one would put a whole chat into the evidence on a guess. */
+const linkedChatsOf = async (store, project) => {
+    if (!project)
+        return [];
+    const chats = [];
+    for (const relation of await store.knowledge.relations(null, project)) {
+        if (!relation.confirmed || relation.kind !== "member-of" || relation.to !== project)
+            continue;
+        if (!relation.from.startsWith("chat:"))
+            continue;
+        const reference = parseReference(relation.from);
+        if (reference.type === "chat")
+            chats.push(reference);
+    }
+    return chats.map(({ provider, account, chat }) => ({ provider, account, chat }));
+};
+/**
+ * `projects evidence` over a whole store: the project's names, key and aliases, the given words and contacts, its
+ * confirmed person members and its confirmed linked chats, in the sources the host resolved.
+ */
+export const gatherStoredProject = async (store, input) => {
+    if (input.asOf !== undefined && input.after !== undefined && input.asOf <= input.after)
+        throw new CliError("validation_error", "--before-time must be later than --since-time", { param: "before_time" });
+    if (!store.contextEvidence)
+        throw new CliError("configuration_error", "Stored context reads are unavailable in this store");
+    const project = await projectOf(store, input.project);
+    const { sources, unread, scope } = input.sources;
+    if (sources.length === 0)
+        throw new CliError("not_found", "no selected source holds anything to read", { param: "source" });
+    const contacts = (await Promise.all([...new Set(input.people ?? [])].map((contact) => contactOf(store, contact)))).flat();
+    const aliases = [...new Set([...project.aliases, ...(input.aliases ?? [])])].filter((alias) => alias !== project.name);
+    // Counted without merging look-alikes, so the room left for members is never more than Core will take.
+    const searchLanes = 1 +
+        (project.key ? 1 : 0) +
+        aliases.length +
+        (input.keywords?.length ?? 0) +
+        contacts.filter((one) => one.name).length;
+    const room = Math.min(CORE_LIMIT - contacts.length, CORE_LIMIT - searchLanes - contacts.filter((one) => one.senders).length);
+    const members = await memberLanesOf(store, project.ref, new Set(contacts.flatMap((one) => one.reference ?? [])), room);
+    const people = [...contacts, ...members.lanes];
+    const linked = await linkedChatsOf(store, project.ref);
+    const linkedChats = linked.slice(0, LINKED_CHATS);
+    const budgets = {
+        ...(input.maxReads === undefined ? {} : { maxReads: input.maxReads }),
+        ...(input.limit === undefined ? {} : { maxItems: input.limit }),
+        ...(input.maxFetchMs === undefined ? {} : { maxFetchMs: input.maxFetchMs }),
+    };
+    const gathered = await gatherProjectEvidence({
+        evidence: store.contextEvidence,
+        neighbours: storedNeighbours(store),
+        coverage: (account, chatIds) => chatCoverage(store, account, chatIds),
+        ...(store.contextIndex ? { index: store.contextIndex } : {}),
+        ...(input.fetcher ? { fetcher: input.fetcher } : {}),
+        ...(input.onFetchProgress ? { onFetchProgress: input.onFetchProgress } : {}),
+    }, {
+        project: {
+            name: project.name,
+            ...(project.key ? { key: project.key } : {}),
+            ...(aliases.length ? { aliases } : {}),
+        },
+        index: input.catchUp === false ? "as-is" : "update",
+        around: { before: input.beforeN ?? 2, after: input.afterN ?? 2 },
+        ...(input.keywords?.length ? { keywords: input.keywords } : {}),
+        ...(people.length ? { people } : {}),
+        ...(linkedChats.length ? { linkedChats } : {}),
+        ...(input.fetcher ? { fetch: "before-read" } : {}),
+        sources,
+        scope,
+        ...(input.days === undefined ? {} : { lookbackDays: input.days }),
+        ...(input.after === undefined ? {} : { after: input.after }),
+        ...(input.asOf === undefined ? {} : { asOf: input.asOf }),
+        ...(input.checkpoint === undefined ? {} : { checkpoint: input.checkpoint }),
+        ...(Object.keys(budgets).length ? { budgets } : {}),
+        ...(input.signal ? { signal: input.signal } : {}),
+    });
+    const mentions = await findEvidenceMentions(store.knowledge, gathered, { exclude: project.ref });
+    const unreadChats = [
+        ...gathered.linkedChats
+            .filter((one) => one.state === "out-of-scope")
+            .map((one) => ({ source: one.ref, kind: "linked-chat", reason: "out-of-scope" })),
+        ...linked.slice(LINKED_CHATS).map((one) => ({
+            source: formatReference({ type: "chat", ...one }),
+            kind: "linked-chat",
+            reason: "linked-chat-limit",
+        })),
+    ];
+    return { projectRef: project.ref, unreadSources: [...unread, ...unreadChats, ...members.left], ...gathered, mentions };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-core",
-  "version": "0.503.0",
+  "version": "0.505.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",