pim-agent 0.13.0 → 0.14.1

package/packages/core/src/extensions/web-search/providers/SearchProvider.ts

@@ -18,7 +18,7 @@ export type SearchProvider = {
   search(input: ProviderSearchInput): Promise<readonly SearchResult[]>;
 };
 
-/** Quota or rate limit exhausted; only this error opens the breaker and sidelines a provider. */
+/** The only error that trips the breaker. */
 export class ProviderQuotaError extends Error {
   public readonly provider: string;
   public readonly retryAfterMs: number | undefined;
@@ -43,7 +43,7 @@ export class ProviderSearchError extends Error {
 
 const MAX_SNIPPET_LENGTH = 500;
 
-/** Caps a provider snippet; Firecrawl returns whole scraped pages where others return two lines. */
+/** Collapses whitespace and caps length; Firecrawl can return whole pages. */
 export function normalizeSnippet(value: string | undefined): string {
   const collapsed = (value ?? "").replaceAll(/\s+/gu, " ").trim();
 
@@ -52,7 +52,7 @@ export function normalizeSnippet(value: string | undefined): string {
     : collapsed;
 }
 
-export function parseRetryAfterMs(value: string | null): number | undefined {
+function parseRetryAfterMs(value: string | null): number | undefined {
   if (value === null) {
     return undefined;
   }

package/packages/core/src/extensions/write/write.ts

@@ -4,7 +4,7 @@ import { FsErrors } from "../../shared/FsErrors";
 
 const CONTEXT_LINES = 3;
 
-// Diff.diffLines is O(n*d): above this only the diff is skipped, never the write.
+// Diffing is O(n*d); above this the diff is skipped, not the write.
 const MAX_DIFF_BYTES = 2 * 1024 * 1024;
 
 export type WriteOutcome = {

package/packages/core/src/picker/InProcessFilePickerSuggestionEngine.ts

@@ -25,9 +25,7 @@ export class InProcessFilePickerSuggestionEngine implements FilePickerSuggestion
         this.cachedRelative = catalog;
       })
       .catch(() => {
-        if (this.cachedRelative === undefined) {
-          this.cachedRelative = [];
-        }
+        this.cachedRelative ??= [];
       })
       .finally(() => {
         this.refresh = undefined;

package/packages/core/src/picker/PickerItem.ts

@@ -1,4 +1,4 @@
-/** One completion row, structurally identical to pi-tui's `AutocompleteItem`. */
+/** Structurally identical to pi-tui's `AutocompleteItem`. */
 export type PickerItem = {
   readonly value: string;
   readonly label: string;

package/packages/core/src/picker/PickerService.ts

@@ -9,19 +9,16 @@ import { InProcessFilePickerSuggestionEngine } from "./InProcessFilePickerSugges
 import type { PickerItem } from "./PickerItem";
 
 export type PickerServiceDeps = {
-  /** Read per query: a session's cwd can move between turns. */
+  /** Read per query; the cwd can change between turns. */
   readonly cwd: () => string;
   readonly agentDir: string;
-  /** Extension-registered commands, available only while an agent is built. */
+  /** Source of extension commands; undefined until an agent is built. */
   readonly agent?: () => AgentSession | undefined;
 };
 
 const DEFAULT_LIMIT = 50;
 
-/**
- * The `.agents/skills` roots pi reads and `loadSkills` does not: every one from
- * the cwd up to the repository root, plus the user's own.
- */
+/** `.agents/skills` dirs from cwd up to the repo root, plus `~/.agents/skills`; `loadSkills` skips these. */
 function agentsSkillDirs(cwd: string): string[] {
   const dirs: string[] = [];
   let dir = resolve(cwd);
@@ -37,7 +34,6 @@ function agentsSkillDirs(cwd: string): string[] {
   return dirs;
 }
 
-/** Answers one session's picker queries against the machine the agent runs on. */
 export class PickerService {
   private readonly deps: PickerServiceDeps;
   private fileCache:

package/packages/core/src/picker/RemoteFilePickerSuggestionEngine.ts

@@ -13,7 +13,7 @@ const DEBOUNCE_MS = 30;
 
 const CACHE_LIMIT = 100;
 
-/** The client half of the `@` picker: the TUI's engine contract, answered by the server. Browser-safe APIs only. */
+/** Browser-safe: asks the server for `@` picker rows. */
 export class RemoteFilePickerSuggestionEngine implements FilePickerSuggestionEngine {
   private readonly cache = new Map<string, readonly PickerItem[]>();
   private generation = 0;
@@ -23,7 +23,6 @@ export class RemoteFilePickerSuggestionEngine implements FilePickerSuggestionEng
     private readonly debounceMs: number = DEBOUNCE_MS
   ) {}
 
-  /** The invalidation hook: `picker_invalidate` from the server lands here. */
   public refreshRelative(): Promise<void> {
     this.cache.clear();
     return Promise.resolve();

package/packages/core/src/picker/catalog.ts

@@ -122,14 +122,13 @@ async function runLoadRelative(
   options: LoadRelativeOptions
 ): Promise<readonly FileCandidate[]> {
   const spawner = options.gitSpawner ?? defaultGitSpawner;
-
-  const fastPath = await tryGitListFiles(root, spawner);
-  if (fastPath !== undefined) {
-    return finalizeRelative(fastPath);
-  }
-
-  const fallback = await scanWithGlob(root);
-  return finalizeRelative(fallback);
+  const paths =
+    (await tryGitListFiles(root, spawner)) ??
+    (await FileEnumerator.enumerate(root, {
+      includeDotfiles: false,
+      includeIgnored: false,
+    }));
+  return finalizeRelative(paths);
 }
 
 async function tryGitListFiles(
@@ -148,13 +147,6 @@ async function tryGitListFiles(
   return result.stdout.split("\n").filter((line) => line.length > 0);
 }
 
-async function scanWithGlob(root: string): Promise<readonly string[]> {
-  return FileEnumerator.enumerate(root, {
-    includeDotfiles: false,
-    includeIgnored: false,
-  });
-}
-
 function finalizeRelative(paths: readonly string[]): readonly FileCandidate[] {
   const normalized = paths.map(Paths.toForwardSlashes);
 

package/packages/core/src/picker/filePickerWorker.ts

@@ -18,9 +18,7 @@ const refreshRelative = async (id: number, root: string): Promise<void> => {
       ok: true,
     } satisfies FilePickerWorkerResponse);
   } catch (error) {
-    if (cachedRelative === undefined) {
-      cachedRelative = [];
-    }
+    cachedRelative ??= [];
     self.postMessage({
       id,
       type: "refreshRelative",

package/packages/core/src/picker/ranker.ts

@@ -164,7 +164,7 @@ class RelativeRankingIndex {
         substringHits.push(candidate);
       }
 
-      // Only prefix hits may end the scan early: a late prefix must not lose to an earlier substring.
+      // Only prefix hits end the scan, so a late prefix hit still beats substrings.
       if (prefixHits.length >= limitSize) {
         break;
       }

package/packages/core/src/picker/token.ts

@@ -1,15 +1,14 @@
-/** Which picker the caret is sitting in, if any. */
 export type PickerToken = {
   readonly kind: "file" | "command";
   readonly query: string;
-  /** Offset of the sigil itself, so a completion replaces it too. */
+  /** Offset of the sigil. */
   readonly start: number;
 };
 
 export const AT_PREFIX = /(?:^|\s)@(\S*)$/;
 export const SLASH_PREFIX = /(?:^|\s)\/(\S*)$/;
 
-/** Offset of the sigil in a match that also swallows the whitespace before it. */
+/** Skips the leading whitespace the prefix regexes may match. */
 export function sigilOffset(match: RegExpMatchArray): number {
   const matched = match[0] ?? "";
   return (match.index ?? 0) + (/^\s/.test(matched) ? 1 : 0);
@@ -53,7 +52,7 @@ export function tokenKey(token: PickerToken | undefined): string {
 export type Completion = {
   readonly text: string;
   readonly caret: number;
-  /** A directory keeps the picker open so the next segment can be drilled into. */
+  /** True for a directory, so the next segment can be picked. */
   readonly keepOpen: boolean;
 };
 

package/packages/core/src/session/AgentRuntime.ts

@@ -7,19 +7,16 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { join } from "node:path";
 
-/** One model a session can be switched to, named the way `setModel` takes it. */
 export type ModelChoice = {
+  /** `provider/id`, as `setModel` takes it. */
   readonly id: string;
   readonly label: string;
-  /** Who serves it, for a client that groups or tags the catalogue. */
   readonly provider: string;
 };
 
 /**
- * Pi's installation as one process sees it: a single `ModelRuntime` over a
- * single `auth.json`, and one `SettingsManager` per cwd. Every surface in a
- * process shares one of these — two runtimes over one auth file race each
- * other's token refresh.
+ * One `ModelRuntime` per process, shared by every surface: two runtimes over
+ * one `auth.json` race each other's token refresh.
  */
 export class AgentRuntime {
   public readonly agentDir: string;
@@ -32,7 +29,7 @@ export class AgentRuntime {
     this.agentDir = agentDir ?? getAgentDir();
   }
 
-  /** Idempotent, and shared by every caller: the second surface to ask waits on the first. */
+  /** Idempotent; concurrent callers share one boot. A failed boot can be retried. */
   public init(): Promise<void> {
     this.booting ??= this.bootstrap().catch((err: unknown) => {
       this.booting = undefined;
@@ -49,7 +46,7 @@ export class AgentRuntime {
     return this.required(this.registry);
   }
 
-  /** Every model this machine has credentials for, qualified as `setModel` takes them. */
+  /** Models with credentials available. */
   public models(): readonly ModelChoice[] {
     return this.modelRegistry.getAvailable().map((model: Model<ModelApi>) => ({
       id: `${model.provider}/${model.id}`,

package/packages/core/src/session/EventLog.ts

@@ -18,7 +18,7 @@ async function ifPresent<T>(read: () => Promise<T>, absent: T): Promise<T> {
   }
 }
 
-/** One durable line of a session file; the header is line 1, so entries start at `seq` 2. */
+/** `seq` is the 1-based line number; the header is line 1. */
 export type LoggedEntry = {
   readonly seq: number;
   readonly entry: FileEntry;
@@ -40,7 +40,7 @@ function isHeader(entry: FileEntry): entry is SessionHeader {
   return entry.type === "session";
 }
 
-/** A reader over one pi session file: append-only JSONL, so a line's `seq` never changes. */
+/** Reader over one append-only pi session file. */
 export class EventLog {
   public readonly path: string;
   private cursor: Cursor = { offset: 0, seq: 0 };
@@ -56,7 +56,7 @@ export class EventLog {
     const file = Bun.file(this.path);
     const text = await ifPresent(() => file.slice(start.offset).text(), "");
 
-    // A trailing fragment is a write in progress: stop short of it or reads lose entries.
+    // Skip a trailing partial line; it is still being written.
     const lastBreak = text.lastIndexOf("\n");
     if (lastBreak === -1) {
       return [];
@@ -92,24 +92,18 @@ export class EventLog {
     return undefined;
   }
 
-  /** The `seq` of the last complete line, without parsing any of them. */
+  /** The `seq` of the last complete line. */
   public async head(): Promise<number> {
     await this.read(Number.MAX_SAFE_INTEGER);
     return this.cursor.seq;
   }
 
-  /**
-   * The name pi's own `/name` writes: the last `session_info` entry wins, and an
-   * empty one clears it. Appended rather than replaced, so it is found by reading
-   * the whole file — the one unbounded read the catalogue makes, and the only
-   * reason `SessionDigest` takes a whole file rather than a bounded head and tail.
-   */
+  /** The last `session_info` name; an empty one clears it. Reads the whole file. */
   public async name(): Promise<string | undefined> {
     const body = await durableBytes(Bun.file(this.path));
     return body === undefined ? undefined : SessionDigest.nameOf(body);
   }
 
-  /** Title and settle time for the catalogue, without opening a session. */
   public async digest(): Promise<SessionDigest> {
     const body = await durableBytes(Bun.file(this.path));
     return body === undefined
@@ -122,7 +116,7 @@ async function* headLines(
   file: BunFile,
   count: number
 ): AsyncGenerator<string> {
-  // Decode with `stream: true`: a chunk boundary can split a character.
+  // `stream: true`: a chunk boundary can split a character.
   const decoder = new TextDecoder();
   let pending = "";
   let yielded = 0;

package/packages/core/src/session/ReadCursors.ts

@@ -22,7 +22,6 @@ export class ReadCursors {
     this.ready = this.load();
   }
 
-  /** Whether a session has been answered since anything last read it. */
   public async isUnread(
     sessionId: string,
     answeredAt: number | undefined
@@ -34,7 +33,7 @@ export class ReadCursors {
     );
   }
 
-  /** Moves a session's cursor forward; the write behind it is not waited on. */
+  /** Only moves forward. Does not wait for the write. */
   public async mark(sessionId: string, at: number = Date.now()): Promise<void> {
     await this.ready;
     if ((this.cursors.get(sessionId) ?? this.baseline) >= at) {
@@ -58,7 +57,7 @@ export class ReadCursors {
     }
   }
 
-  /** Settles the writes behind the marks taken so far, for a clean stop. */
+  /** Waits for pending writes. */
   public async flush(): Promise<void> {
     await this.ready;
     await this.writes.run(async () => undefined);
@@ -69,7 +68,7 @@ export class ReadCursors {
       .json()
       .catch(() => undefined)) as Partial<Stored> | undefined;
     if (typeof stored?.baseline !== "number") {
-      // Persist the baseline now: recomputing it on each start clears every unread session.
+      // Persist it, or every restart would mark everything read.
       this.baseline = Date.now();
       this.persist();
       return;

package/packages/core/src/session/SearchIndex.ts

@@ -13,59 +13,56 @@ import {
 } from "./SessionDigest";
 import type { SessionSummary } from "./SessionRegistry";
 
-/** Half-open character offsets into the string they mark, non-overlapping, ascending. */
+/** Half-open character offsets; non-overlapping and ascending. */
 export type SearchRange = readonly [start: number, end: number];
 
 export type SearchSnippet = {
   readonly seq: number;
   readonly role: "user" | "assistant";
-  /** The windowed snippet, verbatim from the message. */
   readonly text: string;
   /** Offsets into `text`, not into the message. */
   readonly ranges: readonly SearchRange[];
-  /** The window opened past the message's first word. */
+  /** The snippet does not start at the message start. */
   readonly cutHead?: true;
 };
 
 export type SearchHit = {
   readonly sessionId: string;
   readonly cwd: string;
-  /** This machine's path to the session file: local to whoever reads it, and never fit for a wire. */
+  /** Local file path; do not send over the wire. */
   readonly path: string;
   readonly title?: string;
   readonly named?: true;
   /** Offsets into the clamped `title`. */
   readonly titleRanges: readonly SearchRange[];
-  /** The session's opening ask, for a row whose name is all that matched and so has no snippet to show. */
+  /** The first user message; set only for named sessions. */
   readonly opening?: string;
-  /** End of the last completed turn, falling back to when the session started: a row always has a clock to print. */
+  /** End of the last completed turn, else the session's creation time. */
   readonly settledAt: number;
   readonly snippets: readonly SearchSnippet[];
   /** Matching messages in this session, before the snippet cut. */
   readonly total: number;
-  /** This hit was reached through typo expansion, so it ranks below every exact hit. */
+  /** Matched only via typo expansion; ranks below exact hits. */
   readonly typos: boolean;
 };
 
 export type SearchAnswer = {
   readonly hits: readonly SearchHit[];
-  /** Query words dropped because they were too rare; the UI says these out loud. */
+  /** Query words dropped to get any results, rarest first. */
   readonly dropped: readonly string[];
-  /** Sessions searched. */
   readonly scanned: number;
 };
 
 export type SearchOptions = {
   readonly limit?: number;
   readonly cwd?: string;
-  /** Applied before the limit, so the server can exclude sessions without core knowing why. */
+  /** Applied before `limit`. */
   readonly accept?: (sessionId: string) => boolean;
 };
 
 export type SearchIndexDeps = {
-  /** `SessionRegistry.list` in production; a fake in tests. */
   readonly list: () => Promise<readonly SessionSummary[]>;
-  /** Only the refresh throttle reads it, and only a test replaces it. */
+  /** Clock for the refresh throttle. */
   readonly now?: () => number;
 };
 
@@ -83,9 +80,9 @@ type Entry = {
   readonly path: string;
   readonly createdAt: number;
   modifiedAt: number;
-  /** Durable bytes taken from the file, and the resume point of the next tail read. */
+  /** Bytes read so far; the next tail read starts here. */
   offset: number;
-  /** Durable lines taken, so an appended one keeps counting from the right ordinal. */
+  /** Lines read so far. */
   seq: number;
   parts: DigestParts;
   digest: SessionDigest;
@@ -97,23 +94,22 @@ type Posting = {
   readonly turn: Turn;
 };
 
-/** What one file's read yielded: `full` replaces the entry, otherwise it extends it. */
+/** `full` replaces the entry; otherwise `body` is appended to it. */
 type Read = {
   readonly full: boolean;
   readonly body?: Durable;
 };
 
-/** One file's read, folded into its entry and with the bytes already let go. */
 type Taken = {
   readonly entry: Entry;
-  /** Turns the entry held before this read, so only the appended ones are posted. */
+  /** Turn count before this read; later turns are new. */
   readonly from: number;
-  /** A whole file read over an entry we already had, so every ordinal it owned is stale. */
+  /** An existing entry was re-read in full, so postings must be rebuilt. */
   readonly replaced: boolean;
 };
 
 type Plan = {
-  /** Terms reached with no typos: the word itself, and prefixes of it when it is last. */
+  /** The word itself, plus completions when it is the last word. */
   readonly exact: readonly string[];
   readonly typo: readonly string[];
 };
@@ -124,11 +120,7 @@ type Group = {
   exact: boolean;
 };
 
-/**
- * Everything `byRank` weighs, taken from the group alone: no message is
- * tokenised until the sort has cut the losers, and four in five matched
- * sessions never reach a snippet.
- */
+/** Rank inputs, computed without tokenising any message. */
 type Ranked = {
   readonly entry: Entry;
   readonly group: Group;
@@ -140,45 +132,34 @@ type Ranked = {
 
 const FILE_READS = 16;
 
-/** The granularity at which the catalogue already decided file changes become visible. */
 const REFRESH_MS = 500;
 
-/** Typesense's `typo_tokens_threshold`: below this many results, and only then, typos are allowed in. */
+/** Typesense's `typo_tokens_threshold`: typos are tried only below this many results. */
 const ENOUGH = 1;
 
-/** Typesense's `max_candidates`; unbounded expansion is where precision dies. */
+/** Typesense's `max_candidates`. */
 const MAX_CANDIDATES = 4;
 
 const MAX_TYPOS = 2;
 
-/** Typesense's `highlight_affix_num_tokens`, for the run-up only: how far back of the match a window opens. */
+/** Typesense's `highlight_affix_num_tokens`: tokens shown before the first match. */
 const AFFIX = 4;
 
-/**
- * How far past the window's start a snippet runs. A row is cut to pixels, and
- * only the row knows how many it has, so the tail is not a window at all: it is
- * more text than the widest row can draw — the modal is capped at 30rem, which
- * is about 59 of these characters — and the client's own ellipsis does the
- * cutting. A word count here cut short rows shorter still, on the wide screens
- * that had the most room to spare.
- */
+/** Snippet length in characters; more than the widest row shows, so the client's ellipsis cuts it. */
 const TAIL = 100;
 
 const SNIPPETS = 2;
 
-/** What a row draws of an opening ask before its own box cuts it anyway. */
 const PREVIEW = 200;
 
 const LIMIT = 20;
 
-/** Cheap reject before decoding a line: no text part, nothing to index. */
+/** Lines without this are skipped before decoding. */
 const TEXT = Buffer.from('"text"');
 
 /**
- * An inverted index over what was said in every session on disk: `user:text`
- * and `assistant:text` only, which is a sixtieth of the bytes a session tree
- * weighs. Built lazily on the first query and refreshed by later ones, never
- * by a watcher, so the cold cost belongs to whoever searches.
+ * Inverted index over user and assistant text in every session, plus titles.
+ * Built on the first query and refreshed incrementally by later ones.
  */
 export class SearchIndex {
   private readonly list: () => Promise<readonly SessionSummary[]>;
@@ -229,13 +210,13 @@ export class SearchIndex {
       hits: ranked
         .sort(byRank)
         .slice(0, options.limit ?? LIMIT)
-        .map((one) => hitOf(one)),
+        .map(hitOf),
       dropped,
       scanned: scope.size,
     };
   }
 
-  /** Exact and prefix first; typos only widen a result set that came back thin. */
+  /** Exact and prefix first; adds typos only while results are too few. */
   private run(words: readonly string[], scope: ReadonlySet<Entry>): Ranked[] {
     const reach = Math.min(MAX_TYPOS, Math.max(...words.map(gateOf)));
     const last = words.length - 1;
@@ -286,15 +267,11 @@ export class SearchIndex {
   }
 
   private collect(plans: readonly Plan[], scope: ReadonlySet<Entry>): Ranked[] {
-    const turnsExact = plans.map((plan) =>
-      this.union(this.postings, plan.exact)
-    );
-    const titlesExact = plans.map((plan) =>
-      this.union(this.titles, plan.exact)
-    );
+    const turnsExact = plans.map((plan) => union(this.postings, plan.exact));
+    const titlesExact = plans.map((plan) => union(this.titles, plan.exact));
     const everything = plans.map((plan) => [...plan.exact, ...plan.typo]);
-    const turns = everything.map((terms) => this.union(this.postings, terms));
-    const titles = everything.map((terms) => this.union(this.titles, terms));
+    const turns = everything.map((terms) => union(this.postings, terms));
+    const titles = everything.map((terms) => union(this.titles, terms));
     const terms = new Set(everything.flat());
 
     const groups = new Map<Entry, Group>();
@@ -363,19 +340,6 @@ export class SearchIndex {
       .slice(0, MAX_CANDIDATES);
   }
 
-  private union<T>(
-    index: ReadonlyMap<string, T[]>,
-    terms: readonly string[]
-  ): ReadonlySet<T> {
-    const found = new Set<T>();
-    for (const term of terms) {
-      for (const value of index.get(term) ?? []) {
-        found.add(value);
-      }
-    }
-    return found;
-  }
-
   private vocabularyOf(): readonly string[] {
     if (this.vocabularyStale) {
       this.vocabulary = [
@@ -421,9 +385,7 @@ export class SearchIndex {
       }
     }
 
-    // A posting is an ordinal into one flat array of turns, which only holds
-    // while every entry keeps the turns it had; a replaced or departed session
-    // invalidates the lot, and an appended one does not.
+    // Postings are indices into `turns`, so a replaced or removed session forces a full reindex.
     if (replaced) {
       this.reindex();
     } else {
@@ -436,11 +398,7 @@ export class SearchIndex {
     this.syncedAt = this.now();
   }
 
-  /**
-   * One file's bytes end here, with the turns and parts taken out of them:
-   * held until the pool drained instead, a whole session tree would be
-   * resident at once. The entry lands in `entries` in the caller's order.
-   */
+  /** Absorbs the file's bytes immediately so they are not all held at once. */
   private async take(summary: SessionSummary): Promise<Taken | undefined> {
     const read = await this.read(summary);
     if (read === undefined) {
@@ -456,11 +414,7 @@ export class SearchIndex {
     return { entry, from, replaced: read.full && known !== undefined };
   }
 
-  /**
-   * A session file is append-only, so the usual read is the bytes past the
-   * stored offset. Only a file that shrank or whose mtime went backwards has
-   * been rewritten under us, and only that forces the whole file again.
-   */
+  /** Reads only the appended tail, unless the file shrank or its mtime went backwards. */
   private async read(summary: SessionSummary): Promise<Read | undefined> {
     const known = this.entries.get(summary.sessionId);
     const file = Bun.file(summary.path);
@@ -643,7 +597,7 @@ function rangesOf(
   return rangesIn(SearchTokens.scan(text), terms, 0, text.length);
 }
 
-/** Offsets into the cut the caller is about to make, not into the string the tokens came from. */
+/** Ranges within `[from, to)`, relative to `from`. */
 function rangesIn(
   tokens: readonly SearchToken[],
   terms: ReadonlySet<string>,
@@ -675,12 +629,12 @@ function merge(ranges: readonly SearchRange[]): readonly SearchRange[] {
   return marked;
 }
 
-/** What you asked is more memorable than what the agent answered. */
+/** User turns first, then by seq. */
 function byRecognition(a: Turn, b: Turn): number {
   return a.role === b.role ? a.seq - b.seq : a.role === "user" ? -1 : 1;
 }
 
-/** The turn a hit will lead with, without sorting the ones it will never show. */
+/** The first turn by `byRecognition`, without sorting. */
 function leadOf(turns: readonly Turn[]): Turn | undefined {
   let lead: Turn | undefined;
   for (const turn of turns) {
@@ -698,11 +652,7 @@ function byRank(a: Ranked, b: Ranked): number {
   return a.field - b.field || b.settledAt - a.settledAt;
 }
 
-/**
- * A title match outranks a spoken one. The title index is built from the very
- * tokens `rangesOf` marks, so a titled group always has a range to show, and
- * the field is settled without cutting a single snippet.
- */
+/** Title match, then user turn, then assistant turn. */
 function fieldOf(group: Group, title: string | undefined): number {
   if (group.title && title !== undefined) {
     return 0;
@@ -737,6 +687,19 @@ function groupIn(groups: Map<Entry, Group>, entry: Entry): Group {
   return found;
 }
 
+function union<T>(
+  index: ReadonlyMap<string, T[]>,
+  terms: readonly string[]
+): ReadonlySet<T> {
+  const found = new Set<T>();
+  for (const term of terms) {
+    for (const value of index.get(term) ?? []) {
+      found.add(value);
+    }
+  }
+  return found;
+}
+
 function intersect<T>(sets: readonly ReadonlySet<T>[]): ReadonlySet<T> {
   const [first, ...rest] = [...sets].sort((a, b) => a.size - b.size);
   if (first === undefined) {