@phnx-labs/agents-cli 1.22.58 → 1.22.59

package/dist/lib/session/db.js

@@ -27,7 +27,7 @@ const DB_PATH = getSessionsDbPath();
 /** Current schema version; bumped when migrations are added. Exported so tests
  * assert against the constant instead of hardcoding a number that every bump
  * then has to chase (docs/sessions.md calls the constant the source of truth). */
-export const SCHEMA_VERSION = 43;
+export const SCHEMA_VERSION = 44;
 /**
  * Bump to force the content extractor (assistant-answer text, alongside the
  * user-prompt text every harness already accumulates) to re-derive on every
@@ -1205,6 +1205,32 @@ function migrateSchema(db, fromVersion) {
         if (!cols.has('end_timestamp'))
             db.exec(`ALTER TABLE tool_calls ADD COLUMN end_timestamp TEXT`);
     }
+    if (fromVersion < 44) {
+        // v43 -> v44: backfill duration_ms for sessions whose harness scan extractor
+        // never derived it (PHNX-3457). rush/grok/kimi/cursor/muse/antigravity/hermes/
+        // openclaw left duration_ms NULL — 52% of the corpus, 100% of rush — so the
+        // console median was computed over only the ~48% that carried it, skewing it
+        // short. Going forward resolveDurationMs() populates it at every upsert; this
+        // repairs already-indexed rows in place from the timestamps they already store
+        // (last_activity, itself resolved from the last-message time else file mtime,
+        // minus the creation timestamp), so no transcript is re-parsed. julianday is
+        // avoided because it does not accept a trailing 'Z'; the arithmetic is done in
+        // JS with the exact Date.parse resolveDurationMs uses, keeping the backfill and
+        // the live path consistent. Only rows with a positive span are touched; a NULL
+        // that cannot be resolved stays NULL rather than becoming a fabricated 0.
+        const nullDurationRows = db.prepare(`SELECT id, timestamp, last_activity FROM sessions
+       WHERE duration_ms IS NULL AND last_activity IS NOT NULL`).all();
+        // Runs inside migrateSchema's own transaction (db.ts:1468), so no nested
+        // db.transaction() here — that would raise "transaction within a transaction".
+        const update = db.prepare(`UPDATE sessions SET duration_ms = ? WHERE id = ?`);
+        for (const row of nullDurationRows) {
+            const startMs = Date.parse(row.timestamp);
+            const lastMs = Date.parse(row.last_activity);
+            if (Number.isFinite(startMs) && Number.isFinite(lastMs) && lastMs > startMs) {
+                update.run(lastMs - startMs, row.id);
+            }
+        }
+    }
 }
 /**
  * Stamp `account_key` / `account_org` / `account` on every Claude row from its
@@ -2075,7 +2101,7 @@ export function upsertSession(meta, content, scan, assistantContent = '') {
         cache_write_tokens: meta.cacheWriteTokens ?? null,
         cost_usd: meta.costUsd ?? null,
         cost_usd_nocache: meta.costUsdNoCache ?? null,
-        duration_ms: meta.durationMs ?? null,
+        duration_ms: resolveDurationMs(meta, scan),
         model: meta.model ?? null,
         tool_call_count: meta.toolCallCount ?? null,
         file_path: meta.filePath,
@@ -2163,6 +2189,23 @@ export function upsertSessionsBatch(entries) {
                 ? { ...entry, meta: { ...entry.meta, ...fanOutCounts(entry.events, entry.meta.agent) } }
                 : entry;
         }
+        // Harnesses whose scanners produce no events AND whose parseSession reads a
+        // potentially large flat transcript file (not a compact SQLite DB). Calling
+        // parseSession on the warm tick for an active large session wedges the Node
+        // event loop for seconds, making browser IPC miss its connection window
+        // (PHNX-3411). Defer their tool-call indexing to runDeferredToolIndex, which
+        // uses ensureToolIndex with tool_scan_ledger stamps and byte/file budget caps.
+        // NOT opencode — parseOpenCode issues a targeted SQLite query, so it is fast
+        // even for large sessions and its results populate recentDirectoriesTouched.
+        const LARGE_TRANSCRIPT_AGENTS = new Set(['kimi', 'grok']);
+        if (!entry.events && LARGE_TRANSCRIPT_AGENTS.has(entry.meta.agent)) {
+            return entry;
+        }
+        // Enrich the entry. When the scanner already provided events, use them
+        // directly (no transcript re-read). When it didn't — e.g. OpenCode whose
+        // scanner produces only metadata but whose parseOpenCode is a fast SQLite
+        // query — fall back to parseSession. Agents that would call an expensive
+        // flat-file parse already returned above.
         try {
             const toolSourcePath = toolEvidenceSourcePath(entry.meta.filePath, entry.meta.agent);
             const toolScan = toolSourcePath === entry.meta.filePath
@@ -2171,9 +2214,6 @@ export function upsertSessionsBatch(entries) {
                     const stat = fs.statSync(toolSourcePath);
                     return { fileMtimeMs: stat.mtimeMs, fileSize: stat.size };
                 })();
-            // Some non-resumable scanners already normalized the transcript while
-            // deriving metadata. Reuse those events; scanners that only read summary
-            // metadata fall back to exactly one normalized parse here.
             const events = entry.events ?? parseSession(entry.meta.filePath, entry.meta.agent);
             writeResourceUsage(entry.meta.id, events, entry.meta.cwd);
             // Resume the tool index from the last scan of this append-only stream when
@@ -2302,7 +2342,7 @@ export function upsertSessionsBatch(entries) {
                     cache_write_tokens: meta.cacheWriteTokens ?? null,
                     cost_usd: meta.costUsd ?? null,
                     cost_usd_nocache: meta.costUsdNoCache ?? null,
-                    duration_ms: meta.durationMs ?? null,
+                    duration_ms: resolveDurationMs(meta, scan),
                     model: meta.model ?? null,
                     tool_call_count: meta.toolCallCount ?? null,
                     file_path: meta.filePath,
@@ -2599,6 +2639,36 @@ function resolveLastActivity(meta, scan) {
         return new Date(scan.fileMtimeMs).toISOString();
     return meta.timestamp;
 }
+/**
+ * The persisted wall-clock span for a session (PHNX-3457).
+ *
+ * `durationMs` is canonically `lastTs − firstTs`. Some harness scan extractors
+ * derive it themselves from per-event timestamps (claude/codex/droid/gemini/
+ * opencode set `meta.durationMs`); the rest (rush/grok/kimi/cursor/muse/
+ * antigravity/hermes/openclaw) never did, so `duration_ms` landed NULL for them —
+ * 52% of the corpus, including 100% of the dominant `rush` usage — and the
+ * console median was computed over only the ~48% that happened to carry it,
+ * skewing it short and misleading.
+ *
+ * This closes the gap at the single write boundary every harness funnels
+ * through, so parity is automatic rather than per-extractor: when the extractor
+ * already computed a precise span, keep it; otherwise derive it from the same
+ * `timestamp` (creation) and `resolveLastActivity` (last event, itself resolved
+ * from the harness's last-message time, else file mtime) that the row already
+ * stores. Returns null only when no positive span can be established (a single
+ * timestamped event, or a clock that runs backwards), which reads as NULL rather
+ * than a fabricated 0.
+ */
+function resolveDurationMs(meta, scan) {
+    if (meta.durationMs != null)
+        return meta.durationMs;
+    const startMs = Date.parse(meta.timestamp);
+    const lastMs = Date.parse(resolveLastActivity(meta, scan));
+    if (Number.isFinite(startMs) && Number.isFinite(lastMs) && lastMs > startMs) {
+        return lastMs - startMs;
+    }
+    return null;
+}
 export function isSessionActivityFresh(row, maxAgeMs, nowMs) {
     const parsedActivityMs = Date.parse(row.last_activity ?? row.timestamp);
     const activityMs = Number.isFinite(parsedActivityMs) ? parsedActivityMs : row.file_mtime_ms ?? undefined;
@@ -2892,6 +2962,26 @@ export function querySessions(options = {}) {
     const trimmed = options.limit ? live.slice(0, options.limit) : live;
     return trimmed.map(rowToMeta);
 }
+/**
+ * Cheap query for the daemon's deferred tool-index pass (PHNX-3411).
+ *
+ * Returns the most-recently-active sessions whose parseSession reads a large
+ * flat transcript (kimi: wire.jsonl, grok: chat_history.jsonl). Their scanners
+ * produce no events, so upsertSessionsBatch skips them in the warm tick to
+ * avoid wedging the event loop. ensureToolIndex uses tool_scan_ledger stamps
+ * to skip already-current rows and applies byte/file budget caps.
+ */
+export function querySessionsForDeferredToolIndex(limit) {
+    const db = getDB();
+    const rows = db.prepare(`
+    SELECT * FROM sessions
+    WHERE file_path IS NOT NULL
+      AND agent IN ('kimi', 'grok')
+    ORDER BY last_activity DESC, timestamp DESC
+    LIMIT ?
+  `).all(limit);
+    return rows.map(rowToMeta);
+}
 /** Count sessions matching the given filter options. */
 export function countSessions(options = {}) {
     const db = getDB();
@@ -3333,17 +3423,43 @@ export function queryResourceUsageStats(options) {
     return db.prepare(sql).all(...allParams);
 }
 /**
- * Coverage of the resource-usage signal: how many distinct sessions carry any
- * row in session_resource_usage vs. the total indexed. A low ratio means the
- * historical backfill (`agents sessions backfill resources`) hasn't run — the
- * stats surface uses this to tell the user their zero-counts may just be
- * un-scanned history, not genuine non-use.
+ * Coverage of the resource-usage signal, as three honest facts:
+ *
+ * - `scanned`  — sessions the resource extractor has actually processed, i.e.
+ *   those carrying a `resource_scan_ledger` row at the current
+ *   `RESOURCE_INDEX_VERSION`. This is the true "has the historical backfill run"
+ *   signal: the ledger is stamped for EVERY scanned session, including ones that
+ *   invoked nothing (`resource_count = 0`), so `scanned/total` rises to ~1 after
+ *   `agents sessions backfill resources` regardless of how sparse explicit
+ *   invocations are.
+ * - `covered`  — distinct sessions that carry AT LEAST ONE row in
+ *   `session_resource_usage`, i.e. that actually recorded an explicit invocation.
+ *   This is an ABSOLUTE signal count, not a coverage ratio: it stays small even
+ *   at full scan coverage because most sessions invoke no skill/command, and a
+ *   non-recording harness contributes none by construction.
+ * - `total`    — sessions indexed.
+ *
+ * The two were previously conflated: `covered/total` was framed as coverage and
+ * read ~1.2% even after a full backfill (most sessions genuinely invoke nothing),
+ * so the "run the backfill" hint never cleared. Keying the hint on `scanned/total`
+ * fixes that — see `commands/sessions-stats.ts` (PHNX-2301).
  */
 export function resourceUsageCoverage() {
     const db = getDB();
     const covered = db.prepare(`SELECT COUNT(DISTINCT session_id) AS n FROM session_resource_usage`).get().n;
+    // JOIN sessions so a ledger row for a since-vanished transcript (dropped from
+    // `sessions` but not yet from the ledger) can't inflate scan coverage past the
+    // indexed set. Only rows at the current extractor version count as scanned —
+    // a stale-version row is re-derived on the next backfill, so it is not yet
+    // "covered" for this extractor.
+    const scanned = db.prepare(`
+    SELECT COUNT(*) AS n
+    FROM resource_scan_ledger l
+    JOIN sessions s ON s.id = l.session_id
+    WHERE l.extractor_version = ?
+  `).get(RESOURCE_INDEX_VERSION).n;
     const total = db.prepare(`SELECT COUNT(*) AS n FROM sessions`).get().n;
-    return { covered, total };
+    return { covered, scanned, total };
 }
 /** Has this session's resource usage been derived at the current extractor version for this exact file? */
 function needsResourceIndex(db, sessionId, stamp) {

package/dist/lib/smart-launch.d.ts

@@ -95,6 +95,12 @@ export declare function resolveDeviceAuto(agent?: string, opts?: {
     /** Route only to devices with a row the interactive account picker can launch. */
     accountPicker?: boolean;
     probe?: (pool: string[], agent?: AgentType) => Promise<Map<string, DevicePlacementSignal>>;
+    /**
+     * Preferred hosts (`auto-launch.preferred`) that get the ranking boost.
+     * Defaults to the stored fleet block resolved over the candidate pool;
+     * injectable so a test pins it without touching disk.
+     */
+    preferred?: ReadonlySet<string>;
 }): Promise<DeviceAutoPlan>;
 /**
  * Resolve host for `--device auto`. Does NOT pick harness or accounts.

package/dist/lib/smart-launch.js

@@ -8,7 +8,7 @@
 import { queryAffinityRollup } from './session/db.js';
 import { localMachineId } from './session/origin-machine.js';
 import { loadDevicesSync } from './devices/registry.js';
-import { describeAutoPool, filterAutoPool, isAutoPoolMember } from './devices/pool.js';
+import { autoLaunchPreferredSet, describeAutoPool, filterAutoPool, isAutoPoolMember } from './devices/pool.js';
 import { normalizeHost } from './machine-id.js';
 import { probePoolSignals } from './teams/placement-probe.js';
 import { pickBestDevice } from './teams/scheduler.js';
@@ -153,7 +153,10 @@ export async function resolveDeviceAuto(agent, opts = {}) {
     if (eligiblePool.length === 0) {
         throw new Error(formatNoHealthyDeviceError(pool, signals, agent));
     }
-    const picked = pickBestDevice(eligiblePool, [], { signals, agentLabel: agent });
+    // `agents devices prefer <name>` boosts a device in the ranking — resolved
+    // over the same pool so a fleet default reaches a doc-less box.
+    const preferred = opts.preferred ?? autoLaunchPreferredSet(pool, { roster: pool });
+    const picked = pickBestDevice(eligiblePool, [], { signals, agentLabel: agent, preferred });
     return {
         host: picked === local ? null : picked,
         pickedDeviceKey: picked,

package/dist/lib/staleness/writers/plugins.js

@@ -8,8 +8,11 @@ function buildPluginsWriter(agent) {
         write({ version, versionHome, selection }) {
             const all = discoverPlugins();
             const map = new Map(all.map(p => [p.name, p]));
-            // Clean orphan plugin-skills from plugins that no longer exist.
-            cleanOrphanedPluginSkills(agent, versionHome, new Set(all.map(p => p.name)));
+            // Clean orphan plugin-skills from plugins that no longer exist. Pass the
+            // discovered plugins (not just names) so a stale install under one
+            // marketplace is trashed even when another marketplace still ships that
+            // name — the PHNX-2618 shadow `code` plugin.
+            cleanOrphanedPluginSkills(agent, versionHome, all);
             const synced = [];
             for (const name of selection) {
                 const plugin = map.get(name);

package/dist/lib/staleness/writers/subagents.js

@@ -25,10 +25,16 @@ function buildSubagentsWriter(agent) {
             const dir = target.dir(versionHome);
             const synced = [];
             const paths = [];
+            const errors = [];
             for (const name of selection) {
                 const sub = map.get(name);
-                if (!sub)
+                if (!sub) {
+                    // Requested but not discoverable as an installed central subagent —
+                    // e.g. its AGENT.md failed to parse. Say so instead of silently
+                    // dropping it, which read as an unactionable doctor "hold" (PHNX-3187).
+                    errors.push(`subagent '${name}': no parseable AGENT.md in ~/.agents/subagents`);
                     continue;
+                }
                 try {
                     target.write(dir, sub);
                     synced.push(sub.name);
@@ -39,9 +45,13 @@ function buildSubagentsWriter(agent) {
                             paths.push(entry.path);
                     }
                 }
-                catch { /* per-item sync failure: skip */ }
+                catch (e) {
+                    // A genuine fs/transform failure must surface with its reason, not
+                    // vanish behind a bare `catch` (RUSH-2677 / PHNX-3187).
+                    errors.push(`subagent '${sub.name}': ${e.message}`);
+                }
             }
-            return { synced, paths };
+            return errors.length > 0 ? { synced, paths, errors } : { synced, paths };
         },
     };
 }

