@wirecat/cli-core 0.516.0 → 0.517.0

package/CHANGELOG.md

@@ -7,6 +7,21 @@ shape of this file.
 
 ## Unreleased
 
+## 0.517.0 — 01.11.2026
+
+### Added
+
+- **`withSyncCommands(found, sync)`** gives each linked chat of a stored project gathering its `syncCommand`: the
+  line the text names to sync a chat held in part, or null. tg's and max's `projects evidence --json` carry it as
+  `linked_chats[].sync_command`, so an agent reading JSON gets the command the text shows.
+
+### Fixed
+
+- **A chat that reaches its first message is no longer "held from <date> only"** in `missing`, `next` and the
+  `projects evidence` text: it is "held from its first message, behind since <date>", or "with gaps".
+- **`messages sync` progress says how far back it got as a date** ("back to 2026-09-27"), not as a message key, which
+  for MAX was a number of milliseconds.
+
 ## 0.516.0 — 01.11.2026
 
 ### Fixed

package/dist/cli/index.d.ts

@@ -109,7 +109,7 @@ 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 { type ProjectTextHints, projectAnswerParts, projectCutoffTime, projectEvidenceText, projectWindowOf, withSyncCommands, } 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";

package/dist/cli/index.js

@@ -99,7 +99,7 @@ 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 { projectAnswerParts, projectCutoffTime, projectEvidenceText, projectWindowOf, withSyncCommands, } 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";

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

@@ -7,7 +7,7 @@ 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 { projectAnswerParts, projectCutoffTime, projectEvidenceText, projectWindowOf, withSyncCommands, } from "../project-evidence.js";
 import { lineOf } from "../steps.js";
 import { messengerContext } from "./context.js";
 const collect = (value, previous) => [...previous, value];
@@ -120,12 +120,13 @@ export const projectsCommand = (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, {
+        const hints = {
             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",
-        }));
+        };
+        renderAnswer(this, context, itemOf(snakeKeys(withSyncCommands(found, hints.sync)), parts), () => projectEvidenceText(found, hints));
     }));
     return projects;
 };

package/dist/cli/messenger/search-answers.d.ts

@@ -18,6 +18,11 @@ export type HitItem = InferOutput<(typeof ENTITIES)["hit"]>;
 /** The page a `--page` asks for, as the offset the search services take. */
 export declare const offsetOf: (page: number | undefined, limit: number) => number | undefined;
 export declare const messageHitItem: (hit: FoundMessage, query?: string) => MessageHitItem;
