@phnx-labs/agents-cli 1.22.38 → 1.22.40

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

@@ -2,7 +2,7 @@ import type { CloudTaskStatus } from '../cloud/types.js';
 import { type PidSessionEntry } from './pid-registry.js';
 import { type HookSessionIndex } from './hook-sessions.js';
 import { type SessionState, type SessionActivity, type AwaitingReason, type StructuredQuestion, type TodoProgress, type DetectedPr, type DetectedWorktree, type DetectedTicket } from './state.js';
-import { type SessionAgentId, type SessionAttachment } from './types.js';
+import { type SessionAgentId, type SessionAttachment, type SessionMeta } from './types.js';
 import { type SessionProvenance } from './provenance.js';
 import { type DeviceRegistry } from '../devices/registry.js';
 import { type Presence } from './detached.js';
@@ -60,6 +60,19 @@ export declare function attributedSetLostPids(prev: Set<number>, next: Set<numbe
  */
 export declare function filterCachedUnattributed(sessions: ActiveSession[], attributed: Set<number>, alive: (pid: number, startedAtMs?: number) => boolean): ActiveSession[];
 export type ActiveContext = 'terminal' | 'teams' | 'cloud' | 'headless';
+/** The SessionMeta fields the live-row backfill reads — the enrichment a running process cannot report. */
+export type BackfillMeta = Pick<SessionMeta, 'version' | 'timestamp' | 'label' | 'ticketId' | 'prUrl' | 'prNumber' | 'origin' | 'routineName'>;
+export declare function backfillActiveRowsFromMeta(sessions: ActiveSession[], metaById: Map<string, BackfillMeta>): void;
+export declare function backfillActiveRowsFromIndex(sessions: ActiveSession[]): void;
+export declare function isRunningLiveSession(s: ActiveSession): boolean;
+export declare function activeSessionProjectKey(s: Pick<ActiveSession, 'cwd' | 'context'>): string;
+export declare function serializeActiveSessionsForJson(sessions: ActiveSession[]): Array<Omit<ActiveSession, 'viewingIn'> & {
+    ticketId: string | null;
+    project: string;
+    prLink: string | null;
+    viewingIn: string | null;
+}>;
+export declare function serializeSessionsJson(sessions: SessionMeta[]): string;
 /**
  * Every status here is COMPUTED by the framework from observable signals — PID
  * liveness and transcript last-write (mtime) — never self-reported by the agent.
@@ -307,7 +320,7 @@ export interface ActiveSession {
      * registry. This is the one identifier that survives an SSH hop AND a session
      * rotation: a Factory tab offloaded to a device has no local process to inspect,
      * and its spawn-time session id goes stale the moment the agent moves to another
-     * session (`/clear`, exit-and-rerun), so `--active --host <device>` joined on
+     * session (`/clear`, exit-and-rerun), so `--active --device <device>` joined on
      * this is how that tab re-identifies its own session. Absent for any launch that
      * did not inherit a terminal id.
      */
@@ -334,6 +347,18 @@ export interface ActiveQueryOptions {
      */
     localOnly?: boolean;
 }
+/**
+ * Thrown by {@link listTmuxAgentSessions} when the socket exists (a server has
+ * run) but tmux could not be asked for its truth — spawn failure, timeout, or a
+ * nonzero exit. Distinct from a missing socket, which means no server ever ran
+ * and is genuinely empty, not degraded. `getActiveSessions` still swallows this
+ * to `[]` so its return type stays a plain session array, but
+ * {@link describeActiveDiscoveryHealth} re-probes and surfaces it so the empty
+ * case a real fleet sweep found (RUSH-2507) reads differently from a clean one.
+ */
+export declare class TmuxDiscoveryDegradedError extends Error {
+    constructor(message: string);
+}
 /**
  * A live process can only borrow an indexed session file if that transcript
  * has been touched recently enough to plausibly belong to the process. This is
@@ -465,12 +490,24 @@ export declare function resolveFallbackStatus(sessionFile: string | undefined, p
  * (+ optional session uuid), so they resolve straight off disk. Every OTHER
  * tracked harness — Codex (date-partitioned), plus grok / droid / rush / gemini /
  * kimi / hermes / opencode / antigravity / cursor (per-session dirs, SQLite, single-JSON)
- * — is resolved through the session index by cwd: the newest indexed transcript
- * for that cwd, bounded by ACTIVE_SESSION_STALE_MS so a live pid never borrows a
- * weeks-old transcript. This is what lets a live NON-claude/codex agent get a real
- * status instead of falling through to `unknown` (the file feeds
+ * — is resolved through the session index. When the session id is KNOWN, that id
+ * selects the transcript. Only an id-less process falls back to the newest indexed
+ * transcript for that cwd, bounded by ACTIVE_SESSION_STALE_MS so a live pid never
+ * borrows a weeks-old transcript. This is what lets a live NON-claude/codex agent
+ * get a real status instead of falling through to `unknown` (the file feeds
  * {@link computeLiveSignals}). An opaque kind we don't track still yields undefined
  * here and degrades honestly to a live `running`.
+ *
+ * The id branch exists because the cwd fallback is only safe when there is nothing
+ * better: it answers `WHERE agent = ? AND cwd = ? ORDER BY last_activity DESC LIMIT 1`
+ * (`latestSessionFileForCwd`), so with two same-harness agents in ONE cwd — routine on
+ * this fleet — every one of them resolves to whichever transcript was touched last.
+ * That is the same "one stranger's transcript" hazard the id-less tmux pane already
+ * refuses to guess at (see `listTmuxAgentSessions`), and since RUSH-2682 it reaches
+ * further than a status badge: the live row now backs `sessions preview <id>`, so the
+ * guess renders session B's digest under session A's header and caches it against A.
+ * An id we cannot resolve yields undefined — the honest "not indexed here" render —
+ * rather than a neighbour's transcript (RUSH-2691).
  */
 export declare function findSessionFileForKind(kind: string, cwd?: string, sessionId?: string): string | undefined;
 /** Live per-session signals derived from one transcript-tail read. */
@@ -641,6 +678,21 @@ export declare function listTmuxAgentSessions(): Promise<ActiveSession[]>;
  * terminal/headless row for the same session id.
  */
 export declare function getActiveSessions(opts?: ActiveQueryOptions): Promise<ActiveSession[]>;
+/** Local discovery sources probed by {@link describeActiveDiscoveryHealth}. */
+export interface ActiveDiscoveryHealth {
+    /** Sources that failed on the probe (currently only `'tmux'`). Empty = nothing degraded locally. */
+    degradedSources: string[];
+}
+/**
+ * Cheap post-hoc health probe for the local discovery sources. `getActiveSessions`
+ * always swallows a source failure to `[]` so its return type stays a plain
+ * session array — this re-probes the same sources and reports which ones threw,
+ * so a caller that got an empty list back can tell "genuinely nothing running"
+ * apart from "a source errored and got silently folded into empty" (RUSH-2507).
+ * Intended for the empty-result branch only, not the hot path — it repeats a
+ * `list-panes` call `getActiveSessions` already made.
+ */
+export declare function describeActiveDiscoveryHealth(): Promise<ActiveDiscoveryHealth>;
 /**
  * True when a live agent process on this host carries `--session-id <id>` in
  * its argv. RUSH-2384 last-resort for `agents message`: getActiveSessions can
@@ -707,7 +759,7 @@ export declare function foldTmuxClients(rows: ActiveSession[]): Promise<void>;
  * `registerInteractiveHostSession` write the index row with
  * `machine: normalizeHost(task.host)` (`lib/hosts/session-index.ts:55,134`), so
  * this folds that recorded machine back onto the live row. Every consumer then
- * agrees on one owner: the `--host`/`--device` scope, the browser's device
+ * agrees on one owner: the `--device`/`--device` scope, the browser's device
  * filter, `_remote`/preview routing (`liveSessionToMeta`), and the id resolver.
  *
  * Two rows are deliberately left alone:

package/dist/lib/session/active.js

@@ -29,7 +29,7 @@ import { readSessionActorRecord, writeSessionAliasRecord } from './actor-sidecar
 import { loadHookSessionIndex, resolveHookSessionRecord, readStateSessionRecord } from './hook-sessions.js';
 import { buildClaudeLabelMap, getAgentSessionDirs } from './discover.js';
 import { buildRunNameMap } from './run-names.js';
-import { latestSessionFileForCwd, findSessionsByShortIds, findSessionMachinesByIds } from './db.js';
+import { latestSessionFileForCwd, findSessionsByShortIds, findSessionMachinesByIds, getSessionById } from './db.js';
 import { extractSessionTopic } from './prompt.js';
 import { readSessionTailWithRaw } from './tail.js';
 import { parseSession } from './parse.js';
@@ -43,6 +43,8 @@ import { machineId, normalizeHost } from '../machine-id.js';
 import { presenceFromStore } from './detached.js';
 import { classifyHostLink, HOST_HEARTBEAT_STALE_MS } from './host-link.js';
 import { mapBounded } from '../concurrency.js';
+import { linearIssueUrl } from './linear.js';
+import { viewingInLabel } from './viewing-in.js';
 const execFileAsync = promisify(execFile);
 /**
  * The owner (actor id) to show for a session in `--active`. Prefers the actor
@@ -140,6 +142,79 @@ export function filterCachedUnattributed(sessions, attributed, alive) {
         return alive(s.pid, s.startedAtMs);
     });
 }
+export function backfillActiveRowsFromMeta(sessions, metaById) {
+    for (const s of sessions) {
+        if (!s.sessionId)
+            continue;
+        const m = metaById.get(s.sessionId);
+        if (!m)
+            continue;
+        if (!s.version && m.version)
+            s.version = m.version;
+        if (!s.label && m.label)
+            s.label = m.label;
+        if (!s.ticket && m.ticketId)
+            s.ticket = { id: m.ticketId, url: linearIssueUrl(m.ticketId) };
+        if (!s.pr && m.prUrl)
+            s.pr = { url: m.prUrl, number: m.prNumber };
+        if (!s.startedAtMs && m.timestamp) {
+            const ts = new Date(m.timestamp).getTime();
+            if (!Number.isNaN(ts))
+                s.startedAtMs = ts;
+        }
+        if (!s.origin && m.origin)
+            s.origin = m.origin;
+        if (!s.routineName && m.routineName)
+            s.routineName = m.routineName;
+    }
+}
+function loadBackfillMetaFor(sessions) {
+    const byId = new Map();
+    try {
+        for (const s of sessions) {
+            if (!s.sessionId || byId.has(s.sessionId))
+                continue;
+            const m = getSessionById(s.sessionId);
+            if (m)
+                byId.set(s.sessionId, m);
+        }
+    }
+    catch {
+        /* enrichment is best-effort — an unavailable DB leaves rows un-backfilled */
+    }
+    return byId;
+}
+export function backfillActiveRowsFromIndex(sessions) {
+    backfillActiveRowsFromMeta(sessions, loadBackfillMetaFor(sessions));
+}
+export function isRunningLiveSession(s) {
+    if (s.status === 'queued' || s.status === 'closed' || s.status === 'crashed')
+        return false;
+    if (s.context === 'cloud')
+        return Boolean(s.cloudProvider) && Boolean(s.cloudTaskId);
+    return Boolean(s.machine) && typeof s.pid === 'number' && s.pid > 0 && s.pidAlive === true;
+}
+export function activeSessionProjectKey(s) {
+    if (s.cwd)
+        return path.basename(s.cwd);
+    return s.context === 'cloud' ? 'cloud' : 'other';
+}
+export function serializeActiveSessionsForJson(sessions) {
+    return sessions.map((s) => ({
+        ...s,
+        ticketId: s.ticket?.id ?? null,
+        project: activeSessionProjectKey(s),
+        prLink: s.pr?.url ?? null,
+        viewingIn: viewingInLabel(s) ?? null,
+    }));
+}
+export function serializeSessionsJson(sessions) {
+    const serializable = sessions.map((s) => {
+        const { _matchedTerms, _bm25Score, _remote, ...rest } = s;
+        return rest;
+    });
+    return JSON.stringify(serializable, null, 2) + '\n';
+}
 export function activeStatusFromCloudStatus(status) {
     switch (status) {
         case 'running':
@@ -162,9 +237,24 @@ const ACTIVE_MTIME_WINDOW_MS = 2 * 60_000;
 /**
  * Bound on the tmux `list-panes` call in {@link listTmuxAgentSessions}. A wedged
  * tmux server would otherwise hang the whole `--active` scan (the other sources
- * can't run past it); on timeout the tmux source degrades to empty.
+ * can't run past it); on timeout the tmux source throws {@link TmuxDiscoveryDegradedError}.
  */
 const TMUX_LIST_PANES_TIMEOUT_MS = 5_000;
+/**
+ * Thrown by {@link listTmuxAgentSessions} when the socket exists (a server has
+ * run) but tmux could not be asked for its truth — spawn failure, timeout, or a
+ * nonzero exit. Distinct from a missing socket, which means no server ever ran
+ * and is genuinely empty, not degraded. `getActiveSessions` still swallows this
+ * to `[]` so its return type stays a plain session array, but
+ * {@link describeActiveDiscoveryHealth} re-probes and surfaces it so the empty
+ * case a real fleet sweep found (RUSH-2507) reads differently from a clean one.
+ */
+export class TmuxDiscoveryDegradedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'TmuxDiscoveryDegradedError';
+    }
+}
 /**
  * A live process can only borrow an indexed session file if that transcript
  * has been touched recently enough to plausibly belong to the process. This is
@@ -621,22 +711,47 @@ export function resolveFallbackStatus(sessionFile, pidAlive, nowMs = Date.now())
  * (+ optional session uuid), so they resolve straight off disk. Every OTHER
  * tracked harness — Codex (date-partitioned), plus grok / droid / rush / gemini /
  * kimi / hermes / opencode / antigravity / cursor (per-session dirs, SQLite, single-JSON)
- * — is resolved through the session index by cwd: the newest indexed transcript
- * for that cwd, bounded by ACTIVE_SESSION_STALE_MS so a live pid never borrows a
- * weeks-old transcript. This is what lets a live NON-claude/codex agent get a real
- * status instead of falling through to `unknown` (the file feeds
+ * — is resolved through the session index. When the session id is KNOWN, that id
+ * selects the transcript. Only an id-less process falls back to the newest indexed
+ * transcript for that cwd, bounded by ACTIVE_SESSION_STALE_MS so a live pid never
+ * borrows a weeks-old transcript. This is what lets a live NON-claude/codex agent
+ * get a real status instead of falling through to `unknown` (the file feeds
  * {@link computeLiveSignals}). An opaque kind we don't track still yields undefined
  * here and degrades honestly to a live `running`.
+ *
+ * The id branch exists because the cwd fallback is only safe when there is nothing
+ * better: it answers `WHERE agent = ? AND cwd = ? ORDER BY last_activity DESC LIMIT 1`
+ * (`latestSessionFileForCwd`), so with two same-harness agents in ONE cwd — routine on
+ * this fleet — every one of them resolves to whichever transcript was touched last.
+ * That is the same "one stranger's transcript" hazard the id-less tmux pane already
+ * refuses to guess at (see `listTmuxAgentSessions`), and since RUSH-2682 it reaches
+ * further than a status badge: the live row now backs `sessions preview <id>`, so the
+ * guess renders session B's digest under session A's header and caches it against A.
+ * An id we cannot resolve yields undefined — the honest "not indexed here" render —
+ * rather than a neighbour's transcript (RUSH-2691).
  */
 export function findSessionFileForKind(kind, cwd, sessionId) {
     if (!cwd)
         return undefined;
     if (kind === 'claude')
         return findClaudeSessionFile(cwd, sessionId);
-    if (isSessionTrackedAgent(kind)) {
-        return latestSessionFileForCwd(kind, cwd, { maxAgeMs: ACTIVE_SESSION_STALE_MS });
-    }
-    return undefined;
+    if (!isSessionTrackedAgent(kind))
+        return undefined;
+    if (sessionId)
+        return indexedSessionFileForId(kind, sessionId);
+    return latestSessionFileForCwd(kind, cwd, { maxAgeMs: ACTIVE_SESSION_STALE_MS });
+}
+/**
+ * The indexed transcript for one exact session id, or undefined when the index has
+ * not reached it yet. The `agent` guard rejects a row that belongs to a different
+ * harness than the live process claims: those cannot be the same conversation, and
+ * returning it would reintroduce the misattribution this function exists to avoid.
+ */
+function indexedSessionFileForId(kind, sessionId) {
+    const row = getSessionById(sessionId);
+    if (!row || row.agent !== kind)
+        return undefined;
+    return row.filePath || undefined;
 }
 /** Recover the session UUID from a transcript filename (Claude `<uuid>.jsonl`, Codex `rollout-…-<uuid>.jsonl`). */
 const UUID_RE = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i;
