@phnx-labs/agents-cli 1.22.20 → 1.22.22

package/dist/lib/hosts/passthrough.js

@@ -46,6 +46,7 @@ const REMOTE_PASSTHROUGH = {
     list: {},
     usage: {},
     cost: {},
+    insights: {},
     output: {},
     budget: {},
     // config / resources

package/dist/lib/picker.d.ts

@@ -19,6 +19,12 @@ export interface PickerConfig<T> {
     initialSearch?: string;
     emptyMessage?: string;
     enterHint?: string;
+    /**
+     * Lines the caller already printed above the Inquirer prompt (e.g. the
+     * hidden-session footer). Subtracted from the row budget so the list page is
+     * capped to keep the preview — and those notices — on screen together.
+     */
+    linesAbovePrompt?: number;
 }
 /** The result returned when the user selects an item. */
 export interface PickedItem<T> {
@@ -37,7 +43,44 @@ export interface MultiPickerConfig<T> {
     initialSearch?: string;
     emptyMessage?: string;
     enterHint?: string;
+    /** See {@link PickerConfig.linesAbovePrompt}. */
+    linesAbovePrompt?: number;
 }
+/**
+ * Rows the detail preview is guaranteed when it is open and a row is selected.
+ * The list page is capped so this floor always fits the viewport — without it a
+ * long list (PICKER_RECENT_COUNT = 15) consumes the whole default 24-row
+ * terminal, `availablePreviewRows` goes <= 0, and the preview silently collapses
+ * to empty (RUSH-2198).
+ */
+export declare const PREVIEW_MIN_ROWS = 6;
+/** Floor for the visible list page, so a short terminal still shows a few rows. */
+export declare const PICKER_MIN_LIST_ROWS = 3;
+/**
+ * Cap the visible list page so an open preview keeps a guaranteed floor of rows.
+ *
+ * The picker renders header + list page + separator + preview + help. When the
+ * requested page size (e.g. 15) is large enough to fill the terminal on its own,
+ * the preview has no room left and collapses. This reserves
+ * {@link PREVIEW_MIN_ROWS} (plus its separator) for the preview and hands the
+ * list whatever remains, never below {@link PICKER_MIN_LIST_ROWS}.
+ *
+ * `chromeRows` counts the fixed non-list, non-preview lines (header, subtitle,
+ * help, any flash). `linesAbovePrompt` counts lines the caller printed above the
+ * Inquirer prompt that have scrolled the viewport but the picker cannot measure —
+ * today the session picker passes the hidden-session footer; subtracting it keeps
+ * that notice on screen alongside the preview. (The fleet browser folds its
+ * unreachable-peer warning into the header instead, so it needs no reserve here.)
+ */
+export declare function pickerPageSize(opts: {
+    requestedPageSize: number;
+    terminalRows: number;
+    chromeRows: number;
+    previewOpen: boolean;
+    linesAbovePrompt?: number;
+    previewMinRows?: number;
+    minListRows?: number;
+}): number;
 /** Clip a picker preview so the full prompt can fit in the terminal viewport. */
 export declare function limitPreviewHeight(preview: string, maxRows: number, width: number): string;
 /** Show an interactive fuzzy-filter picker and return the selected item, or null on cancel. */
@@ -93,6 +136,8 @@ export interface DynamicPickerConfig<T, F> {
     emptyMessage?: string;
     loadingMessage?: string;
     enterHint?: string;
+    /** See {@link PickerConfig.linesAbovePrompt}. */
+    linesAbovePrompt?: number;
 }
 /**
  * The lookup token for a hotkey: the literal character the key produced, else

package/dist/lib/picker.js

@@ -17,12 +17,47 @@ import chalk from 'chalk';
 import { stripVTControlCharacters } from 'node:util';
 const DEFAULT_TERMINAL_ROWS = 24;
 const DEFAULT_TERMINAL_WIDTH = 80;
+/**
+ * Rows the detail preview is guaranteed when it is open and a row is selected.
+ * The list page is capped so this floor always fits the viewport — without it a
+ * long list (PICKER_RECENT_COUNT = 15) consumes the whole default 24-row
+ * terminal, `availablePreviewRows` goes <= 0, and the preview silently collapses
+ * to empty (RUSH-2198).
+ */
+export const PREVIEW_MIN_ROWS = 6;
+/** Floor for the visible list page, so a short terminal still shows a few rows. */
+export const PICKER_MIN_LIST_ROWS = 3;
 function terminalWidth() {
     return Math.max(1, process.stdout.columns || DEFAULT_TERMINAL_WIDTH);
 }
 function terminalRows() {
     return Math.max(1, process.stdout.rows || DEFAULT_TERMINAL_ROWS);
 }
+/**
+ * Cap the visible list page so an open preview keeps a guaranteed floor of rows.
+ *
+ * The picker renders header + list page + separator + preview + help. When the
+ * requested page size (e.g. 15) is large enough to fill the terminal on its own,
+ * the preview has no room left and collapses. This reserves
+ * {@link PREVIEW_MIN_ROWS} (plus its separator) for the preview and hands the
+ * list whatever remains, never below {@link PICKER_MIN_LIST_ROWS}.
+ *
+ * `chromeRows` counts the fixed non-list, non-preview lines (header, subtitle,
+ * help, any flash). `linesAbovePrompt` counts lines the caller printed above the
+ * Inquirer prompt that have scrolled the viewport but the picker cannot measure —
+ * today the session picker passes the hidden-session footer; subtracting it keeps
+ * that notice on screen alongside the preview. (The fleet browser folds its
+ * unreachable-peer warning into the header instead, so it needs no reserve here.)
+ */
+export function pickerPageSize(opts) {
+    const previewMinRows = opts.previewMinRows ?? PREVIEW_MIN_ROWS;
+    const minListRows = opts.minListRows ?? PICKER_MIN_LIST_ROWS;
+    const linesAbove = Math.max(0, opts.linesAbovePrompt ?? 0);
+    // The separator line rides with the preview only when it is open.
+    const previewReserve = opts.previewOpen ? previewMinRows + 1 : 0;
+    const budget = opts.terminalRows - linesAbove - opts.chromeRows - previewReserve;
+    return Math.max(minListRows, Math.min(opts.requestedPageSize, budget));
+}
 function renderedRows(text, width) {
     const normalizedWidth = Math.max(1, width);
     return text.split('\n').reduce((rows, line) => {
@@ -157,6 +192,17 @@ export function itemPicker(config) {
             : '(type to filter)';
         const searchStr = searchTerm ? chalk.cyan(searchTerm) : chalk.gray(placeholder);
         const header = [prefix, message, searchStr].filter(Boolean).join(' ');
+        // Cap the list page so an open preview keeps a guaranteed floor of rows.
+        // chrome = header + optional subtitle + help; the preview separator is
+        // reserved inside pickerPageSize.
+        const chromeRows = 1 + (cfg.subtitle ? 1 : 0) + 1;
+        const effectivePageSize = pickerPageSize({
+            requestedPageSize: cfg.pageSize ?? 10,
+            terminalRows: terminalRows(),
+            chromeRows,
+            previewOpen: previewOpen && Boolean(cfg.buildPreview),
+            linesAbovePrompt: cfg.linesAbovePrompt,
+        });
         const page = usePagination({
             items: results,
             active,
@@ -167,7 +213,7 @@ export function itemPicker(config) {
                 const row = isActive ? chalk.bold(item.label) : item.label;
                 return `${cursor} ${row}`;
             },
-            pageSize: cfg.pageSize ?? 10,
+            pageSize: effectivePageSize,
             loop: false,
         });
         const enter = cfg.enterHint ?? 'select';
@@ -188,7 +234,7 @@ export function itemPicker(config) {
                 renderedRows(parts.slice(1).join('\n'), width) +
                 renderedRows(separator, width) +
                 renderedRows(help, width);
-            const availablePreviewRows = terminalRows() - fixedRows;
+            const availablePreviewRows = terminalRows() - Math.max(0, cfg.linesAbovePrompt ?? 0) - fixedRows;
             const preview = limitPreviewHeight(cfg.buildPreview(selected.value), availablePreviewRows, width);
             if (preview) {
                 parts.push(separator);
@@ -283,6 +329,17 @@ export function multiItemPicker(config) {
         const placeholder = '(type to filter · space to toggle · enter to resume)';
         const searchStr = searchTerm ? chalk.cyan(searchTerm) : chalk.gray(placeholder);
         const header = [prefix, message, searchStr].filter(Boolean).join(' ');
+        // Cap the list page so an open preview keeps a guaranteed floor of rows.
+        // chrome = header + help; the preview separator is reserved inside
+        // pickerPageSize.
+        const chromeRows = 2;
+        const effectivePageSize = pickerPageSize({
+            requestedPageSize: cfg.pageSize ?? 10,
+            terminalRows: terminalRows(),
+            chromeRows,
+            previewOpen: previewOpen && Boolean(cfg.buildPreview),
+            linesAbovePrompt: cfg.linesAbovePrompt,
+        });
         const page = usePagination({
             items: results,
             active,
@@ -295,7 +352,7 @@ export function multiItemPicker(config) {
                 const row = isActive ? chalk.bold(item.label) : item.label;
                 return `${cursor} ${box} ${row}`;
             },
-            pageSize: cfg.pageSize ?? 10,
+            pageSize: effectivePageSize,
             loop: false,
         });
         const enter = cfg.enterHint ?? 'resume';
@@ -312,7 +369,7 @@ export function multiItemPicker(config) {
                 renderedRows(parts.slice(1).join('\n'), width) +
                 renderedRows(separator, width) +
                 renderedRows(help, width);
-            const availablePreviewRows = terminalRows() - fixedRows;
+            const availablePreviewRows = terminalRows() - Math.max(0, cfg.linesAbovePrompt ?? 0) - fixedRows;
             const preview = limitPreviewHeight(cfg.buildPreview(selected.value), availablePreviewRows, width);
             if (preview) {
                 parts.push(separator);
@@ -553,6 +610,18 @@ export function dynamicPicker(config) {
             headerBits.push(chalk.cyan('/' + query));
         }
         const header = headerBits.filter(Boolean).join(' ');
+        // Cap the list page so an open preview keeps a guaranteed floor of rows.
+        // chrome = header + help + optional flash line; the preview separator is
+        // reserved inside pickerPageSize. Only the loaded list steals viewport, so
+        // skip the cap while the loading placeholder is showing.
+        const chromeRows = 2 + (flash ? renderedRows(flash, terminalWidth()) : 0);
+        const effectivePageSize = pickerPageSize({
+            requestedPageSize: cfg.pageSize ?? 12,
+            terminalRows: terminalRows(),
+            chromeRows,
+            previewOpen: previewOpen && Boolean(cfg.buildPreview) && !loading,
+            linesAbovePrompt: cfg.linesAbovePrompt,
+        });
         const page = usePagination({
             items: results,
             active,
@@ -563,7 +632,7 @@ export function dynamicPicker(config) {
                 const row = isActive ? chalk.bold(item.label) : item.label;
                 return `${cursor} ${row}`;
             },
-            pageSize: cfg.pageSize ?? 12,
+            pageSize: effectivePageSize,
             loop: false,
         });
         const help = chalk.gray(cfg.helpFor
@@ -590,7 +659,7 @@ export function dynamicPicker(config) {
                 renderedRows(separator, width) +
                 renderedRows(help, width) +
                 flashRows;
-            const availablePreviewRows = terminalRows() - fixedRows;
+            const availablePreviewRows = terminalRows() - Math.max(0, cfg.linesAbovePrompt ?? 0) - fixedRows;
             const preview = limitPreviewHeight(cfg.buildPreview(selected.value), availablePreviewRows, width);
             if (preview) {
                 parts.push(separator);

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

@@ -20,6 +20,13 @@ export declare const SCHEMA_VERSION = 33;
  * TOOL_INDEX_VERSION gives the tool backfill).
  */
 export declare const RESOURCE_INDEX_VERSION = 1;
+/**
+ * Bumping this invalidates every cached facet row without touching the schema
+ * version, so a change to the extraction logic (a new metric, a corrected bucket)
+ * re-derives on the next `agents insights` instead of silently reporting stale
+ * numbers alongside fresh ones. Same role as RESOURCE_INDEX_VERSION.
+ */
+export declare const INSIGHTS_EXTRACTOR_VERSION = 3;
 /** Raw row shape returned from the sessions table. */
 export interface SessionRow {
     id: string;
@@ -317,6 +324,33 @@ export interface UsageRollupRow {
     outputTokens: number;
 }
 /** What to group a usage rollup by. */
+/**
+ * Read cached facets for the given sessions, dropping any row that is stale.
+ *
+ * Staleness is decided in SQL against the session's own `file_mtime_ms` / `file_size`,
+ * the same pair the scanner maintains — so the cache cannot disagree with the index,
+ * `IS` rather than `=` so a source with no statable file — NULL on both sides — is a
+ * cache HIT rather than a permanent miss that re-parses it on every run.
+ */
+export declare function readSessionInsights<T>(ids: string[]): Map<string, T>;
+/**
+ * Persist freshly computed facets against the stamp of the bytes actually parsed.
+ *
+ * The caller passes the stat it observed when it read the file. Re-reading the stamp
+ * from the sessions table inside this INSERT would race: a concurrent rescan between
+ * the parse and the write (the cold path flushes in batches, so the window is minutes
+ * wide, and this module treats concurrent access as a design assumption) stamps NEW
+ * bytes onto OLD facets — a permanent false cache hit until the file changes again.
+ * tool-index.ts sets the precedent: stat at parse time, carry the stamp into the write.
+ */
+export declare function writeSessionInsights<T>(entries: Array<{
+    id: string;
+    fileMtimeMs: number | null;
+    fileSize: number | null;
+    facets: T;
+}>): void;
+/** Drop every cached facet row. Backs `agents insights --refresh`. */
+export declare function clearSessionInsights(): void;
 export type UsageRollupGroup = 'agent' | 'project' | 'day' | 'account';
 /**
  * Smart-launch affinity priors: group sessions by origin machine, harness, or

package/dist/lib/session/db.js

@@ -268,7 +268,33 @@ CREATE TABLE IF NOT EXISTS resource_scan_ledger (
   indexed_at INTEGER NOT NULL,
   resource_count INTEGER NOT NULL
 );
+
+-- Behavioural facets per session, for "agents insights". Deliberately its own table
+-- and deliberately NOT tied to SCHEMA_VERSION: it is created by CREATE TABLE IF NOT
+-- EXISTS and keyed on (file_mtime_ms, file_size), so it self-heals after any future
+-- migration that flushes a ledger, and adding it costs the hot "sessions" table
+-- nothing. Populated lazily by the insights command, never by a normal scan --
+-- parsing every transcript is far too expensive for the common listing path.
+-- file_mtime_ms / file_size are NULLABLE because they are nullable on the sessions
+-- table too (a source with no statable file indexes them as NULL). NOT NULL here made
+-- a legitimate null-stat session throw a constraint error that took the whole batch
+-- transaction down with it.
+CREATE TABLE IF NOT EXISTS session_insights (
+  session_id TEXT PRIMARY KEY,
+  file_mtime_ms INTEGER,
+  file_size INTEGER,
+  extractor_version INTEGER NOT NULL,
+  computed_at INTEGER NOT NULL,
+  facets TEXT NOT NULL
+);
 `;
+/**
+ * Bumping this invalidates every cached facet row without touching the schema
+ * version, so a change to the extraction logic (a new metric, a corrected bucket)
+ * re-derives on the next `agents insights` instead of silently reporting stale
+ * numbers alongside fresh ones. Same role as RESOURCE_INDEX_VERSION.
+ */
+export const INSIGHTS_EXTRACTOR_VERSION = 3;
 let dbInstance = null;
 /**
  * Apply schema migrations from `fromVersion` → SCHEMA_VERSION. The new
@@ -2105,6 +2131,80 @@ export function countSessions(options = {}) {
     const row = db.prepare(sql).get(...params);
     return row ? row.n : 0;
 }
+/** What to group a usage rollup by. */
+/**
+ * Read cached facets for the given sessions, dropping any row that is stale.
+ *
+ * Staleness is decided in SQL against the session's own `file_mtime_ms` / `file_size`,
+ * the same pair the scanner maintains — so the cache cannot disagree with the index,
+ * `IS` rather than `=` so a source with no statable file — NULL on both sides — is a
+ * cache HIT rather than a permanent miss that re-parses it on every run.
+ */
+export function readSessionInsights(ids) {
+    const db = getDB();
+    const out = new Map();
+    if (ids.length === 0)
+        return out;
+    const CHUNK = 400; // chunk.length + 1 binds, well under SQLite's 999-variable limit
+    for (let i = 0; i < ids.length; i += CHUNK) {
+        const chunk = ids.slice(i, i + CHUNK);
+        const phs = chunk.map(() => '?').join(',');
+        const rows = db.prepare(`
+      SELECT si.session_id AS id, si.facets AS facets
+      FROM session_insights si
+      JOIN sessions s ON s.id = si.session_id
+      WHERE si.session_id IN (${phs})
+        AND si.extractor_version = ?
+        AND si.file_mtime_ms IS s.file_mtime_ms
+        AND si.file_size IS s.file_size
+    `).all(...chunk, INSIGHTS_EXTRACTOR_VERSION);
+        for (const row of rows) {
+            try {
+                out.set(row.id, JSON.parse(row.facets));
+            }
+            catch {
+                // A corrupt cache row is not a reason to fail the report; recompute it.
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Persist freshly computed facets against the stamp of the bytes actually parsed.
+ *
+ * The caller passes the stat it observed when it read the file. Re-reading the stamp
+ * from the sessions table inside this INSERT would race: a concurrent rescan between
+ * the parse and the write (the cold path flushes in batches, so the window is minutes
+ * wide, and this module treats concurrent access as a design assumption) stamps NEW
+ * bytes onto OLD facets — a permanent false cache hit until the file changes again.
+ * tool-index.ts sets the precedent: stat at parse time, carry the stamp into the write.
+ */
+export function writeSessionInsights(entries) {
+    if (entries.length === 0)
+        return;
+    const db = getDB();
+    const stmt = db.prepare(`
+    INSERT INTO session_insights
+      (session_id, file_mtime_ms, file_size, extractor_version, computed_at, facets)
+    VALUES (?, ?, ?, ?, ?, ?)
+    ON CONFLICT(session_id) DO UPDATE SET
+      file_mtime_ms = excluded.file_mtime_ms,
+      file_size = excluded.file_size,
+      extractor_version = excluded.extractor_version,
+      computed_at = excluded.computed_at,
+      facets = excluded.facets
+  `);
+    const now = Date.now();
+    db.transaction(() => {
+        for (const e of entries) {
+            stmt.run(e.id, e.fileMtimeMs, e.fileSize, INSIGHTS_EXTRACTOR_VERSION, now, JSON.stringify(e.facets));
+        }
+    })();
+}
+/** Drop every cached facet row. Backs `agents insights --refresh`. */
+export function clearSessionInsights() {
+    getDB().exec(`DELETE FROM session_insights`);
+}
 export function queryAffinityRollup(options) {
     const db = getDB();
     const where = [];

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

@@ -13,6 +13,9 @@ export interface FileChange {
     path: string;
     op: FileOp;
 }
+export declare const READ_TOOLS: Set<string>;
+export declare const WRITE_TOOLS: Set<string>;
+export declare const EDIT_TOOLS: Set<string>;
 /**
  * Path-shaped noise that must never surface as a session "change": shell
  * redirect tokens (`2>&1`), unexpanded env-var prefixes (`$WT/...`), dependency

package/dist/lib/session/digest.js

@@ -10,9 +10,9 @@
 import { bucketKey, classifyBashCommand } from './bash-command.js';
 // Tool vocab mirrors parse.ts / render.ts so classification matches what those
 // modules already recognize across Claude/Codex/others.
-const READ_TOOLS = new Set(['Read', 'read_file', 'view_file', 'cat_file', 'get_file']);
-const WRITE_TOOLS = new Set(['Write', 'write_file', 'create_file']);
-const EDIT_TOOLS = new Set(['Edit', 'edit_file', 'replace', 'patch', 'MultiEdit', 'apply_patch']);
+export const READ_TOOLS = new Set(['Read', 'read_file', 'view_file', 'cat_file', 'get_file']);
+export const WRITE_TOOLS = new Set(['Write', 'write_file', 'create_file', 'Create']);
+export const EDIT_TOOLS = new Set(['Edit', 'edit_file', 'replace', 'patch', 'MultiEdit', 'apply_patch']);
 /**
  * Path-shaped noise that must never surface as a session "change": shell
  * redirect tokens (`2>&1`), unexpanded env-var prefixes (`$WT/...`), dependency

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

@@ -0,0 +1,126 @@
+/**
+ * Behavioural facets of a coding session, and the cross-session rollup built from them.
+ *
+ * This is the engine behind `agents insights`. It answers "how do you work" rather than
+ * "what did you spend" (`agents cost`) or "what shipped" (`agents output`), and it is
+ * the only surface that splits any of it by the account that produced the work.
+ *
+ * Everything here is a pure function of a parsed `SessionEvent[]`, so it is testable
+ * without a database and cheap to re-run. The expensive part is parsing the transcript,
+ * which is why results are cached per session in `session_insights` and recomputed only
+ * when the file's (mtime, size) changes — the same staleness contract as `scan_ledger`.
+ *
+ * Prior art: Claude Code's own `/insights`, which computes a comparable set from
+ * `~/.claude/projects` alone. Two deliberate differences:
+ *
+ *   - It sees ONE account's directory. This reads every indexed session, across every
+ *     Claude account and every other harness, and reports them apart.
+ *   - It collapses conversation branches before counting. agents-cli is file-per-session
+ *     throughout (`discover.ts` keys on the transcript's basename), so session counts
+ *     here will read slightly higher than `/insights` on the same machine. Reported as
+ *     the raw file count rather than quietly differing.
+ */
+import type { SessionEvent } from './types.js';
+/** Behavioural facets of one session. Serialized as JSON into `session_insights`. */
+export interface InsightFacets {
+    toolCounts: Record<string, number>;
+    /** Per-model assistant turn counts. `/insights` has no model dimension at all. */
+    models: Record<string, number>;
+    languages: Record<string, number>;
+    /** Slash commands the user invoked, by name. */
+    slashCommands: Record<string, number>;
+    errorCategories: Record<string, number>;
+    /** Times the user cut a turn short — the `interrupt` event from parse.ts. */
+    interruptions: number;
+    /** Seconds between an assistant's last event and the user's next message. */
+    responseGaps: number[];
+    /** Gaps excluded for exceeding the ceiling — reported, never silently dropped. */
+    gapsOverCeiling: number;
+    /**
+     * Lines in the BEFORE and AFTER text of every edit and write — "lines touched", not
+     * a diff. An Edit whose old_string is three unchanged context lines counts them in
+     * both; git counts them zero times. Measured against a real commit the added figure
+     * ran 19% high and the removed figure 475% high, so this must never be rendered as
+     * a diffstat. Computing a true delta needs a line-level diff per edit, which is a
+     * different feature.
+     */
+    linesTouchedBefore: number;
+    linesTouchedAfter: number;
+    /**
+     * Edit/write calls in a vocabulary we recognise. NOT a proxy for measurability:
+     * codex renames `apply_patch` to `Edit` but carries no line-bearing arguments, so it
+     * reports edit calls with zero lines. Callers decide "measurable" from the line
+     * totals themselves.
+     */
+    editingToolCalls: number;
+    filesCreated: number;
+    filesModified: number;
+    filesDeleted: number;
+    gitCommits: number;
+    gitPushes: number;
+    /**
+     * Tool calls that carried an actual command string to search. Not every harness
+     * populates one: the codex parser sets `command` for `exec_command` but not for
+     * plain `exec`, its dominant tool, so git activity is structurally invisible there.
+     * 0 means the commit counts are unmeasurable, not observed-zero.
+     */
+    shellCommandsSeen: number;
+    /** 24 slots, local time, indexed by hour of the user's messages. */
+    messageHours: number[];
+    userTurns: number;
+    assistantTurns: number;
+    toolCount: number;
+    errorCount: number;
+}
+/**
+ * Compute every behavioural facet of one session from its parsed events.
+ *
+ * Pure: no I/O, no clock, no filesystem. `timezoneOffsetMinutes` is injected rather
+ * than read from the environment so the hour histogram is deterministic in tests and
+ * can be re-bucketed for a different display timezone without re-parsing.
+ */
+export declare function computeInsightFacets(events: SessionEvent[], timezoneOffsetMinutes?: number): InsightFacets;
+/** Percentile of a numeric sample, nearest-rank. Returns 0 for an empty sample. */
+export declare function percentile(values: number[], p: number): number;
+/** Bucket response gaps for display. Returns every bucket, including empty ones. */
+export declare function bucketGaps(gaps: number[]): Array<{
+    bucket: string;
+    count: number;
+}>;
+/** A session's time span, for overlap detection. */
+export interface SessionSpan {
+    id: string;
+    accountKey: string;
+    startMs: number;
+    endMs: number;
+}
+/** How much work ran concurrently, and how much of it straddled two accounts. */
+export interface OverlapReport {
+    /** Pairs of sessions whose spans intersect. */
+    overlappingPairs: number;
+    /** Of those, pairs belonging to DIFFERENT accounts. */
+    crossAccountPairs: number;
+    /** Distinct sessions involved in any overlap. */
+    sessionsInvolved: number;
+}
+/**
+ * Detect concurrent sessions by interval intersection.
+ *
+ * This is the metric that makes the account split legible rather than academic: a
+ * cross-account overlap is `balanced` rotation actively running two orgs' quota at the
+ * same moment. `/insights` has a comparable "multi-clauding" count, but with one
+ * account it can only ever report the same-account case.
+ *
+ * Sweep in start order, keeping only spans that could still intersect, so this is
+ * O(n log n + pairs) rather than O(n^2) over ~3k sessions.
+ */
+export declare function detectOverlap(spans: SessionSpan[]): OverlapReport;
+/** Merge a session's facets into a running total. */
+export declare function mergeFacets(into: InsightFacets, add: InsightFacets): void;
+/** A fresh zeroed accumulator, for callers folding many sessions together. */
+export declare function newFacetAccumulator(): InsightFacets;
+/** Top-N entries of a count map, highest first, ties broken by name for determinism. */
+export declare function topEntries(counts: Record<string, number>, limit: number): Array<{
+    name: string;
+    count: number;
+}>;