+/**
+ * What the store holds of a chat that is not complete, in words. A chat that reaches its first message is only
+ * behind or has gaps: saying "held from <date> only" would claim older history is missing.
+ */
+export declare const heldPhrase: ({ completeness, held }: Pick<ChatCoverage, "completeness" | "held">) => string;
 /**
  * What the archive lacked for this answer, and the step that would fill it. From a search's coverage, or from the
  * chats an answer is about (`since` is the start of the window it was asked for).

package/dist/cli/messenger/search-answers.js

@@ -96,6 +96,19 @@ const metaOf = (accounts, skipped = [], heldInPart = false) => ({
         : {}),
 });
 const day = (at) => at?.slice(0, 10) ?? "no date";
+/**
+ * What the store holds of a chat that is not complete, in words. A chat that reaches its first message is only
+ * behind or has gaps: saying "held from <date> only" would claim older history is missing.
+ */
+export const heldPhrase = ({ completeness, held }) => {
+    if (completeness.state === "unknown" || !held.oldestAt)
+        return "never fetched";
+    if (!completeness.reachesStart)
+        return `held from ${day(held.oldestAt)} only`;
+    if (completeness.gaps)
+        return "held from its first message, with gaps";
+    return `held from its first message, behind since ${day(held.newestAt)}`;
+};
 /**
  * The steps for chats the store holds only in part. Bounded first, when the answer's window is known, then the whole
  * chat; both name the first chat only, because a download is the owner's call. Counts and dates only, never text.
@@ -105,7 +118,7 @@ const chatGaps = (rows, since) => {
     const [first] = open;
     if (!first)
         return { next: [], missing: [] };
-    const held = first.completeness.state === "unknown" ? "never fetched" : `held from ${day(first.held.oldestAt)} only`;
+    const held = heldPhrase(first);
     const steps = (args, why) => ({
         ...nextStep("messages.sync", { args: { chat: first.chatId, ...args } }),
         why,

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

@@ -41,6 +41,102 @@ export declare const projectAnswerParts: (sinceTime: string, found: StoredProjec
         complete: boolean;
     };
 };
+/**
+ * The gathering with each linked chat's `syncCommand`: the line that syncs a chat held in part back to the window
+ * start, or null when it needs none or no command here can. JSON readers get what the text says per chat.
+ */
+export declare const withSyncCommands: (found: StoredProjectGathering, sync: ProjectTextHints["sync"]) => {
+    schemaVersion: 1;
+    runKey: string;
+    fingerprint: string;
+    resumed: boolean;
+    project: {
+        name: string;
+        key: string | null;
+        background: string | null;
+        aliases: string[];
+    };
+    window: {
+        after: number;
+        before: number;
+        asOf: number;
+        lookbackDays: number | null;
+        basis: "explicit" | "lookback";
+        timeBasis: "per-item-time-kind";
+    };
+    scope: {
+        origin: "all-connected" | "explicit";
+        sources: import("../context/evidence.js").ContextSource[];
+    };
+    lanes: import("../services/project-gathering-request.js").ProjectLane[];
+    fetch: import("../services/project-gathering-request.js").ProjectChatFetched[];
+    index: import("../services/project-gathering.js").ProjectIndexCatchUp;
+    units: {
+        lane: string;
+        source: number;
+        after: number;
+        before: number;
+        state: import("../services/project-gathering-request.js").ProjectUnitState;
+        pages: number;
+        issue: string | null;
+    }[];
+    items: import("../services/project-gathering.js").ProjectEvidenceItem[];
+    people: import("../services/project-gathering.js").ProjectEvidencePerson[];
+    peopleOmitted: number;
+    oversized: {
+        ref: string;
+        lanes: string[];
+        source: number;
+        bytes: number;
+    }[];
+    matchedAgain: {
+        ref: string;
+        lanes: string[];
+    }[];
+    usage: {
+        reads: number;
+        readBytes: number;
+        aroundBytes: number;
+        items: number;
+        elapsedMs: number;
+    };
+    totals: {
+        reads: number;
+        readBytes: number;
+        items: number;
+        invocations: number;
+    };
+    stopped: import("../services/project-gathering.js").ProjectGatheringStop;
+    complete: boolean;
+    completeness: "complete" | "partial" | "unknown";
+    checkpoint: string | null;
+    projectRef: string | null;
+    unreadSources: {
+        source: string;
+        kind: string;
+        reason?: "out-of-scope" | "linked-chat-limit" | "member-limit" | "no-identity" | "unknown-provider";
+    }[];
+    mentions: import("../services/project-gathering-mentions.js").EvidenceMentions;
+    linkedChats: {
+        provider: string;
+        account: string;
+        chat: string;
+        ref: string;
+        source: number | null;
+        lane: string | null;
+        state: "in-scope" | "out-of-scope" | "pending" | "unavailable";
+        title: string | null;
+        completeness: import("../store/exports.js").ChatCompleteness | null;
+        held: {
+            messages: number;
+            oldestAt: string | null;
+            newestAt: string | null;
+        } | null;
+        items?: number | undefined;
+        capped?: boolean | undefined;
+        syncCommand: string | null;
+    }[];
+};
 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;

package/dist/cli/project-evidence.js

@@ -1,7 +1,7 @@
 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";
+import { coverageGaps, heldPhrase } 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];
@@ -47,6 +47,17 @@ export const projectAnswerParts = (sinceTime, found) => {
         },
     };
 };
+/**
+ * The gathering with each linked chat's `syncCommand`: the line that syncs a chat held in part back to the window
+ * start, or null when it needs none or no command here can. JSON readers get what the text says per chat.
+ */
+export const withSyncCommands = (found, sync) => ({
+    ...found,
+    linkedChats: found.linkedChats.map((one) => ({
+        ...one,
+        syncCommand: one.completeness === null || one.completeness.state === "complete" ? null : sync(one, day(found.window.after)),
+    })),
+});
 const LABELS = {
     "person-only": "  [person only]",
     sender: "  [sent by contact]",
@@ -120,13 +131,11 @@ export const projectEvidenceText = (found, hints) => {
     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" : ""}` +
+            const held = one.held === null ? "never fetched" : heldPhrase({ completeness: one.completeness, held: one.held });
+            lines.push(`${one.title ?? one.ref}: ${held}${one.state === "pending" ? ", not read this run" : ""}` +
                 (sync ? ` — sync it: ${sync}` : ""));
         }
     const capped = found.linkedChats.filter((one) => one.capped);

package/dist/services/archive.js

@@ -308,7 +308,7 @@ export const fetchInto = async ({ history, store, account, fetching, limit, page
         before = byTime
             ? new Date(boundary + (fresh > 0 && !(window && fetching.beforeInclusive) ? 1 : 0)).toISOString()
             : String(boundary);
-        note(`${fetched} messages so far, back to ${held.from}`);
+        note(`${fetched} messages so far, back to ${fromAt.slice(0, 10)}`);
         const wait = fetching.jitter ? pauseMs * (1 + Math.random()) : pauseMs;
         await sleep(wait, undefined, { signal: stop }).catch(() => { });
     }

package/package.json

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