@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/session/title.d.ts

@@ -1,67 +1,13 @@
-/**
- * Daemon-generated session TITLES (PHNX-3797).
- *
- * The headline on a session row answers "what is this session about?", so it has
- * to be anchored in what the USER asked for. It used to be the agent's latest
- * transcript line — verbose, rolling, and unrecognizable to the person who
- * started the run. The fix is a two-rung answer:
- *
- *  1. INSTANT, free: the user's own first message (already in the index) is the
- *     honest fallback shown from the moment the session appears.
- *  2. UPGRADED, once: this module asks a CHEAP model (via a swappable
- *     {@link SessionTitleProvider}; the default {@link CloudSessionTitleProvider}
- *     uses the `cheap` tier — haiku on Claude — through the same
- *     `agents run --model <tier>` resolution every other call uses) for a short
- *     ACTION + OBJECT headline of what the session is doing, and persists it in
- *     the session index.
- *
- * Generation happens ONCE per session, in the daemon, and is keyed by
- * {@link sessionTitleSourceKey} — a hash of the user text the title was derived
- * from — so a sweep that sees a stored key matching the row's current text skips
- * it (the cache hit) and regenerates only when that first user message actually
- * changed, or when an operator asks explicitly
- * (`agents sessions backfill titles --refresh`). There is no per-tick model call
- * and no per-client generation: the daemon writes one value, every consumer
- * (local list, picker, `sessions watch --json`, the fleet mirror, AGI EXT) reads
- * it off the row.
- *
- * Everything here except {@link runSessionTitleTick} is pure, and the tick takes
- * an injectable runner seam, so the whole path is testable without spawning a
- * harness.
- */
 import type { SessionTitleCandidateRow } from './db.js';
-/**
- * The phrase every generated-title prompt carries. Load-bearing twice over:
- * `traces/sync.ts` classifies a session whose topic matches it as internal
- * `utility` plumbing rather than agent work, and {@link isSessionTitlePrompt}
- * uses it to keep the titler from titling its OWN spawned sessions — which
- * would otherwise be a runaway loop, since each generation creates one more
- * untitled session.
- *
- * It is a STABLE sentinel, not the human-readable instruction: keep it exact and
- * keep `traces/sync.ts`'s matching regex in sync when it changes. The surrounding
- * prompt (see {@link renderSessionTitlePrompt}) asks for an action+object headline
- * of 4–8 words; the sentinel deliberately carries no word budget so the two never
- * drift.
- */
 export declare const SESSION_TITLE_PROMPT_MARKER = "Generate a concise session headline";
-/** Hard ceiling on a stored title; the prompt asks for far less. */
 export declare const SESSION_TITLE_MAX_CHARS = 60;
-/** Hard ceiling on words kept from a model reply that ignored the word budget. */
 export declare const SESSION_TITLE_MAX_WORDS = 8;
-/** How much user text the prompt carries — enough to be specific, bounded for cost. */
 export declare const SESSION_TITLE_INPUT_MAX_CHARS = 2000;
-/** How many sessions one periodic sweep may generate for. */
 export declare const SESSION_TITLE_MAX_PER_TICK = 2;
-/** How many recent rows a sweep inspects before picking that batch. */
 export declare const SESSION_TITLE_CANDIDATE_SCAN = 200;
-/** Only sessions active within this window are titled — older rows are not shown. */
 export declare const SESSION_TITLE_MAX_AGE_MS: number;
-/** Per-generation subprocess ceiling. A title is not worth waiting on. */
 export declare const SESSION_TITLE_TIMEOUT_MS = 45000;
-/** The harnesses the titler will run as, best first. The first installed one wins. */
 export declare const SESSION_TITLE_AGENTS: readonly ["claude", "codex", "grok", "kimi", "opencode"];