@@ -1540,6 +1655,9 @@ export async function listTmuxAgentSessions() {
     const { readSessionMeta } = await import('../tmux/session.js');
     const { runTmux } = await import('../tmux/binary.js');
     const socket = getDefaultSocketPath();
+    // No server has ever run on this socket — genuinely nothing to report, not
+    // a degraded read. Distinct from the throws below, which mean tmux truth
+    // exists but could not be read (RUSH-2507).
     if (!fs.existsSync(socket))
         return [];
     let res;
@@ -1549,16 +1667,19 @@ export async function listTmuxAgentSessions() {
             args: ['list-panes', '-a', '-F', ['#{pane_id}', '#{session_name}', '#{pane_pid}', '#{pane_dead}', '#{pane_current_path}'].join(TMUX_FIELD_SEP)],
             throwOnError: false,
             // A wedged tmux server must not hang the whole active-session scan. The
-            // catch below turns a timeout into an empty tmux source (the other sources
-            // still report) rather than a frozen `agents sessions --active`.
+            // catch below turns a timeout into a DEGRADED-tmux-source signal (the
+            // other sources still report) rather than a frozen `agents sessions
+            // --active` — and, crucially, no longer collapses into the same silent
+            // `[]` a genuinely-idle socket returns (RUSH-2507).
             timeoutMs: TMUX_LIST_PANES_TIMEOUT_MS,
         });
     }