package/dist/lib/state.d.ts

@@ -198,10 +198,13 @@ export declare function getMonitorsDir(): string;
  * Path to built-in monitor definitions shipped in the system repo
  * (`~/.agents/.system/monitors/`). Unioned under the user monitors dir by
  * listMonitors()/readMonitor(): a monitor shipped here is available on every
- * install, and a user monitor of the same name overrides it. A built-in with no
- * `enabled:` field is opt-in — it stays disabled until the user enables it,
- * which materializes a user copy (writes never touch this pull-only mirror). The
- * directory need not exist.
+ * install, and a user monitor of the same name overrides it. A built-in is
+ * enabled by default like every other system-layer resource — it runs on every
+ * install unless the user shadows it with `enabled: false` (via `agents monitors
+ * pause`, which materializes a user copy; writes never touch this pull-only
+ * mirror). A shared-input built-in still carries its own `device:` owner pin in
+ * the shipped YAML so exactly one box fires it (SING-9). The directory need not
+ * exist.
  */
 export declare function getSystemMonitorsDir(): string;
 /** Path to the durable per-monitor state-diff store + fire history

package/dist/lib/state.js

@@ -491,10 +491,13 @@ export function getMonitorsDir() { return process.env.AGENTS_MONITORS_DIR ?? MON
  * Path to built-in monitor definitions shipped in the system repo
  * (`~/.agents/.system/monitors/`). Unioned under the user monitors dir by
  * listMonitors()/readMonitor(): a monitor shipped here is available on every
- * install, and a user monitor of the same name overrides it. A built-in with no
- * `enabled:` field is opt-in — it stays disabled until the user enables it,
- * which materializes a user copy (writes never touch this pull-only mirror). The
- * directory need not exist.
+ * install, and a user monitor of the same name overrides it. A built-in is
+ * enabled by default like every other system-layer resource — it runs on every
+ * install unless the user shadows it with `enabled: false` (via `agents monitors
+ * pause`, which materializes a user copy; writes never touch this pull-only
+ * mirror). A shared-input built-in still carries its own `device:` owner pin in
+ * the shipped YAML so exactly one box fires it (SING-9). The directory need not
+ * exist.
  */
 export function getSystemMonitorsDir() { return process.env.AGENTS_SYSTEM_MONITORS_DIR ?? SYSTEM_MONITORS_DIR; }
 /** Path to the durable per-monitor state-diff store + fire history

package/dist/lib/subagents.js

@@ -23,7 +23,12 @@ export function parseSubagentFrontmatter(filePath) {
     }
     try {
         const content = fs.readFileSync(filePath, 'utf-8');
-        const lines = content.split('\n');
+        // Split on CRLF or LF: git checks text files out with CRLF on Windows
+        // (core.autocrlf), so a plain split('\n') leaves a trailing '\r' on every
+        // line and the frontmatter fence `'---\r' !== '---'` never matches —
+        // silently dropping the subagent from discovery so it can never be
+        // installed or reconciled (PHNX-3187).
+        const lines = content.split(/\r?\n/);
         // Check for YAML frontmatter
         if (lines[0] === '---') {
             const endIndex = lines.slice(1).findIndex((l) => l === '---');
@@ -52,7 +57,8 @@ export function getSubagentBody(filePath) {
         return '';
     }
     const content = fs.readFileSync(filePath, 'utf-8');
-    const lines = content.split('\n');
+    // CRLF-robust for the same reason as parseSubagentFrontmatter (PHNX-3187).
+    const lines = content.split(/\r?\n/);
     // Skip YAML frontmatter
     if (lines[0] === '---') {
         const endIndex = lines.slice(1).findIndex((l) => l === '---');

package/dist/lib/teams/scheduler.d.ts

@@ -48,6 +48,16 @@ export interface PlacementOptions {
     /** Human label of the requested agent (e.g. `claude@2.1.112`) for the
      * fail-loud message. */
     agentLabel?: string;