-/** The user text a title is derived from, plus the context that makes it technical. */
 export interface SessionTitleInput {
     firstUserMessage?: string | null;
     topic?: string | null;
@@ -69,170 +15,51 @@ export interface SessionTitleInput {
     ticketId?: string | null;
     gitBranch?: string | null;
 }
-/** The user text itself — the ONLY thing the source key is computed over. */
 export declare function sessionTitleSourceText(input: SessionTitleInput): string;
-/**
- * Stable identity of the text a title was generated from. Storing this beside
- * the title is what makes "already titled" distinguishable from "the user's
- * first message changed" without keeping a second copy of that text.
- * Empty text yields `null`: there is nothing to title.
- */
 export declare function sessionTitleSourceKey(input: SessionTitleInput): string | null;
-/**
- * True when this text is one of the titler's OWN prompts. The titler runs a real
- * harness, which writes a real transcript, which lands in the index as another
- * untitled session — so without this guard every title generated would create
- * work for the next sweep, forever.
- */
 export declare function isSessionTitlePrompt(...values: Array<string | null | undefined>): boolean;
-/**
- * The one-shot prompt handed to the cheap model.
- *
- * It asks for a descriptive ACTION + OBJECT headline (a verb phrase naming the
- * concrete task, "Triage the AGI board", "Rename browser profile — default
- * confusion"), not a single terse noun ("Triage") and not a full sentence — the
- * headline slot has to tell the person who started the run what the session is
- * doing at a glance. The word budget is soft in the prompt and hard-enforced by
- * {@link sanitizeGeneratedTitle}'s {@link SESSION_TITLE_MAX_WORDS} ceiling.
- */
 export declare function renderSessionTitlePrompt(input: SessionTitleInput): string;
-/**
- * Reduce a model reply to a storable title, or `undefined` when it produced
- * nothing usable. Takes the first non-empty line (a chatty model puts the title
- * first), strips wrapping quotes/backticks and trailing punctuation, and applies
- * the word + character ceilings. A reply that is really a refusal or an
- * explanation fails the ceilings and is dropped rather than shown.
- */
 export declare function sanitizeGeneratedTitle(raw: string | null | undefined): string | undefined;
-/**
- * Compile-time guard: resolves to `T` only when `T` actually declares a
- * `generatedTitle` key, and to `never` otherwise.
- *
- * This exists because structural typing makes the obvious signature useless. A
- * parameter typed `{ generatedTitle?: string }` is satisfied by an object type
- * that has no such property at all, so passing a projection that DROPPED the
- * field — the watchdog's `SessionOutcome`, which copied `label`/`name`/`topic`
- * off the session and left `generatedTitle` behind — compiles cleanly and
- * silently degrades {@link sessionHeadline} back to `label || topic`. That is a
- * real bug this feature shipped once and a lexical lint cannot see, since the
- * call site looks correct. `keyof` includes optional keys, so every legitimate
- * carrier (`SessionMeta`, `ActiveSession`, a `Pick<>` that names it) still
- * passes; only a type that never modelled the rung is rejected.
- */
 type CarriesTitleRung<T> = 'generatedTitle' extends keyof T ? T : never;
-/**
- * The headline for an INDEXED session row, on the same ladder the live path uses
- * (`deriveSessionRecap`, active.ts): `/rename` label → daemon-generated title →
- * first-prompt topic. Every `agents sessions` surface that shows "what this
- * session is" reads it from here, so the CLI and the watch stream can never
- * disagree about a session's name (PHNX-3797).
- *
- * A caller whose row type does not carry `generatedTitle` fails to compile
- * (see {@link CarriesTitleRung}) — fix the projection to carry the field rather
- * than casting past this.
- */
 export declare function sessionHeadline<T extends {
     label?: string | null;
     generatedTitle?: string | null;
     topic?: string | null;
 }>(row: CarriesTitleRung<T>): string | undefined;
-/**
- * Runs the cheap model once and returns its raw stdout. Injectable so tests
- * exercise the whole tick — candidate selection, key comparison, persistence —
- * without spawning a harness.
- */
 export type SessionTitleRunner = (prompt: string, signal?: AbortSignal) => Promise<string>;
-/** The harness the titler runs as on this box, or null when none is installed. */
 export declare function resolveSessionTitleAgent(): Promise<string | null>;
-/**
- * The real runner: ONE `agents run <agent> --mode plan --model cheap <prompt>`
- * subprocess. `--mode plan` keeps it read-only (it must never touch a repo), and
- * `--model cheap` goes through the same tier resolution every other run uses, so
- * the box's own catalog picks haiku (or its per-harness equivalent) rather than
- * this module hardcoding a model id that ages out.
- */
 export declare function defaultSessionTitleRunner(prompt: string, signal?: AbortSignal): Promise<string>;
-/**
- * A pluggable backend that turns a session's user text into a raw headline reply
- * — the ONE part of title generation that varies by model host (PHNX-3797).
- *
- * The tick decides WHICH sessions need a title, caches by source key, sanitizes,
- * and persists — none of that is provider-specific, so only the model call itself
- * sits behind this interface. The shipped default is
- * {@link CloudSessionTitleProvider} (one cheap cloud-model subprocess). A LOCAL
- * backend — e.g. an ollama 1–3B instruct model over HTTP — is a drop-in: implement
- * `generate` and hand the instance to {@link runSessionTitleTick} (or construct
- * {@link SessionTitleService} with it). No call site inside the tick changes, and
- * the shared {@link sanitizeGeneratedTitle} still enforces the word/character
- * ceilings on whatever text the backend returns.
- *
- * `generate` returns the model's RAW reply (the tick owns sanitizing). It MAY
- * throw — harness missing, signed out, timed out — and the tick treats a throw as
- * "no title this sweep", leaving the row on the user's own words and backing off.
- */
 export interface SessionTitleProvider {
-    /** Stable id for logs/diagnostics (e.g. `'cloud'`, `'ollama'`). */
     readonly name: string;
-    /** Produce a raw headline reply for one session's user text, or throw. */
     generate(input: SessionTitleInput, signal?: AbortSignal): Promise<string>;
 }
-/**
- * The default, shipped provider: render the shared prompt and run it through a
- * {@link SessionTitleRunner} — by default {@link defaultSessionTitleRunner}, the
- * one cheap `agents run --model cheap` subprocess. Tests inject a fake runner (or
- * a whole fake provider) to exercise the tick without spawning a harness.
- */
 export declare class CloudSessionTitleProvider implements SessionTitleProvider {
     private readonly runner;
     readonly name = "cloud";
     constructor(runner?: SessionTitleRunner);
     generate(input: SessionTitleInput, signal?: AbortSignal): Promise<string>;
 }
-/** The provider used when a caller injects neither a `provider` nor a `run`. */
 export declare function defaultSessionTitleProvider(): SessionTitleProvider;
 export interface SessionTitleTickOptions {
-    /** Max sessions generated for in this sweep. */
     limit?: number;
-    /** Title this session specifically (an explicit refresh), ignoring the recency window. */
     id?: string;
-    /** Regenerate even when the stored key still matches the row's user text. */
     force?: boolean;
-    /**
-     * The generation backend. Defaults to {@link defaultSessionTitleProvider}
-     * (the cheap cloud model). Swap this for a local model without touching the
-     * tick. Takes precedence over {@link SessionTitleTickOptions.run}.
-     */
     provider?: SessionTitleProvider;
-    /**
-     * Shortcut seam for the cloud provider's raw model call — wrapped in a
-     * {@link CloudSessionTitleProvider} when no {@link provider} is given. Kept for
-     * the daemon service and the tests that inject only the subprocess.
-     */
     run?: SessionTitleRunner;
     signal?: AbortSignal;
     nowMs?: number;
     maxAgeMs?: number;
 }
 export interface SessionTitleTickResult {
-    /** Rows inspected. */
     scanned: number;
-    /** Rows already carrying a title for their current user text (the cache hit). */
     cached: number;
-    /** Titles generated and persisted this sweep. */
     generated: number;
-    /** Generation attempts that produced nothing usable (model unavailable, empty reply). */
     failed: number;
     titles: Array<{
         id: string;
         title: string;
     }>;
 }
-/**
- * Decide what one sweep should do, without touching the model. Pure over its
- * inputs so the "generate once, then cache-hit" property is directly testable:
- * a candidate is work only when its user text yields a key AND that key differs
- * from the one stored beside its title (or `force`).
- */
 export declare function selectSessionsNeedingTitle(rows: SessionTitleCandidateRow[], opts?: {
     limit: number;
     force?: boolean;
@@ -243,14 +70,5 @@ export declare function selectSessionsNeedingTitle(rows: SessionTitleCandidateRo
     }>;
     cached: number;
 };
-/**
- * One titling sweep: pick the sessions whose headline is still the raw user
- * message, generate a title for at most {@link SessionTitleTickOptions.limit} of
- * them, and persist each. Best-effort by contract — a failed generation leaves
- * the row untitled, which the ladder renders as the user's own first message.
- *
- * Throws only for an explicit {@link SessionTitleTickOptions.id} that matches no
- * indexed session (a caller error); the periodic sweep never throws.
- */
 export declare function runSessionTitleTick(options?: SessionTitleTickOptions): Promise<SessionTitleTickResult>;
 export {};

package/dist/lib/session/title.js

@@ -1,102 +1,26 @@
-/**
- * Daemon-generated session TITLES (PHNX-3797).
- *
- * The headline on a session row answers "what is this session about?", so it has
- * to be anchored in what the USER asked for. It used to be the agent's latest
- * transcript line — verbose, rolling, and unrecognizable to the person who
- * started the run. The fix is a two-rung answer:
- *
- *  1. INSTANT, free: the user's own first message (already in the index) is the
- *     honest fallback shown from the moment the session appears.
- *  2. UPGRADED, once: this module asks a CHEAP model (via a swappable
- *     {@link SessionTitleProvider}; the default {@link CloudSessionTitleProvider}
- *     uses the `cheap` tier — haiku on Claude — through the same
- *     `agents run --model <tier>` resolution every other call uses) for a short
- *     ACTION + OBJECT headline of what the session is doing, and persists it in
- *     the session index.
- *
- * Generation happens ONCE per session, in the daemon, and is keyed by
- * {@link sessionTitleSourceKey} — a hash of the user text the title was derived
- * from — so a sweep that sees a stored key matching the row's current text skips
- * it (the cache hit) and regenerates only when that first user message actually
- * changed, or when an operator asks explicitly
- * (`agents sessions backfill titles --refresh`). There is no per-tick model call
- * and no per-client generation: the daemon writes one value, every consumer
- * (local list, picker, `sessions watch --json`, the fleet mirror, AGI EXT) reads
- * it off the row.
- *
- * Everything here except {@link runSessionTitleTick} is pure, and the tick takes
- * an injectable runner seam, so the whole path is testable without spawning a
- * harness.
- */
 import { createHash } from 'node:crypto';
-/**
- * The phrase every generated-title prompt carries. Load-bearing twice over:
- * `traces/sync.ts` classifies a session whose topic matches it as internal
- * `utility` plumbing rather than agent work, and {@link isSessionTitlePrompt}
- * uses it to keep the titler from titling its OWN spawned sessions — which
- * would otherwise be a runaway loop, since each generation creates one more
- * untitled session.
- *
- * It is a STABLE sentinel, not the human-readable instruction: keep it exact and
- * keep `traces/sync.ts`'s matching regex in sync when it changes. The surrounding
- * prompt (see {@link renderSessionTitlePrompt}) asks for an action+object headline
- * of 4–8 words; the sentinel deliberately carries no word budget so the two never
- * drift.
- */
 export const SESSION_TITLE_PROMPT_MARKER = 'Generate a concise session headline';
-/** Hard ceiling on a stored title; the prompt asks for far less. */
 export const SESSION_TITLE_MAX_CHARS = 60;
-/** Hard ceiling on words kept from a model reply that ignored the word budget. */
 export const SESSION_TITLE_MAX_WORDS = 8;
-/** How much user text the prompt carries — enough to be specific, bounded for cost. */
 export const SESSION_TITLE_INPUT_MAX_CHARS = 2000;
-/** How many sessions one periodic sweep may generate for. */
 export const SESSION_TITLE_MAX_PER_TICK = 2;
-/** How many recent rows a sweep inspects before picking that batch. */
 export const SESSION_TITLE_CANDIDATE_SCAN = 200;
-/** Only sessions active within this window are titled — older rows are not shown. */
 export const SESSION_TITLE_MAX_AGE_MS = 14 * 24 * 60 * 60_000;
-/** Per-generation subprocess ceiling. A title is not worth waiting on. */
 export const SESSION_TITLE_TIMEOUT_MS = 45_000;
-/** The harnesses the titler will run as, best first. The first installed one wins. */
 export const SESSION_TITLE_AGENTS = ['claude', 'codex', 'grok', 'kimi', 'opencode'];
-/** The user text itself — the ONLY thing the source key is computed over. */
 export function sessionTitleSourceText(input) {
     const raw = (input.firstUserMessage || input.topic || '').replace(/\s+/g, ' ').trim();
     return raw.length > SESSION_TITLE_INPUT_MAX_CHARS ? raw.slice(0, SESSION_TITLE_INPUT_MAX_CHARS) : raw;
 }
-/**
- * Stable identity of the text a title was generated from. Storing this beside
- * the title is what makes "already titled" distinguishable from "the user's
- * first message changed" without keeping a second copy of that text.
- * Empty text yields `null`: there is nothing to title.
- */
 export function sessionTitleSourceKey(input) {
     const text = sessionTitleSourceText(input);
     if (!text)
         return null;
     return createHash('sha256').update(text).digest('hex').slice(0, 16);
 }
-/**
- * True when this text is one of the titler's OWN prompts. The titler runs a real
- * harness, which writes a real transcript, which lands in the index as another
- * untitled session — so without this guard every title generated would create
- * work for the next sweep, forever.
- */
 export function isSessionTitlePrompt(...values) {
     return values.some((v) => typeof v === 'string' && v.includes(SESSION_TITLE_PROMPT_MARKER));
 }
-/**
- * The one-shot prompt handed to the cheap model.
- *
- * It asks for a descriptive ACTION + OBJECT headline (a verb phrase naming the
- * concrete task, "Triage the AGI board", "Rename browser profile — default
- * confusion"), not a single terse noun ("Triage") and not a full sentence — the
- * headline slot has to tell the person who started the run what the session is
- * doing at a glance. The word budget is soft in the prompt and hard-enforced by
- * {@link sanitizeGeneratedTitle}'s {@link SESSION_TITLE_MAX_WORDS} ceiling.
- */
 export function renderSessionTitlePrompt(input) {
     const text = sessionTitleSourceText(input);
     const context = [
@@ -120,13 +44,6 @@ export function renderSessionTitlePrompt(input) {
         '---',
     ].join('\n');
 }
-/**
- * Reduce a model reply to a storable title, or `undefined` when it produced
- * nothing usable. Takes the first non-empty line (a chatty model puts the title
- * first), strips wrapping quotes/backticks and trailing punctuation, and applies
- * the word + character ceilings. A reply that is really a refusal or an
- * explanation fails the ceilings and is dropped rather than shown.
- */
 export function sanitizeGeneratedTitle(raw) {
     if (!raw)
         return undefined;
@@ -141,36 +58,19 @@ export function sanitizeGeneratedTitle(raw) {
         .trim();
     if (!title)
         return undefined;
-    // A model that ignored the budget gets truncated, not shown in full — a
-    // paragraph in the headline slot is the very failure this feature removes.
     const words = title.split(' ');
     if (words.length > SESSION_TITLE_MAX_WORDS)
         title = words.slice(0, SESSION_TITLE_MAX_WORDS).join(' ');
     if (title.length > SESSION_TITLE_MAX_CHARS)
         title = title.slice(0, SESSION_TITLE_MAX_CHARS).trimEnd();
-    // Never store the prompt back as a title (a harness that echoed its input).
     if (isSessionTitlePrompt(title))
         return undefined;
     return title || undefined;
 }
-/**
- * The headline for an INDEXED session row, on the same ladder the live path uses
- * (`deriveSessionRecap`, active.ts): `/rename` label → daemon-generated title →
- * first-prompt topic. Every `agents sessions` surface that shows "what this
- * session is" reads it from here, so the CLI and the watch stream can never
- * disagree about a session's name (PHNX-3797).
- *
- * A caller whose row type does not carry `generatedTitle` fails to compile
- * (see {@link CarriesTitleRung}) — fix the projection to carry the field rather
- * than casting past this.
- */
 export function sessionHeadline(row) {
     return row.label || row.generatedTitle || row.topic || undefined;
 }
-/** The harness the titler runs as on this box, or null when none is installed. */
 export async function resolveSessionTitleAgent() {
-    // Lazy import: this module is also imported by render paths that must not pull
-    // the installation store (and its filesystem probes) into a hot listing.
     const { listInstalledVersions } = await import('../installations/store.js');
     for (const agent of SESSION_TITLE_AGENTS) {
         try {
@@ -178,18 +78,10 @@ export async function resolveSessionTitleAgent() {
                 return agent;
         }
         catch {
-            // An unreadable store for one agent must not hide the others.
         }
     }
     return null;
 }
-/**
- * The real runner: ONE `agents run <agent> --mode plan --model cheap <prompt>`
- * subprocess. `--mode plan` keeps it read-only (it must never touch a repo), and
- * `--model cheap` goes through the same tier resolution every other run uses, so
- * the box's own catalog picks haiku (or its per-harness equivalent) rather than
- * this module hardcoding a model id that ages out.
- */
 export async function defaultSessionTitleRunner(prompt, signal) {
     const [{ getAgentsInvocation }, { execFile }, { promisify }] = await Promise.all([
         import('../daemon/daemon.js'),
@@ -208,12 +100,6 @@ export async function defaultSessionTitleRunner(prompt, signal) {
     });
     return stdout;
 }
-/**
- * The default, shipped provider: render the shared prompt and run it through a
- * {@link SessionTitleRunner} — by default {@link defaultSessionTitleRunner}, the
- * one cheap `agents run --model cheap` subprocess. Tests inject a fake runner (or
- * a whole fake provider) to exercise the tick without spawning a harness.
- */
 export class CloudSessionTitleProvider {
     runner;
     name = 'cloud';
@@ -224,21 +110,13 @@ export class CloudSessionTitleProvider {
         return this.runner(renderSessionTitlePrompt(input), signal);
     }
 }
-/** The provider used when a caller injects neither a `provider` nor a `run`. */
 export function defaultSessionTitleProvider() {
     return new CloudSessionTitleProvider();
 }
-/**
- * Decide what one sweep should do, without touching the model. Pure over its
- * inputs so the "generate once, then cache-hit" property is directly testable:
- * a candidate is work only when its user text yields a key AND that key differs
- * from the one stored beside its title (or `force`).
- */
 export function selectSessionsNeedingTitle(rows, opts = { limit: SESSION_TITLE_MAX_PER_TICK }) {
     const pending = [];
     let cached = 0;
     for (const row of rows) {
-        // The titler's own runs are sessions too; titling them would spawn another.
         if (isSessionTitlePrompt(row.firstUserMessage, row.topic))
             continue;
         const sourceKey = sessionTitleSourceKey(row);
@@ -253,15 +131,6 @@ export function selectSessionsNeedingTitle(rows, opts = { limit: SESSION_TITLE_M
     }
     return { pending, cached };
 }
-/**
- * One titling sweep: pick the sessions whose headline is still the raw user
- * message, generate a title for at most {@link SessionTitleTickOptions.limit} of
- * them, and persist each. Best-effort by contract — a failed generation leaves
- * the row untitled, which the ladder renders as the user's own first message.
- *
- * Throws only for an explicit {@link SessionTitleTickOptions.id} that matches no
- * indexed session (a caller error); the periodic sweep never throws.
- */
 export async function runSessionTitleTick(options = {}) {
     const limit = options.limit ?? SESSION_TITLE_MAX_PER_TICK;
     const now = options.nowMs ?? Date.now();
@@ -271,9 +140,6 @@ export async function runSessionTitleTick(options = {}) {
         ? { id: options.id }
         : { sinceMs: now - (options.maxAgeMs ?? SESSION_TITLE_MAX_AGE_MS) });
     result.scanned = rows.length;
-    // An explicitly requested session that has no indexed row is a caller error,
-    // not a quiet sweep outcome: reporting "0 generated" would read as "already
-    // current" for an id that was simply mistyped or not scanned yet.
     if (options.id && rows.length === 0) {
         throw new Error(`no indexed session matches "${options.id}" on this machine — ` +
             `a session is titled after it is indexed (the daemon indexes within seconds), ` +
@@ -283,9 +149,6 @@ export async function runSessionTitleTick(options = {}) {
     result.cached = cached;
     if (pending.length === 0)
         return result;
-    // The provider is the ONLY thing that varies by model host; everything above
-    // (candidate selection, the source-key cache) and below (sanitize, persist) is
-    // shared. A local backend is dropped in here, not woven through the tick.
     const provider = options.provider ?? new CloudSessionTitleProvider(options.run);
     for (const { row, sourceKey } of pending) {
         if (options.signal?.aborted)
@@ -295,8 +158,6 @@ export async function runSessionTitleTick(options = {}) {
             title = sanitizeGeneratedTitle(await provider.generate(row, options.signal));
         }
         catch {
-            // Harness unavailable, signed out, or over its deadline. Best-effort: the
-            // row keeps showing the user's own words, and the caller backs off.
             title = undefined;
         }
         if (!title) {

package/dist/lib/session/tool-index.d.ts

@@ -1,5 +1,5 @@
-import { type IndexedToolCall } from './tool-calls.js';
-import type { SessionMeta } from './types.js';
+import { type IndexedToolCall } from '@phnx-labs/sessions-cli/reader';
+import type { SessionMeta } from '@phnx-labs/sessions-cli/reader';
 export declare const BACKFILL_MAX_STREAM_SOURCE_BYTES: number;
 export declare const TOOL_SEARCH_SCHEMA_VERSION = 1;
 export declare const TOOL_PROGRAM_COUNT_SCHEMA_VERSION = 1;
@@ -30,10 +30,6 @@ export interface ToolSessionEvidence {
     cwd?: string;
     topic?: string;
     label?: string;
-    /** The daemon-generated headline (PHNX-3797). Carried so a consumer of this
-     * envelope names a session the same way every other surface does; a
-     * projection that drops it silently degrades `sessionHeadline` to
-     * `label || topic`. */
     generatedTitle?: string;
     filePath?: string;
     calls: ToolCallEvidence[];
@@ -68,30 +64,15 @@ export interface ToolProgramCountEnvelope {
         totals: ToolProgramCountTotals;
     }>;
 }
-/** Serialize once and enforce headroom below the fleet transport's 16 MiB cap. */
 export declare function serializeToolSearchEnvelope(envelope: ToolSearchEnvelope): string;
-/** Exact UTF-8 size of the public pretty-JSON envelope. */
 export declare function serializedToolSearchEnvelopeBytes(envelope: ToolSearchEnvelope): number;
-/**
- * Reserve the exact local JSON plus coordinator headroom before retaining peer
- * stdout. Peer envelopes repeat metadata that disappears during merge, so
- * charging their full wire bytes against the remainder is conservative.
- */
 export declare function toolSearchRemoteReceiveBudget(envelope: ToolSearchEnvelope): number;
-/** Read index completeness from SQLite only; never stat or parse transcripts. */
 export declare function readToolIndexCoverage(sessions: SessionMeta[]): ToolIndexCoverage;
-/**
- * Fill one bounded chunk of the independent tool index. A warm call performs
- * only stat + ledger checks; it never opens or parses unchanged transcripts.
- */
 export declare function ensureToolIndex(sessions: SessionMeta[], limits?: {
     maxFiles?: number;
     maxBytes?: number;
     verifySourceStamps?: boolean;
 }): Promise<ToolIndexCoverage>;
-/** A count has one unambiguous subject: one exact `program:<name>` term. */
 export declare function parseToolProgramCountClause(source: string): string;
-/** Count exact, pre-indexed static program sites without reading transcripts. */
 export declare function countToolProgramOccurrences(sessions: SessionMeta[], program: string, coverage: ToolIndexCoverage, machine: string): ToolProgramCountEnvelope;
-/** Query cached evidence; every repeated clause must select a distinct call. */
 export declare function searchToolCalls(sessions: SessionMeta[], clauseSources: string[], coverage: ToolIndexCoverage, resultLimit?: number): ToolSearchEnvelope;