-    catch {
-        return [];
+    catch (err) {
+        throw new TmuxDiscoveryDegradedError(`tmux list-panes on ${socket} did not answer: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (res.code !== 0) {
+        throw new TmuxDiscoveryDegradedError(`tmux list-panes on ${socket} exited ${res.code}: ${res.stderr.trim() || res.stdout.trim()}`);
     }
-    if (res.code !== 0)
-        return [];
     // Index live launches by the pane they target, so a pane we did NOT wrap (a
     // split) resolves to its own agent. Newest launch wins a pane (pid reuse), and
     // only live pids count — a dead agent's stale entry can't light up its old pane.
@@ -1716,6 +1837,26 @@ export async function getActiveSessions(opts = {}) {
     annotateOrchestratorLabels(merged);
     return merged;
 }
+/**
+ * Cheap post-hoc health probe for the local discovery sources. `getActiveSessions`
+ * always swallows a source failure to `[]` so its return type stays a plain
+ * session array — this re-probes the same sources and reports which ones threw,
+ * so a caller that got an empty list back can tell "genuinely nothing running"
+ * apart from "a source errored and got silently folded into empty" (RUSH-2507).
+ * Intended for the empty-result branch only, not the hot path — it repeats a
+ * `list-panes` call `getActiveSessions` already made.
+ */
+export async function describeActiveDiscoveryHealth() {
+    const degradedSources = [];
+    try {
+        await listTmuxAgentSessions();
+    }
+    catch (err) {
+        if (err instanceof TmuxDiscoveryDegradedError)
+            degradedSources.push('tmux');
+    }
+    return { degradedSources };
+}
 /**
  * True when a live agent process on this host carries `--session-id <id>` in
  * its argv. RUSH-2384 last-resort for `agents message`: getActiveSessions can
@@ -1826,7 +1967,7 @@ export async function foldTmuxClients(rows) {
  * `registerInteractiveHostSession` write the index row with
  * `machine: normalizeHost(task.host)` (`lib/hosts/session-index.ts:55,134`), so
  * this folds that recorded machine back onto the live row. Every consumer then
- * agrees on one owner: the `--host`/`--device` scope, the browser's device
+ * agrees on one owner: the `--device`/`--device` scope, the browser's device
  * filter, `_remote`/preview routing (`liveSessionToMeta`), and the id resolver.
  *
  * Two rows are deliberately left alone:

package/dist/lib/session/bash-command.js

@@ -140,7 +140,7 @@ const VALUE_FLAGS = {
     // (`agents sessions`, `linear list`) instead of one flat `other` pile (#1830).
     // `ag` is deliberately NOT here — it is the silver searcher in TOOL_REGISTRY,
     // not the agents alias, in this classifier's world.
-    agents: new Set(['-H', '--host', '--device']),
+    agents: new Set(['-D', '--device']),
     linear: new Set(),
 };
 /**

package/dist/lib/session/claude-accounts.d.ts

@@ -55,7 +55,7 @@
  *
  * Until that lands, a non-Claude session has a NULL `account_key` and rolls up under
  * `unattributed:<agent>` — named after its harness rather than implying we tried and
- * failed. `--by account` on `agents cost` / `agents output` therefore reports Claude
+ * failed. `--by account` on `agents insights cost` / `agents insights output` therefore reports Claude
  * accounts plus one bucket per other harness.
  */
 /** The account a transcript is attributed to. */

package/dist/lib/session/claude-accounts.js

@@ -55,7 +55,7 @@
  *
  * Until that lands, a non-Claude session has a NULL `account_key` and rolls up under
  * `unattributed:<agent>` — named after its harness rather than implying we tried and
- * failed. `--by account` on `agents cost` / `agents output` therefore reports Claude
+ * failed. `--by account` on `agents insights cost` / `agents insights output` therefore reports Claude
  * accounts plus one bucket per other harness.
  */
 import * as os from 'os';

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

@@ -192,6 +192,14 @@ export declare function maintainSessionSearchIndex(db?: Database.Database, optio
  * mode can return SQLITE_BUSY_SNAPSHOT which bypasses the busy handler.
  */
 export declare function tryClaimScan(pid: number): boolean;
+/**
+ * Read-only probe: is a scan in progress right now, held by a LIVE process
+ * within the TTL? (RUSH-2682). Unlike {@link tryClaimScan} it never writes, so a
+ * caller that lost the claim can wait for the in-flight scan to finish rather
+ * than returning the pre-scan DB snapshot as if it were the answer. Returns
+ * false for a dead-PID or expired claim — that scan is not actually running.
+ */
+export declare function scanInProgressByLivePid(): boolean;
 /**
  * Release the scan claim written by tryClaimScan. Only deletes the entry
  * if it still belongs to this process (guards against TTL takeovers).
@@ -354,7 +362,7 @@ export interface UsageRollupRow {
     costUsd: number;
     /**
      * USD cost priced as if caching were off (cache read/write at the input rate),
-     * summed from `cost_usd_nocache`. Backs `agents output --pricing no-cache`.
+     * summed from `cost_usd_nocache`. Backs `agents insights output --pricing no-cache`.
      * Equals `costUsd` for rows whose sessions record no cache split (RUSH-2287).
      */
     costUsdNoCache: number;
@@ -472,7 +480,7 @@ export declare function queryAffinityRollup(options: {
 /**
  * Aggregate cost / duration / tokens across sessions, grouped by agent,
  * project, or calendar day. Honors the same filter shape as querySessions
- * (agent, since/until, team-origin) so `agents cost --since 7d --by day`
+ * (agent, since/until, team-origin) so `agents insights cost --since 7d --by day`
  * lines up with what `agents sessions` would list. Ordered by cost desc.
  */
 export declare function queryUsageRollup(options: QueryOptions & {

package/dist/lib/session/db.js

@@ -12,7 +12,7 @@ import Database from '../sqlite.js';
 import { parseSession, sessionFilePathContainer } from './parse.js';
 import { extractRecentDirectoriesTouched, extractTodoProgressFromEvents } from './state.js';
 import { getSessionsDir, getSessionsDbPath } from '../state.js';
-import { query as queryEvents, queryToolUsageForSessions } from '../events.js';
+import { query as queryEvents, queryToolUsageForSessions } from '../feed/events.js';
 import { machineForSessionFile } from './origin-machine.js';
 import { loadSessionActorIndex, readSessionActorRecord } from './actor-sidecar.js';
 import { toolCallsFromEvents } from './tool-calls.js';
@@ -20,7 +20,7 @@ import { persistToolCalls, toolEvidenceSourcePath } from './tool-store.js';
 import { buildClaudeAccountIndex, resolveClaudeAccount } from './claude-accounts.js';
 import { extractSkills, extractSlashCommands } from './highlights.js';
 import { resolveResource } from '../resources.js';
-import { discoverPlugins } from '../plugins.js';
+import { discoverPlugins } from '../plugins/plugins.js';
 import { machineId } from '../machine-id.js';
 const SESSIONS_DIR = getSessionsDir();
 const DB_PATH = getSessionsDbPath();
@@ -528,7 +528,7 @@ function migrateSchema(db, fromVersion) {
         // v11 → v12: `output_tokens` — the real generated-token count, kept separate
         // from `token_count` (which sums cache-read/-write and so is dominated by
         // cheap re-counted context). This is the honest "output" metric powering
-        // `agents output`. Additive column; rescan to backfill from transcripts.
+        // `agents insights output`. Additive column; rescan to backfill from transcripts.
         const cols = db.prepare(`PRAGMA table_info(sessions)`).all();
         if (!cols.some(c => c.name === 'output_tokens'))
             db.exec(`ALTER TABLE sessions ADD COLUMN output_tokens INTEGER`);
@@ -966,12 +966,12 @@ function migrateSchema(db, fromVersion) {
     }
     if (fromVersion < 37) {
         // v36 -> v37: persist the burn SPLIT (uncached input / cache-read /
-        // cache-write) and a second "no-cache" cost per session, so `agents output`
+        // cache-write) and a second "no-cache" cost per session, so `agents insights output`
         // can report the token split and a --pricing no-cache scenario (RUSH-2287).
         // These are new nullable columns — do NOT flush scan_ledger (adding a column
         // must keep warm session ledgers warm, the contract the v33->v34 note above
         // states). Pre-upgrade rows stay NULL for the split until their transcript is
-        // re-scanned; `agents output` reports the split only where it is present, so
+        // re-scanned; `agents insights output` reports the split only where it is present, so
         // an absent split reads as "not available for this session", never as zero.
         const cols = new Set(db.prepare(`PRAGMA table_info(sessions)`).all().map((c) => c.name));
         if (!cols.has('input_tokens'))
@@ -1309,6 +1309,25 @@ export function tryClaimScan(pid) {
     });
     return txn();
 }
+/**
+ * Read-only probe: is a scan in progress right now, held by a LIVE process
+ * within the TTL? (RUSH-2682). Unlike {@link tryClaimScan} it never writes, so a
+ * caller that lost the claim can wait for the in-flight scan to finish rather
+ * than returning the pre-scan DB snapshot as if it were the answer. Returns
+ * false for a dead-PID or expired claim — that scan is not actually running.
+ */
+export function scanInProgressByLivePid() {
+    const db = getDB();
+    const existing = db
+        .prepare(`SELECT value FROM meta WHERE key = 'scan_in_progress'`)
+        .get();
+    if (!existing)
+        return false;
+    const parts = existing.value.split(':');
+    const pid = parseInt(parts[0], 10);
+    const ts = parseInt(parts[1], 10);
+    return isProcessAlive(pid) && Date.now() - ts < SCAN_CLAIM_TTL_MS;
+}
 /**
  * Release the scan claim written by tryClaimScan. Only deletes the entry
  * if it still belongs to this process (guards against TTL takeovers).
@@ -2807,7 +2826,7 @@ export function queryAffinityRollup(options) {
 /**
  * Aggregate cost / duration / tokens across sessions, grouped by agent,
  * project, or calendar day. Honors the same filter shape as querySessions
- * (agent, since/until, team-origin) so `agents cost --since 7d --by day`
+ * (agent, since/until, team-origin) so `agents insights cost --since 7d --by day`
  * lines up with what `agents sessions` would list. Ordered by cost desc.
  */
 export function queryUsageRollup(options) {

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

@@ -52,6 +52,19 @@ export interface DiscoverOptions {
     skill?: string;
     /** Only sessions that used a skill/command owned by this plugin (#12) — see QueryOptions.plugin. */
     plugin?: string;
+    /** Exact session id — a targeted indexed lookup with no scan (RUSH-2477). */
+    idExact?: string;
+    /** Session id prefix — a targeted indexed lookup with no scan (RUSH-2477). */
+    idPrefix?: string;
+    /**
+     * Cold-miss repair: when another live process already holds the scan claim,
+     * wait (bounded) for that in-flight scan to finish before reading the index,
+     * instead of returning the pre-scan snapshot (RUSH-2682). A caller repairing a
+     * "not indexed yet" miss wants the fresh result the concurrent scan is about to
+     * write, not the stale read that just missed. Ignored when THIS process wins
+     * the claim (it scans itself) or no scan is in progress.
+     */
+    waitForScan?: boolean;
 }
 /** Progress report emitted during incremental scanning. */
 export interface ScanProgress {
@@ -158,11 +171,75 @@ interface CodexSessionScan {
  * TTL, no external lock files needed.
  */
 export declare function discoverSessions(options?: DiscoverOptions): Promise<SessionMeta[]>;
+/** What one incremental scan actually did. */
+export interface IncrementalScanResult {
+    /** True when this process won the single-flight claim and ran the scan. */
+    claimed: boolean;
+    /**
+     * Transcripts parsed this scan — i.e. those whose (mtime, size) changed. Zero
+     * is the steady state on an idle box and does NOT mean the scan was skipped;
+     * read `claimed` for that.
+     *
+     * Twelve of the 13 SESSION_AGENTS contribute, including OpenCode, whose
+     * scanner filters to sessions whose own per-session stamp changed and reports
+     * that batch — so a tick whose only changed sessions live there no longer
+     * reports 0 (RUSH-2691). OpenClaw is the exception and contributes nothing:
+     * its scanner has no change detection to report (a TTL gate, a fresh stamp
+     * every run, and an entry list rebuilt as the current inventory), so counting
+     * it would overstate rather than measure. See `scanOpenClawIncremental`.
+     */
+    scanned: number;
+}
+/**
+ * The write half of {@link discoverSessions}: claim the single-flight scan slot,
+ * incrementally index this host's transcript dirs, and report what was parsed.
+ *
+ * Split out so a caller that only wants the index refreshed — the daemon's warm
+ * tick — can run it WITHOUT the listing query `discoverSessions` ends with. That
+ * query is not free: it applies a cwd filter, runs the `archived_at`-writing
+ * existence check, and can issue a Linear fetch, none of which index anything
+ * (RUSH-2691). Keeping one implementation here is also what stops the tick and
+ * the foreground path from drifting apart.
+ */
+export declare function scanSessionsIncremental(options?: {
+    agent?: SessionAgentId;
+    onProgress?: (p: ScanProgress) => void;
+}): Promise<IncrementalScanResult>;
+/**
+ * Poll until no live process holds the scan claim, or the bound elapses
+ * (RUSH-2682). Bounded so a wedged/slow scan can never hang a foreground preview.
+ * Exported for the cold-miss repair test.
+ */
+export declare function waitForScanToSettle(timeoutMs?: number, pollMs?: number): Promise<boolean>;
 /** Read the current SQLite snapshot without scanning or parsing transcript files. */
 export declare function queryIndexedSessions(options?: DiscoverOptions, indexedOptions?: {
     resolveLinear?: boolean;
     skipExistenceCheck?: boolean;
 }): Promise<SessionMeta[]>;
+/**
+ * Resolve a full-or-partial session id against the LOCAL SQLite index only.
+ *
+ * A plain WAL read through `queryIndexedSessions` — same origin-machine
+ * attribution and managed scoping every indexed read gets — with NO incremental
+ * discovery scan (so none of `tryClaimScan`/`releaseScan`'s `BEGIN IMMEDIATE`
+ * writer lock) and NO fleet SSH fan-out. This is the crash-restart storm path
+ * (RUSH-2477): dozens of `sessions resume <id>` at once for a known local id must
+ * each be a cheap read, never a writer-lock contender or a dial into the
+ * not-yet-up tailnet. Exact id first, then prefix (matching `findSessionsById`),
+ * so a complete id never also drags in its prefix siblings. Returns `[]` on a
+ * genuine local miss, leaving the caller to fall back to the fleet resolver.
+ *
+ * The existence check is left ON (`skipExistenceCheck: false`), exactly as the old
+ * `discoverSessions` path and `findSessionsById` do (RUSH-2436): it KEEPS a
+ * file-gone session whose user turns still live in `session_text` (flagged
+ * archived) and SUPPRESSES a contentless phantom — so a phantom id misses here and
+ * falls through to the fleet resolver, instead of resolving to a row with no real
+ * transcript to resume. For a present transcript — the storm's actual case, since
+ * the crashed tabs' files are on disk — the check does no writes, so the lock-free
+ * guarantee holds; it only writes to (un)archive a genuinely missing or resurrected
+ * file, which is not the 20-at-once resume path.
+ */
+export declare function resolveIndexedSessionById(idQuery: string): Promise<SessionMeta[]>;
 /**
  * Drop unmanaged rows for agents that HAVE managed versions.
  *