@wirecat/cli-core 0.375.0 → 0.377.0

package/CHANGELOG.md

@@ -7,6 +7,52 @@ shape of this file.
 
 ## Unreleased
 
+## 0.377.0 — 20.10.2026
+
+### Added
+
+- **A document hit says how many other paragraphs match.** `ProjectEvidenceItem.moreMatches` (on a document item
+  with `around`) counts the paragraphs after the one `around` centres on that also name a lane word. See
+  [project gathering](docs/dev/PROJECT-GATHERING.md).
+
+### Fixed
+
+- **A document hit's `around` followed the lane that found it first, not the document.** It centred on that lane's
+  first matching paragraph (in a measured 145 KB document, paragraph 60 found by the key, not paragraph 4 that
+  names the project). It now centres on the first paragraph that names a word of any lane, in document order, as
+  the guide says. No extra reads or charged bytes.
+
+## 0.376.0 — 20.10.2026
+
+### Added
+
+- **`gatherProjectEvidence` reads a project's linked chats.** `linkedChats: [{ provider, account, chat }]` (at
+  most 16, the host's confirmed `member-of` links) become lanes of their own (`kinds: ["linked-chat"]`,
+  `query: null`, `chat: <reference>`), read whole through the selected source of the chat's own account. Items
+  found only that way have `context: "linked-chat"` and no `around`; a reference a word lane also finds keeps
+  `context: "project"`. The result's `linkedChats` gives each entry's `ref`, `source`, `lane` and `state`
+  (`in-scope`, `out-of-scope` when its account is not in `sources`, never read; `unavailable` when not stored).
+  Checkpoints stay version 1; a run without linked chats keeps its fingerprint, and a changed link set is refused
+  with "start again without --cursor". See [project gathering](docs/dev/PROJECT-GATHERING.md).
+- **The context reader reads one chat.** `chat` (a chat or mail thread external id) in place of `query` returns
+  that chat's records newest first, including a chat hidden from search, with `coverage.matching: "chat"`.
+  Refused on document and meeting sources and together with `query`. Old cursors stay valid.
+- **`knowledge.relate` links a chat to a project.** A `chat:<provider>/<account>/<chat>` reference may be the
+  `from` of a `member-of` relationship to a `project:`, and `confirmRelation` confirms it. The reference carries
+  its account; a scope key of another account is refused. A chat is related to nothing else.
+
+### Changed — may break callers
+
+- **`ProjectLane.query` is `string | null`** (null for a linked chat's lane), and `ProjectEvidenceItem.context`
+  adds `"linked-chat"`. `ContextEvidenceRequest.query` is optional and `coverage.matching` adds `"chat"`.
+- **`store.contextRecords.read` resolves a message of a chat hidden from search**, since its reference names
+  the chat, so evidence from a linked hidden chat can be staged and its fingerprint rechecked.
+
+### Fixed
+
+- **A resumed project gathering read nothing when every open unit already had a page** (for example a lane
+  stopped after its first page): it now starts at the shallowest open unit's round.
+
 ## 0.375.0 — 20.10.2026
 
 ### Fixed

package/dist/context/evidence-response.js

@@ -8,7 +8,7 @@ export const validateContextEvidencePage = (page, request) => {
         throw new CliError("invalid_response", "context reader returned invalid or out-of-scope evidence");
     };
     try {
-        const { source, after, before, limit, maxReadBytes } = contextEvidenceRequest(request);
+        const { source, chat, after, before, limit, maxReadBytes } = contextEvidenceRequest(request);
         if (!page || contextSourceKey(contextSource(page.source)) !== contextSourceKey(source))
             fail();
         if (!Array.isArray(page.items) ||
@@ -23,7 +23,7 @@ export const validateContextEvidencePage = (page, request) => {
             typeof c.hasMore !== "boolean" ||
             typeof c.hasUndated !== "boolean" ||
             !["ready", "pending", "missing", "unknown"].includes(c.index) ||
-            c.matching !== "literal-words" ||
+            c.matching !== (chat === undefined ? "literal-words" : "chat") ||
             c.completeness !== "unknown" ||
             c.consistency !== "snapshot-per-page")
             fail();
@@ -83,6 +83,7 @@ export const validateContextEvidencePage = (page, request) => {
                 const locator = parseLocator(item.ref);
                 if (locator.provider !== source.provider ||
                     locator.account !== source.account ||
+                    (chat !== undefined && locator.chat !== chat) ||
                     formatLocator(locator) !== item.ref)
                     fail();
                 text.push(locator.chat, locator.message);

package/dist/context/evidence.d.ts

@@ -8,7 +8,10 @@ export interface ContextSource {
 }
 export interface ContextEvidenceRequest {
     source: ContextSource;
-    query: string;
+    /** Required unless `chat` is given; a chat read takes no query. */
+    query?: string;
+    /** One stored chat or mail thread of the source's account, by its external id; refused for documents and meetings. */
+    chat?: string;
     after: number;
     before: number;
     limit?: number;
@@ -52,7 +55,7 @@ export interface ContextEvidencePage {
         hasMore: boolean;
         hasUndated: boolean;
         completeness: "unknown";
-        matching: "literal-words";
+        matching: "literal-words" | "chat";
         consistency: "snapshot-per-page";
     };
 }
@@ -80,11 +83,12 @@ export declare const fittingRows: (sizes: readonly number[], limit: number, maxR
 export interface ContextRecordReader {
     read(ref: string): Promise<Pick<ContextEvidenceItem, "ref" | "title" | "text" | "revision"> | null>;
 }
-export declare const contextCursorScope: (request: Pick<ContextEvidenceRequest, "source" | "query" | "after" | "before">) => string;
+export declare const contextCursorScope: (request: Pick<ContextEvidenceRequest, "source" | "query" | "chat" | "after" | "before">) => string;
 export declare const contextSource: (value: ContextSource) => ContextSource;
 export declare const contextEvidenceRequest: (input: ContextEvidenceRequest) => {
     source: ContextSource;
-    query: string;
+    query: string | undefined;
+    chat: string | undefined;
     words: RegExpMatchArray | [];
     after: number;
     before: number;

package/dist/context/evidence.js

@@ -24,9 +24,11 @@ export const contextCursorScope = (request) => createHash("sha256")
     request.source.accountId,
     request.source.provider,
     request.source.account,
-    request.query,
+    request.query ?? null,
     request.after,
     request.before,
+    // Only a chat read hashes its chat, so cursors issued before chat reads existed stay valid.
+    ...(request.chat === undefined ? [] : [request.chat]),
 ]))
     .digest("hex");
 const fields = (value, allowed, prefix) => {
@@ -51,7 +53,7 @@ export const contextSource = (value) => {
 };
 export const contextEvidenceRequest = (input) => {
     const source = contextSource(input?.source);
-    fields(input, ["source", "query", "after", "before", "limit", "maxReadBytes", "cursor", "signal"], "");
+    fields(input, ["source", "query", "chat", "after", "before", "limit", "maxReadBytes", "cursor", "signal"], "");
     const integer = (value, name, low, high) => {
         if (!Number.isSafeInteger(value) || value < low || value > high)
             throw new CliError("validation_error", `${name} must be a whole number from ${low} to ${high}`);
@@ -61,11 +63,20 @@ export const contextEvidenceRequest = (input) => {
     const before = integer(input.before, "before", after + 1, 8_640_000_000_000_000);
     if (before - after > 90 * 86400000)
         throw new CliError("validation_error", "context time window must not exceed 90 days");
+    const chat = input.chat;
+    if (chat !== undefined) {
+        if (typeof chat !== "string" || !chat.trim() || Buffer.byteLength(chat) > 1024)
+            throw new CliError("validation_error", "chat needs 1–1024 UTF-8 bytes");
+        if (source.kind !== "message" && source.kind !== "mail")
+            throw new CliError("validation_error", "only a message or mail source reads one chat");
+        if (input.query !== undefined)
+            throw new CliError("validation_error", "a chat read takes no query");
+    }
     const query = input.query;
-    if (typeof query !== "string" || !query.trim() || Buffer.byteLength(query) > 2048)
+    if (chat === undefined && (typeof query !== "string" || !query.trim() || Buffer.byteLength(query) > 2048))
         throw new CliError("validation_error", "query needs 1–2048 UTF-8 bytes of literal words");
-    const words = query.match(/[\p{L}\p{N}]+/gu) ?? [];
-    if (!words.length || words.length > 16)
+    const words = query?.match(/[\p{L}\p{N}]+/gu) ?? [];
+    if (chat === undefined && (!words.length || words.length > 16))
         throw new CliError("validation_error", "query needs 1–16 literal words");
     const limit = integer(input.limit ?? 10, "limit", 1, 20);
     const maxReadBytes = integer(input.maxReadBytes ?? 65536, "maxReadBytes", 1, CONTEXT_MAX_READ_BYTES);
@@ -80,7 +91,7 @@ export const contextEvidenceRequest = (input) => {
             id: integer(input.cursor.id, "cursor.id", 1, Number.MAX_SAFE_INTEGER),
             scope: input.cursor.scope,
         };
-    if (cursor && cursor.scope !== contextCursorScope({ source, query, after, before }))
-        throw new CliError("validation_error", "cursor belongs to another source, query or time window");
-    return { source, query, words, after, before, limit, maxReadBytes, cursor, signal: input.signal };
+    if (cursor && cursor.scope !== contextCursorScope({ source, query, chat, after, before }))
+        throw new CliError("validation_error", "cursor belongs to another source, query, chat or time window");
+    return { source, query, chat, words, after, before, limit, maxReadBytes, cursor, signal: input.signal };
 };

package/dist/services/context-evidence.js

@@ -21,7 +21,8 @@ export const createContextEvidenceReader = (port, allowed, limits) => {
             const reservation = budget.reserve(validated.maxReadBytes);
             const request = Object.freeze({
                 source: Object.freeze({ ...source }),
-                query: validated.query,
+                ...(validated.query === undefined ? {} : { query: validated.query }),
+                ...(validated.chat === undefined ? {} : { chat: validated.chat }),
                 after: validated.after,
                 before: validated.before,
                 limit: validated.limit,

package/dist/services/index.d.ts

@@ -3,13 +3,13 @@ export type { ContextEvidenceItem, ContextEvidencePage, ContextEvidenceReader, C
 export { contextEvidenceFingerprint, createContextEvidenceReader } from "./context-evidence.js";
 export { excerpt } from "./excerpt.js";
 export { type DownloadedModel, downloadImageModel, downloadTextModel, type ModelDownloadOptions, } from "./model-downloads.js";
-export type { ProjectEvidenceItem, ProjectGathering, ProjectGatheringPorts, ProjectGatheringStop, ProjectIndexCatchUp, ProjectSourceFetcher, } from "./project-gathering.js";
+export type { ProjectEvidenceContext, ProjectEvidenceItem, ProjectGathering, ProjectGatheringPorts, ProjectGatheringStop, ProjectIndexCatchUp, ProjectSourceFetcher, } 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, ProjectUnitState, } from "./project-gathering-request.js";
+export type { ProjectFetchState, ProjectGatheringBudgets, ProjectGatheringRequest, ProjectLane, ProjectLaneKind, ProjectLinkedChat, ProjectUnitState, } from "./project-gathering-request.js";
 import { type AccountService } from "./account.js";
 import { type AdminService } from "./admin.js";
 import { type AdminStatisticsService } from "./admin-statistics.js";

package/dist/services/meeting-communications-selection.d.ts

@@ -14,7 +14,8 @@ export declare const captureCommunicationSelections: (port: MeetingCommunication
         id: any;
         request: {
             source: import("./context-evidence.js").ContextSource;
-            query: string;
+            query: string | undefined;
+            chat: string | undefined;
             after: number;
             before: number;
             limit: number;

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

@@ -20,6 +20,20 @@ export interface ProjectNeighbourReader {
     }[]>;
 }
 export declare const storedMessageNeighbours: (messages: Pick<MessagesStore, "around">) => ProjectNeighbourReader;
+/**
+ * The paragraphs around the first one that names a word of any query, in document order, with the hit's own marked
+ * found, and how many later paragraphs name one too.
+ */
+export declare const documentMatches: (text: string, queries: string[], window: {
+    before: number;
+    after: number;
+}) => {
+    around: {
+        text: string;
+        found: boolean;
+    }[];
+    moreMatches: number;
+};
 /** The paragraphs around the first one that names the query, in document order; the hit's own is marked found. */
 export declare const documentPassage: (text: string, query: string, window: {
     before: number;

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

@@ -19,22 +19,30 @@ export const storedMessageNeighbours = (messages) => ({
     },
 });
 const wordsOf = (text) => (text.match(/[\p{L}\p{N}\p{M}]+/gu) ?? []).map(fold);
-/** The paragraphs around the first one that names the query, in document order; the hit's own is marked found. */
-export const documentPassage = (text, query, window) => {
+/**
+ * The paragraphs around the first one that names a word of any query, in document order, with the hit's own marked
+ * found, and how many later paragraphs name one too.
+ */
+export const documentMatches = (text, queries, window) => {
     const paragraphs = text
         .split(/\n\s*\n/)
         .map((part) => part.replace(/\s+/g, " ").trim())
         .filter(Boolean);
+    const query = queries.join(" ");
     const words = new Set(wordsOf(query));
-    const hit = paragraphs.findIndex((part) => wordsOf(part).some((word) => words.has(word)));
-    if (hit < 0 || paragraphs.length < 2)
-        return [];
+    const matching = paragraphs.flatMap((part, index) => (wordsOf(part).some((word) => words.has(word)) ? [index] : []));
+    const hit = matching[0];
+    if (hit === undefined || paragraphs.length < 2)
+        return { around: [], moreMatches: 0 };
     const from = Math.max(0, hit - window.before);
-    return paragraphs.slice(from, hit + window.after + 1).map((part, index) => ({
+    const around = paragraphs.slice(from, hit + window.after + 1).map((part, index) => ({
         text: excerpt(part, query, 200, { literal: true }),
         found: from + index === hit,
     }));
+    return { around, moreMatches: matching.length - 1 };
 };
+/** The paragraphs around the first one that names the query, in document order; the hit's own is marked found. */
+export const documentPassage = (text, query, window) => documentMatches(text, [query], window).around;
 /**
  * Neighbours are context for reading a hit, not matches: they never join `items`, and their text counts against
  * the run's read bytes.

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

@@ -12,6 +12,8 @@ export interface ProjectGatheringRequest {
         reference?: string;
     }[];
     sources: ContextSource[];
+    /** Chats the host confirmed as the project's; each is read whole, through the source of its own account. */
+    linkedChats?: ProjectLinkedChat[];
     scope: "explicit" | "all-connected";
     lookbackDays?: number;
     after?: number;
@@ -28,6 +30,11 @@ export interface ProjectGatheringRequest {
     checkpoint?: string;
     signal?: AbortSignal;
 }
+export interface ProjectLinkedChat {
+    provider: string;
+    account: string;
+    chat: string;
+}
 export interface ProjectGatheringBudgets {
     maxReads?: number;
     maxReadBytes?: number;
@@ -35,12 +42,15 @@ export interface ProjectGatheringBudgets {
     maxElapsedMs?: number;
     maxItems?: number;
 }
-export type ProjectLaneKind = "project" | "key" | "alias" | "keyword" | "person";
+export type ProjectLaneKind = "project" | "key" | "alias" | "keyword" | "person" | "linked-chat";
 export interface ProjectLane {
     id: string;
     kinds: ProjectLaneKind[];
-    query: string;
+    /** Null for a linked chat's lane, which reads every message of the chat. */
+    query: string | null;
     people: string[];
+    /** A linked chat's lane only: the chat's reference. */
+    chat?: string;
 }
 export type ProjectUnitState = "pending" | "partial" | "done" | "unavailable" | "failed" | "read-limited";
 export interface ProjectUnitProgress {
@@ -67,6 +77,8 @@ export interface ProjectGatheringCheckpoint {
         code: string | null;
     }[];
     units: ProjectUnitProgress[];
+    /** Present only when the run reads linked chats: a hash of their references. */
+    linkedChats?: string;
     seen: string[];
     totals: {
         reads: number;
@@ -90,6 +102,15 @@ export declare const projectGatheringRequest: (input: ProjectGatheringRequest, n
     }[];
     lanes: ProjectLane[];
     sources: ContextSource[];
+    linkedChats: {
+        provider: string;
+        account: string;
+        chat: string;
+        ref: string;
+        source: number | null;
+        lane: string | null;
+    }[];
+    linkedKey: string | undefined;
     scope: "all-connected" | "explicit";
     lookbackDays: number | null;
     window: {
@@ -126,6 +147,7 @@ export declare const projectUnits: (plan: ProjectGatheringPlan, window: {
         after: number;
         before: number;
     };
+    chat: string | undefined;
 }[];
 export declare const seenKey: (ref: string) => string;
 export declare const encodeCheckpoint: (checkpoint: ProjectGatheringCheckpoint) => string;

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

@@ -2,10 +2,11 @@ import { createHash } from "node:crypto";
 import { CliError } from "@wirecat/cli-base";
 import { contextSource } from "../context/evidence.js";
 import { contextSourceKey } from "../context/evidence-response.js";
+import { formatReference } from "../domain/references.js";
 const DAY = 86400000;
 const MAX_TIME = 8_640_000_000_000_000;
 export const CONTEXT_CHUNK_DAYS = 90;
-const LIMITS = { lanes: 16, sources: 32, units: 512, lookbackDays: 730, people: 16 };
+const LIMITS = { lanes: 16, sources: 32, units: 512, lookbackDays: 730, people: 16, linkedChats: 16 };
 const BUDGETS = {
     maxReads: [48, 512],
     maxReadBytes: [2097152, 16777216],
@@ -49,6 +50,7 @@ export const projectGatheringRequest = (input, now) => {
         "keywords",
         "people",
         "sources",
+        "linkedChats",
         "scope",
         "lookbackDays",
         "after",
@@ -90,10 +92,33 @@ export const projectGatheringRequest = (input, now) => {
     const sources = sourceList.map((s) => contextSource(s));
     if (new Set(sources.map(contextSourceKey)).size !== sources.length)
         fail("sources lists one source twice", "sources");
+    const linkedChats = list(input.linkedChats, "linkedChats", LIMITS.linkedChats).map((value, i) => {
+        const name = `linkedChats.${i}`;
+        if (!value || typeof value !== "object")
+            return fail(`${name} needs provider, account and chat`, name);
+        known(value, ["provider", "account", "chat"], `${name}.`);
+        const given = value;
+        const provider = text(given.provider, `${name}.provider`, 128);
+        const account = text(given.account, `${name}.account`, 1024);
+        const chat = text(given.chat, `${name}.chat`, 1024);
+        const kind = provider === "email" ? "mail" : "message";
+        // The chat's own account must be a selected source; any other account would widen the owner's scope.
+        const source = sources.findIndex((s) => s.kind === kind && s.provider === provider && s.account === account);
+        return {
+            provider,
+            account,
+            chat,
+            ref: formatReference({ type: "chat", provider, account, chat }),
+            source: source < 0 ? null : source,
+            lane: null,
+        };
+    });
+    if (new Set(linkedChats.map((c) => c.ref)).size !== linkedChats.length)
+        fail("linkedChats lists one chat twice", "linkedChats");
     const lanes = [];
     const lane = (kind, query, person) => {
         const key = query.toLowerCase();
-        const found = lanes.find((l) => l.query.toLowerCase() === key) ?? {
+        const found = lanes.find((l) => l.query?.toLowerCase() === key) ?? {
             id: `l${lanes.length + 1}`,
             kinds: [],
             query,
@@ -117,6 +142,12 @@ export const projectGatheringRequest = (input, now) => {
         lane("person", p.name, p.reference ?? p.name);
     if (lanes.length > LIMITS.lanes)
         fail(`at most ${LIMITS.lanes} distinct search lanes`, "keywords");
+    for (const linked of linkedChats) {
+        if (linked.source === null)
+            continue;
+        linked.lane = `l${lanes.length + 1}`;
+        lanes.push({ id: linked.lane, kinds: ["linked-chat"], query: null, people: [], chat: linked.ref });
+    }
     const fetch = input.fetch ?? "none";
     const index = input.index ?? "update";
     if (index !== "update" && index !== "as-is")
@@ -171,6 +202,11 @@ export const projectGatheringRequest = (input, now) => {
         fetch,
     ]))
         .digest("hex");
+    const linkedKey = linkedChats.length
+        ? createHash("sha256")
+            .update(JSON.stringify(linkedChats.map((c) => c.ref)))
+            .digest("hex")
+        : undefined;
     const runKey = input.runKey === undefined ? fingerprint : text(input.runKey, "runKey", 256);
     if (input.checkpoint !== undefined && typeof input.checkpoint !== "string")
         fail("checkpoint must be text", "checkpoint");
@@ -180,6 +216,8 @@ export const projectGatheringRequest = (input, now) => {
         people,
         lanes,
         sources,
+        linkedChats,
+        linkedKey,
         scope: input.scope,
         lookbackDays,
         window,
@@ -201,7 +239,25 @@ export const contextChunks = (after, before) => {
     return chunks;
 };
 export const projectUnits = (plan, window) => {
-    const units = contextChunks(window.after, window.before).flatMap((chunk) => plan.lanes.flatMap((lane) => plan.sources.map((source, sourceIndex) => ({ lane, source, sourceIndex, chunk }))));
+    const chunks = contextChunks(window.after, window.before);
+    const literal = chunks.flatMap((chunk) => plan.lanes
+        .filter((lane) => lane.query !== null)
+        .flatMap((lane) => plan.sources.map((source, sourceIndex) => ({
+        lane,
+        source,
+        sourceIndex,
+        chunk,
+        chat: undefined,
+    }))));
+    // Appended after every literal unit: a checkpoint from a run without links keeps its unit order, and in each
+    // round a literal lane labels a shared hit before the linked chat does.
+    const linked = chunks.flatMap((chunk) => plan.linkedChats.flatMap(({ lane, source, chat }) => {
+        const found = plan.lanes.find((l) => l.id === lane);
+        return found && source !== null
+            ? [{ lane: found, source: plan.sources[source], sourceIndex: source, chunk, chat }]
+            : [];
+    }));
+    const units = [...literal, ...linked];
     if (units.length > LIMITS.units)
         fail(`${units.length} lane × source × 90-day reads exceed ${LIMITS.units}; narrow the lanes, sources or window`);
     return units;
@@ -227,6 +283,8 @@ export const decodeCheckpoint = (text, plan) => {
         value.after < 0 ||
         value.before <= value.after)
         fail("invalid project gathering checkpoint", "checkpoint");
+    if ((value.linkedChats ?? null) !== (plan.linkedKey ?? null))
+        fail("the project's linked chats changed; start again without --cursor", "checkpoint");
     if (value.runKey !== plan.runKey)
         fail("checkpoint belongs to another run key", "checkpoint");
     if (value.fingerprint !== plan.fingerprint)

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

@@ -32,11 +32,15 @@ export interface ProjectEvidenceItem extends Omit<ContextEvidenceItem, "text"> {
     text: string;
     textTruncated: boolean;
     lanes: string[];
-    context: "project" | "person-only";
+    context: ProjectEvidenceContext;
     fingerprint: string;
     around?: ProjectNeighbour[] | null;
     aroundIssue?: string | null;
+    /** A document hit with `around`: how many paragraphs after the one it centres on also name a lane word. */
+    moreMatches?: number;
 }
+/** Strongest first: a hit that names the project, then one only from a linked chat, then one naming only a person. */
+export type ProjectEvidenceContext = "project" | "linked-chat" | "person-only";
 export type ProjectGatheringStop = "reads" | "read-bytes" | "elapsed" | "items" | null;
 export declare const gatherProjectEvidence: (ports: ProjectGatheringPorts, request: ProjectGatheringRequest) => Promise<{
     schemaVersion: 1;
@@ -62,6 +66,15 @@ export declare const gatherProjectEvidence: (ports: ProjectGatheringPorts, reque
         sources: ContextSource[];
     };
     lanes: ProjectLane[];
+    linkedChats: {
+        provider: string;
+        account: string;
+        chat: string;
+        ref: string;
+        source: number | null;
+        lane: string | null;
+        state: "in-scope" | "out-of-scope" | "unavailable";
+    }[];
     fetch: {
         state: ProjectFetchState;
         history: "complete" | "partial" | "unknown" | null;

package/dist/services/project-gathering.js

@@ -2,9 +2,15 @@ import { CliError } from "@wirecat/cli-base";
 import { CONTEXT_MAX_READ_BYTES, contextEvidenceFingerprint } from "../context/evidence.js";
 import { createContextEvidenceReader } from "./context-evidence.js";
 import { excerpt } from "./excerpt.js";
-import { attachNeighbours, documentPassage, } from "./project-gathering-around.js";
+import { attachNeighbours, documentMatches, } from "./project-gathering-around.js";
 import { decodeCheckpoint, encodeCheckpoint, projectGatheringRequest, projectUnits, seenKey, } from "./project-gathering-request.js";
 const terminal = new Set(["done", "unavailable", "failed"]);
+const CONTEXTS = ["person-only", "linked-chat", "project"];
+const contextOf = (lane) => lane.kinds.includes("linked-chat")
+    ? "linked-chat"
+    : lane.kinds.every((k) => k === "person")
+        ? "person-only"
+        : "project";
 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");
@@ -25,6 +31,7 @@ export const gatherProjectEvidence = async (ports, request) => {
         plan.sources.map(() => ({ state: "not-requested", history: null, code: null }));
     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", {
             param: "fetch",
@@ -81,8 +88,9 @@ export const gatherProjectEvidence = async (ports, request) => {
         if (known) {
             if (!known.lanes.includes(lane.id))
                 known.lanes.push(lane.id);
-            if (!lane.kinds.every((k) => k === "person"))
-                known.context = "project";
+            const context = contextOf(lane);
+            if (CONTEXTS.indexOf(context) > CONTEXTS.indexOf(known.context))
+                known.context = context;
             return true;
         }
         if (!seen.has(seenKey(ref)))
@@ -94,7 +102,7 @@ export const gatherProjectEvidence = async (ports, request) => {
         if (again(item.ref, lane))
             return;
         seen.add(seenKey(item.ref));
-        const short = excerpt(item.text, lane.query, 300, { literal: true });
+        const short = excerpt(item.text, lane.query ?? "", 300, { literal: true });
         const fingerprint = contextEvidenceFingerprint(item);
         const entry = {
             ...item,
@@ -104,11 +112,13 @@ export const gatherProjectEvidence = async (ports, request) => {
             textTruncated: short !== item.text.replace(/\s+/g, " ").trim(),
             fingerprint,
             lanes: [lane.id],
-            context: lane.kinds.every((k) => k === "person") ? "person-only" : "project",
+            context: contextOf(lane),
         };
-        if (kind === "document" && plan.around.before + plan.around.after) {
+        if (kind === "document" && lane.query !== null && plan.around.before + plan.around.after) {
+            const passage = documentMatches(item.text, queries, plan.around);
             entry.around = [];
-            for (const part of documentPassage(item.text, lane.query, plan.around)) {
+            entry.moreMatches = passage.moreMatches;
+            for (const part of passage.around) {
                 const bytes = Buffer.byteLength(part.text);
                 if (bytes > plan.budgets.maxReadBytes - usage.readBytes - usage.aroundBytes) {
                     entry.aroundIssue = "read-bytes";
@@ -122,7 +132,9 @@ export const gatherProjectEvidence = async (ports, request) => {
         items.push(entry);
         usage.items++;
     };
-    for (let round = 0; !stopped; round++) {
+    // A resumed run starts at its shallowest open unit: below it no unit is due, and an empty round would end the run.
+    const shallowest = progress.reduce((low, u) => (open(u) ? Math.min(low, u.pages) : low), Number.POSITIVE_INFINITY);
+    for (let round = shallowest; !stopped; round++) {
         const due = progress.flatMap((u, index) => (open(u) && u.pages <= round ? [index] : []));
         if (!due.length)
             break;
@@ -152,7 +164,7 @@ export const gatherProjectEvidence = async (ports, request) => {
                 try {
                     const page = await reader.read({
                         source: unit.source,
-                        query: unit.lane.query,
+                        ...(unit.chat === undefined ? { query: unit.lane.query ?? undefined } : { chat: unit.chat }),
                         after: unit.chunk.after,
                         before: unit.chunk.before,
                         limit,
@@ -214,7 +226,9 @@ export const gatherProjectEvidence = async (ports, request) => {
             }
         }
     }
-    await attachNeighbours(items, ports.neighbours, plan.around, {
+    await attachNeighbours(
+    // A linked chat's neighbours are already its own lane's evidence.
+    items.filter((item) => item.context !== "linked-chat"), ports.neighbours, plan.around, {
         remaining: () => plan.budgets.maxReadBytes - usage.readBytes - usage.aroundBytes,
         charge: (bytes) => {
             usage.aroundBytes += bytes;
@@ -236,6 +250,7 @@ export const gatherProjectEvidence = async (ports, request) => {
         asOf: window.asOf,
         fetched,
         units: progress.map((u) => (u.state === "read-limited" ? { ...u, state: "partial" } : u)),
+        ...(plan.linkedKey === undefined ? {} : { linkedChats: plan.linkedKey }),
         seen: [...seen],
         totals,
     };
@@ -255,6 +270,19 @@ export const gatherProjectEvidence = async (ports, request) => {
         },
         scope: { origin: plan.scope, sources: plan.sources },
         lanes: plan.lanes,
+        linkedChats: plan.linkedChats.map(({ provider, account, chat, ref, source, lane }) => ({
+            provider,
+            account,
+            chat,
+            ref,
+            source,
+            lane,
+            state: source === null
+                ? "out-of-scope"
+                : units.every((unit, index) => unit.lane.id !== lane || progress[index]?.state === "unavailable")
+                    ? "unavailable"
+                    : "in-scope",
+        })),
         fetch: fetched.map((f, index) => ({ source: index, ...f })),
         index: indexed,
         units: units.map((unit, index) => ({

package/dist/store/sqlite/context-evidence.js

@@ -19,6 +19,9 @@ const corpora = {
         timeKind: "'sent'",
         join: "JOIN chats c ON c.id=n.chat_id AND c.account_id=n.account_id",
         where: "c.searchable=1",
+        chats: "chats",
+        // A read that names the chat sees it even when it is hidden from search (searchable=0).
+        named: "c.external_id=?",
     },
     mail: {
         table: "emails",
@@ -32,6 +35,8 @@ const corpora = {
         timeKind: "'sent'",
         join: "JOIN email_threads c ON c.id=n.email_thread_id AND c.account_id=n.account_id",
         where: "a.provider='email'",
+        chats: "email_threads",
+        named: "a.provider='email' AND c.external_id=?",
     },
     document: {
         table: "documents",
@@ -45,17 +50,19 @@ const corpora = {
         timeKind: contextDocumentTimeKind,
         join: "",
         where: "n.body IS NOT NULL AND CASE WHEN json_valid(n.metadata) THEN coalesce(json_extract(n.metadata, '$.catalog.active'),1) ELSE 1 END=1",
+        chats: null,
+        named: null,
     },
 };
 /** No index fills, model loads or record hydration outside the read transaction. */
 export const contextEvidenceOver = ({ database }) => ({
     async read(original) {
         const request = contextEvidenceRequest(original);
-        const { source, words, after, before, limit, maxReadBytes, cursor, signal } = request;
+        const { source, words, chat, after, before, limit, maxReadBytes, cursor, signal } = request;
         if (source.kind === "meeting")
             return readMeetingContextEvidence(database, request);
         const corpus = corpora[source.kind];
-        const scope = contextCursorScope({ source, query: request.query, after, before });
+        const scope = contextCursorScope({ source, query: request.query, chat, after, before });
         signal?.throwIfAborted();
         return read(database, () => {
             const coverage = {
@@ -64,25 +71,35 @@ export const contextEvidenceOver = ({ database }) => ({
                 hasMore: false,
                 hasUndated: false,
                 completeness: "unknown",
-                matching: "literal-words",
+                matching: chat === undefined ? "literal-words" : "chat",
                 consistency: "snapshot-per-page",
             };
             const empty = () => ({ source, items: [], next: null, readBytes: 0, coverage });
-            const scopeParams = [source.accountId, source.provider, source.account];
+            const accountParams = [source.accountId, source.provider, source.account];
             const account = database
                 .prepare(`SELECT 1 FROM accounts WHERE id=? AND provider=? AND external_id=?${source.kind === "mail" ? " AND provider='email'" : ""}`)
-                .get(...scopeParams);
+                .get(...accountParams);
             if (!account)
                 return empty();
+            if (chat !== undefined &&
+                !database
+                    .prepare(`SELECT 1 FROM ${corpus.chats} WHERE account_id=? AND external_id=?`)
+                    .get(source.accountId, chat))
+                return empty();
             coverage.available = true;
-            if (!database.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name=?").get(corpus.index)) {
+            const scopeParams = chat === undefined ? accountParams : [...accountParams, chat];
+            const base = `FROM ${corpus.table} n JOIN accounts a ON a.id=n.account_id ${corpus.join}
+        WHERE n.account_id=? AND a.provider=? AND a.external_id=? AND n.deleted_at IS NULL
+        AND ${chat === undefined ? corpus.where : corpus.named}`;
+            // A chat read uses no word index, so words still waiting for it hide nothing.
+            if (chat !== undefined)
+                coverage.index = "ready";
+            else if (!database.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name=?").get(corpus.index)) {
                 coverage.index = "missing";
                 return empty();
             }
-            const base = `FROM ${corpus.table} n JOIN accounts a ON a.id=n.account_id ${corpus.join}
-        WHERE n.account_id=? AND a.provider=? AND a.external_id=? AND n.deleted_at IS NULL AND ${corpus.where}`;
             coverage.hasUndated = Boolean(database.prepare(`SELECT 1 ${base} AND ${corpus.at} IS NULL LIMIT 1`).get(...scopeParams));
-            if (source.kind === "message") {
+            if (chat === undefined && source.kind === "message") {
                 const state = database
                     .prepare("SELECT watermark,filled_through FROM search_index_state WHERE name='message_words'")
                     .get();
@@ -95,7 +112,7 @@ export const contextEvidenceOver = ({ database }) => ({
                         ? "pending"
                         : "ready";
             }
-            else {
+            else if (chat === undefined) {
                 coverage.index = database
                     .prepare(`SELECT 1 ${base} AND ${corpus.at}>=? AND ${corpus.at}<?
           AND EXISTS(SELECT 1 FROM ${source.kind === "mail" ? "email" : "document"}_index_pending p
@@ -108,16 +125,13 @@ export const contextEvidenceOver = ({ database }) => ({
         ${corpus.title} AS title,${corpus.body} AS body,${corpus.url} AS url,${corpus.at} AS at,
         n.updated_at,${corpus.revision} AS revision,${corpus.timeKind} AS time_kind ${base}
         AND ${corpus.at}>=? AND ${corpus.at}<?
-        AND n.id IN (SELECT rowid FROM ${corpus.index} WHERE ${corpus.index} MATCH ?)
-        ${source.kind === "message" ? `AND n.normalized_text IS NOT NULL AND n.normalizer_version=${NORMALIZER_VERSION}` : `AND NOT EXISTS(SELECT 1 FROM ${source.kind === "mail" ? "email" : "document"}_index_pending p WHERE p.id=n.id AND p.indexable_type='${source.kind === "mail" ? "email" : "document"}')`}
+        ${chat !== undefined ? "" : `AND n.id IN (SELECT rowid FROM ${corpus.index} WHERE ${corpus.index} MATCH ?)`}
+        ${chat !== undefined ? "" : source.kind === "message" ? `AND n.normalized_text IS NOT NULL AND n.normalizer_version=${NORMALIZER_VERSION}` : `AND NOT EXISTS(SELECT 1 FROM ${source.kind === "mail" ? "email" : "document"}_index_pending p WHERE p.id=n.id AND p.indexable_type='${source.kind === "mail" ? "email" : "document"}')`}
         ${cursor ? `AND (${corpus.at}<? OR (${corpus.at}=? AND n.id<?))` : ""}
         ORDER BY ${corpus.at} DESC,n.id DESC LIMIT ?`;
-            const params = [
-                ...scopeParams,
-                after,
-                before,
-                words.map((w) => `normalized_text:"${normalize(w)}"`).join(" AND "),
-            ];
+            const params = [...scopeParams, after, before];
+            if (chat === undefined)
+                params.push(words.map((w) => `normalized_text:"${normalize(w)}"`).join(" AND "));
             if (cursor)
                 params.push(cursor.at, cursor.at, cursor.id);
             params.push(limit + 1);
@@ -217,9 +231,9 @@ export const contextRecordOf = (database, ref) => {
     const corpus = at.provider === "email" ? corpora.mail : corpora.message;
     const row = database
         .prepare(`SELECT ${corpus.title} AS title,${corpus.body} AS body FROM ${corpus.table} n JOIN accounts a ON a.id=n.account_id
-       ${corpus.join} WHERE a.provider=? AND a.external_id=? AND c.external_id=? AND n.external_id=?
-       AND n.deleted_at IS NULL AND ${corpus.where}`)
-        .get(at.provider, at.account, at.chat, at.message);
+       ${corpus.join} WHERE a.provider=? AND a.external_id=? AND n.external_id=?
+       AND n.deleted_at IS NULL AND ${corpus.named}`)
+        .get(at.provider, at.account, at.message, at.chat);
     return row
         ? { ref, title: row.title == null ? null : String(row.title), text: String(row.body), revision: null }
         : null;

package/dist/store/sqlite/knowledge.js

@@ -222,11 +222,18 @@ export const knowledgeStoreOver = (context) => {
             throw new CliError("not_found", "no relationship with that id");
         return row;
     };
-    const related = (key, reference) => {
+    /** A chat may only be the member: its reference names its own account, so it is never another account's. */
+    const related = (key, reference, member = false) => {
         checked(key);
         const thing = thingOf(database, reference);
-        if (!thing || !RELATED.includes(thing.type) || stateOfThing(database, thing) !== "available")
-            throw new CliError("not_found", "reference needs a stored person:, organization:, project: or task:");
+        const chat = member && (thing?.type === "chat" || thing?.type === "email_thread");
+        if (!thing || !(RELATED.includes(thing.type) || chat) || stateOfThing(database, thing) !== "available")
+            throw new CliError("not_found", `reference needs a stored person:, organization:, project:${member ? ", task: or chat:" : " or task:"}`);
+        if (chat && key !== null) {
+            const parsed = parseReference(reference);
+            if (parsed.provider !== key.provider || parsed.account !== key.account)
+                throw new CliError("validation_error", "the chat belongs to another account");
+        }
         return thing;
     };
     const reminderOf = (row) => ({
@@ -473,10 +480,13 @@ export const knowledgeStoreOver = (context) => {
             .all()
             .map(projectOf),
         relate: async (key, input) => {
-            const from = related(key, input.from);
+            const from = related(key, input.from, true);
             const to = related(key, input.to);
             if ((from.type === to.type && from.id === to.id) || !RELATION_KINDS.includes(input.kind))
                 throw new CliError("validation_error", "a relationship needs distinct references and a supported kind");
+            if ((from.type === "chat" || from.type === "email_thread") &&
+                (input.kind !== "member-of" || to.type !== "project"))
+                throw new CliError("validation_error", "a chat is related only as member-of a project");
             const existing = database
                 .prepare(`${RELATIONS} AND from_type=? AND from_id=? AND to_type=? AND to_id=? AND kind=?`)
                 .get(from.type, from.id, to.type, to.id, input.kind);
@@ -514,7 +524,7 @@ export const knowledgeStoreOver = (context) => {
             checked(key);
             const row = relation(id);
             const link = linkOf(database, row);
-            related(key, link.from);
+            related(key, link.from, true);
             related(key, String(link.to));
             database
                 .prepare("UPDATE links SET confirmed=1, source='owner', author='owner', updated_at=? WHERE id=?")

package/package.json

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