+    /**
+     * Normalized hosts boosted with `auto-launch.preferred` (set by
+     * `agents devices prefer <name>`). A preferred device ranks ahead of a
+     * non-preferred one among the eligible survivors — after the signed-in tier
+     * (a preferred box that can't run the agent is still no use) and before load,
+     * so an operator boost overrides load-based ordering without overriding hard
+     * health. Empty/undefined leaves the ranking unchanged. See
+     * {@link autoLaunchPreferredSet}.
+     */
+    preferred?: ReadonlySet<string>;
 }
 /** Why a device was excluded from the viable set, for the fail-loud message. */
 export type ExclusionReason = 'unreachable' | 'overloaded' | 'capped' | 'not-installed';

package/dist/lib/teams/scheduler.js

@@ -266,6 +266,14 @@ export function pickBestDevice(devices, roster, opts) {
         const signedIn = (sa?.signedIn === true ? 0 : 1) - (sb?.signedIn === true ? 0 : 1);
         if (signedIn !== 0)
             return signedIn;
+        // (a2) operator-preferred device next — `agents devices prefer <name>`
+        // boosts a box above its load-equal peers, overriding load-based order.
+        const preferred = opts?.preferred;
+        if (preferred && preferred.size > 0) {
+            const pref = (preferred.has(a) ? 0 : 1) - (preferred.has(b) ? 0 : 1);
+            if (pref !== 0)
+                return pref;
+        }
         // (b) lower load — coarse headroom tier, then raw load cost.
         const tier = headroomTier(sa?.headroom) - headroomTier(sb?.headroom);
         if (tier !== 0)

package/dist/lib/traces/sync.d.ts

@@ -67,18 +67,46 @@ export interface TracesIndexShard {
     owner: string;
     stats: {
         sessionsImported: number;
+        /**
+         * Median ACTIVE duration (span − idle gaps > 120s), ms — the meaningful figure
+         * (PHNX-3457). Same key/shape as before this change, so the fleet-aggregate
+         * worker (`worker-template.ts`) keeps weighted-averaging it unchanged; only its
+         * VALUE moved from raw span to active time. The raw span stays available per
+         * session on `SessionDetail.meta.spanMs`.
+         */
         medianMs: number;
+        /** p90 ACTIVE duration, ms. */
         p90Ms: number;
+        /**
+         * SEGMENTED active-time stats (PHNX-3472). The blended `medianMs`/`p90Ms`
+         * above conflate one-shot interactive queries (63% of the corpus, ~15s
+         * median) with substantial agent runs (~15min median), so they headline
+         * neither. A session is an AGENT run when it made any tool call OR has more
+         * than 8 messages; otherwise INTERACTIVE. These segment the same active-time
+         * figure so the console can headline agent runs on their own axis. Each is
+         * computed only over sessions with a non-null duration.
+         */
+        agentMedianMs: number;
+        /** p90 ACTIVE duration over AGENT sessions, ms. */
+        agentP90Ms: number;
+        /** Median ACTIVE duration over INTERACTIVE sessions, ms. */
+        interactiveMedianMs: number;
+        /** (sessions with a non-null duration) / (total sessions), 0..1 — coverage of the duration stats. */
+        measuredFraction: number;
         needAttention: number;
         toolErrorRate: number;
     };
+    /**
+     * Sessions excluded from the eval corpus as internal utility plumbing (PHNX-3474):
+     * single-shot machine calls (no tool call AND ≤2 messages) or a known
+     * internal-prompt signature (title generation, watchdog, commit-message, factory
+     * worker). Every `stats` figure above, `topics` counts, and `needsAttention` are
+     * computed over the AGENT set ONLY — `sessionsImported` is the real agent count,
+     * not the raw row count. This is the number that was dropped.
+     */
+    utilityCount: number;
     needsAttention: IndexedSession[];
-    topics: Array<{
-        key: string;
-        label: string;
-        count: number;
-        group: TraceTopicGroup;
-    }>;
+    topics: TopicItem[];
     failures: {
         byToolError: Array<{
             tool: string;
@@ -104,11 +132,56 @@ export interface IndexedSession {
     title: string;
     repo: string;
     device: string;
+    /** The harness that produced the session (claude/codex/rush/grok/…). Same as `harness`. */
     agent: string;
     model: string;
+    /** Corpus classification (PHNX-3474). Always `'agent'` here — utility rows are excluded. */
+    kind: SessionKind;
     severity: number;
     flags: string[];
 }
+/**
+ * One example session under a topic tile — the shape the console drill-down consumes.
+ * Carries `kind` + `harness` (PHNX-3474) so the console can filter a tile's session
+ * list by corpus class and by harness. Refs on a topic tile are always `'agent'`
+ * (utility rows never reach a bucket), but the field is explicit for the consumer.
+ */
+export interface TopicSessionRef {
+    id: string;
+    title: string;
+    kind: SessionKind;
+    harness: string;
+}
+/**
+ * Corpus class of a session (PHNX-3474). `utility` is internal machine plumbing —
+ * a single-shot call with no tool use and ≤2 messages, or one whose topic/label
+ * matches a known internal-prompt signature (title generation, watchdog,
+ * commit-message writer, factory worker). Everything else is `agent`: real agent
+ * work the Evals console counts and scores. Utility rows are tagged, never deleted,
+ * and excluded from every index statistic.
+ */
+export type SessionKind = 'utility' | 'agent';
+/**
+ * Classify a session as internal `utility` plumbing vs real `agent` work (PHNX-3474).
+ * `toolCallCount` is the AUTHORITATIVE per-session tool-call count from the loaded
+ * `tool_calls` rows (the row's own `tool_call_count` column is a fallback for a row
+ * whose calls weren't loaded). A session is `utility` when a known internal-prompt
+ * signature matches its topic/label, OR it made no tool call AND has ≤2 messages —
+ * the single-shot machine-call shape. Otherwise it is `agent`.
+ */
+export declare function classifySessionKind(row: Pick<SyncRow, 'topic' | 'label' | 'message_count' | 'tool_call_count'>, toolCallCount: number): SessionKind;
+/**
+ * One topic bucket in the treemap. `sessions` carries up to {@link TOPIC_SESSION_CAP}
+ * example refs so the console can drill from the tile into its session list — a tile
+ * with no refs renders display-only (PHNX-3408). `count` stays the true total.
+ */
+export interface TopicItem {
+    key: string;
+    label: string;
+    count: number;
+    group: TraceTopicGroup;
+    sessions: TopicSessionRef[];
+}
 /** A row from `tool_calls`. `ordinal`/`timestamp` order calls within a session for computeInsights(). */
 export interface ToolCallRow {
     session_id: string;
@@ -129,6 +202,31 @@ export interface ToolCallRow {
     error: string | null;
     parse_error: string | null;
 }
+/**
+ * Active time for a session in the index shard: its recorded span minus every idle
+ * gap > 120s (PHNX-3457). The index build already holds the ordered `tool_calls`
+ * rows for the whole corpus, so idle is derived from them here — no transcript
+ * re-parse. A cursor sweeps the span from `sessionStartMs`: each stretch where the
+ * cursor sits idle for more than the threshold before the next call starts is
+ * subtracted, and idle is measured from a call's END (its own `end_timestamp` when
+ * known, else its start) so a call's own blocking duration is never mistaken for
+ * idle. Crucially the sweep also books the gaps at the two BOUNDARIES — before the
+ * first call and after the last call to the session end — so a session with a lone
+ * tool call that was then abandoned and resumed hours later (the case a
+ * between-calls-only measure missed entirely, leaving the whole 345h span counted
+ * as active) has that trailing idle stripped. A session end is `sessionStartMs +
+ * spanMs`, so the two agree by construction.
+ *
+ * Bounded to `[0, spanMs]`. A session with NO tool calls returns the full span
+ * unchanged rather than a fabricated zero: there is no tool-call evidence of idle
+ * either way, and treating a chat-only turn as 100% idle would be a worse error
+ * than leaving its span uncorrected. Where the full event stream IS available (a
+ * per-session `SessionDetail`), {@link activeMsFromTrajectory} is used instead —
+ * it sees message events this call-only approximation cannot, so the two are close
+ * but not identical by design (the corpus-scale index build cannot afford the
+ * per-session parse the detail view does).
+ */
+export declare function sessionActiveMs(spanMs: number, sessionCalls: ToolCallRow[], sessionStartMs: number): number;
 /** Human description of a failed call, keyed by (tool, desc, cause) for grouping. Exported for computeInsights(). */
 export declare function failureDescription(call: ToolCallRow, cause: TraceFailureCause): string;
 /** Build the redacted rich console shard from indexed metadata and derived caches. */
@@ -138,7 +236,16 @@ export interface SessionDetail {
     schema: 1;
     id: string;
     meta: {
+        /** Raw wall-clock span (last event − first event), idle time included. */
         spanMs: number;
+        /**
+         * Active time: `spanMs` minus every idle gap > 120s (PHNX-3457). A session
+         * resumed hours later, or left idle mid-turn, inflates `spanMs` with wall-clock
+         * the agent did no work in — active time strips those gaps so a duration reads
+         * as effort, not calendar span. This is what the console's duration median/p90
+         * should trust; `spanMs` stays available as the raw figure.
+         */
+        activeMs: number;
         turns: number;
         tools: number;
         errorCount: number;