@phnx-labs/agents-cli 1.22.39 → 1.22.41

package/dist/commands/sessions.d.ts

@@ -2,9 +2,11 @@ import { type Command } from 'commander';
 import { type ProjectDef } from '../lib/projects.js';
 import type { SessionAgentId, SessionMeta, ViewMode } from '../lib/session/types.js';
 import { type ActiveSession } from '../lib/session/active.js';
+export { activeSessionProjectKey, backfillActiveRowsFromIndex, backfillActiveRowsFromMeta, isRunningLiveSession, serializeActiveSessionsForJson, serializeSessionsJson, type BackfillMeta } from '../lib/session/active.js';
+import { loadLocalActiveSessions } from '../lib/session/session-cache.js';
 import { gatherRemoteList, runOnPeer } from '../lib/session/remote-list.js';
 import { type RemoteAgentsJsonParseResult } from '../lib/remote-agents-json.js';
-import { type RunMeta } from '../lib/routines.js';
+import { type RunMeta } from '../lib/scheduling/routines.js';
 import { type PickedSession } from './sessions-picker.js';
 import { type ComputerRunRow } from '../lib/computer/sessions-list.js';
 import { type ToolSearchEnvelope, type ToolProgramCountEnvelope } from '../lib/session/tool-index.js';
@@ -70,7 +72,7 @@ interface SessionsOptions extends SessionFilterOptions {
     /** Force local-only: skip the cross-machine SSH fan-out (both the default
      * listing and --active). */
     local?: boolean;
-    /** --device <target...> — alias for --host; resolves against the device registry. */
+    /** --device <target...> — values from the `--device` flag; resolves against the device registry. */
     device?: string[];
     /** --devices <target...> — plural alias for --device; a bare `all`/`fleet` value
      * means "search the whole fleet" (already the default), so it never errors. */
@@ -142,19 +144,6 @@ export declare function formatActiveRowDescription(s: ActiveSession): string;
  * can't be correlated back to a transcript on disk.
  */
 export declare function indexActiveBySessionId(active: ActiveSession[]): Map<string, ActiveSession>;
-/** 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'>;
-/**
- * Backfill display-only fields onto live rows from the indexed SessionMeta, by
- * full session id (RUSH-2205). A running process reports no agent version, and a
- * live orphan row usually carries no ticket/PR/label/start-time; the historical
- * index does. Only a field the live row LACKS is filled — the live signal always
- * wins when present. Pure (no I/O) so the join is unit-tested against fixtures;
- * the DB read that builds `metaById` is the caller's concern.
- */
-export declare function backfillActiveRowsFromMeta(sessions: ActiveSession[], metaById: Map<string, BackfillMeta>): void;
-/** Add indexed display metadata to active rows for non-renderer consumers. */
-export declare function backfillActiveRowsFromIndex(sessions: ActiveSession[]): void;
 /**
  * The live decoration for a listing row: a status glyph and the latest-turn
  * preview, when the session is still running. `●` running / `◐` waiting on the
@@ -198,36 +187,6 @@ export declare function liveStatusWord(a: ActiveSession | undefined): string;
  * stays excluded rather than inventing a human who can answer.
  */
 export declare function isAwaitingUser(s: ActiveSession): boolean;
-/**
- * Whether a row belongs in an unqualified `--active` view (RUSH-2336) — the
- * ONE canonical selector every bare-active surface shares: the CLI's grouped
- * table and `--json` (`renderActiveSessions`), the interactive browser's
- * `--active` filter ({@link applyFilters} in `sessions-browser.ts`), `focus`'s
- * attach gate (`isAttachableLiveSession`), and the menubar snapshot
- * ({@link computeMenubarSnapshot}).
- *
- * The live registry deliberately retains terminally-dead AND not-yet-started
- * rows long enough for `--closed` / `--crashed` / `--queued` and recovery to
- * find them. Presence in that registry therefore is not, by itself, evidence
- * that a session is CURRENTLY active. Explicit lifecycle filters bypass this
- * predicate and select those retained rows through {@link matchesLiveStatus}
- * instead — this function only decides the unqualified default.
- *
- *   - `queued` / `closed` / `crashed` are never active here: queued hasn't
- *     started yet, closed/crashed are unconditionally dead. All three stay
- *     reachable through their explicit filter.
- *   - A cloud row carries no local pid at all — it is active on the
- *     provider's own word (`cloudProvider` + `cloudTaskId`), never a
- *     fabricated pid.
- *   - Every other row is a real OS process (terminal/tmux/headless/team). It
- *     is active only when the row names the machine it runs on, carries a
- *     positive pid, AND has POSITIVELY verified that pid is alive
- *     (`pidAlive === true` — not merely "not known dead"). A live orphaned
- *     row, or a live-but-stuck abandoned row, still qualifies this way since
- *     both carry a genuinely alive pid; unknown liveness (an older peer's
- *     row, or a pid that could never be resolved) does not.
- */
-export declare function isRunningLiveSession(s: ActiveSession): boolean;
 /**
  * The tracker/PR ref for a session's dedicated column: the ticket id when known,
  * else `PR#<n>`, else empty. Pulled out of the trailing badge blob so refs align
@@ -236,26 +195,36 @@ export declare function isRunningLiveSession(s: ActiveSession): boolean;
 export declare function ticketLabel(s: Pick<SessionMeta, 'ticketId' | 'prNumber'>): string;
 export declare function linkTicketCell(s: Pick<SessionMeta, 'ticketId' | 'prNumber' | 'prUrl'>, label: string): string;
 export declare function linkCwdCell(s: Pick<SessionMeta, 'cwd' | '_remote'>, label: string): string;
+/**
+ * The single project/group key for an active session row (RUSH-2688). It is the
+ * ONE derivation every project-grouped consumer of `--active`/the menubar snapshot
+ * shares, so a session is bucketed the same way everywhere:
+ *
+ *   - A real working dir → its `basename` — the same key SessionMeta derives (see
+ *     discover.ts), so the active view and the history view join identically on
+ *     (ticketId + project).
+ *   - A row with NO local cwd (a cloud task, a provider-run job) → an explicit
+ *     bucket keyed by context: `cloud` for a cloud row, else `other`.
+ *
+ * It never falls back to `kind` (the harness — 'codex', 'claude') or `machine`
+ * (the box it runs on): neither is a project, and letting either stand in for the
+ * key is exactly what leaked a Codex cloud task under a 'codex' group and a bogus
+ * machine label in the menubar. No fallback chain — one explicit bucket.
+ */
 /**
  * The row shape `agents sessions --active --json` emits. RUSH-1981: a watcher
  * joins active sessions on ticketId + project, but the raw ActiveSession nests
  * the ticket (`ticket.id`) and carries no `project` at all — so a naive join
  * silently drops every row. Emit both as flat, always-present top-level keys
- * (null when unknown) alongside the raw fields, so every active row is joinable.
- * `project` uses the same derivation SessionMeta does — basename(cwd) (see
- * discover.ts) — so the active view and the history view join identically.
+ * alongside the raw fields, so every active row is joinable. `project` is the
+ * canonical {@link activeSessionProjectKey} — basename(cwd), or an explicit
+ * `cloud`/`other` bucket for a row with no local cwd, never the harness/machine.
  *
  * `viewingIn` flattens to the same display string the row renderer prints —
  * `'codium tab 3'` / `'detached'` / null — so a consumer can tell a watched
  * session from an orphaned one (its terminal died, the agent is still running)
  * without re-implementing the tmux client lookup.
  */
-export declare function serializeActiveSessionsForJson(sessions: ActiveSession[]): Array<Omit<ActiveSession, 'viewingIn'> & {
-    ticketId: string | null;
-    project: string | null;
-    prLink: string | null;
-    viewingIn: string | null;
-}>;
 export interface SessionPickerJsonRow extends SessionMeta {
     state: ActiveSession['status'] | 'inactive';
     resumable: boolean;
@@ -351,7 +320,7 @@ export declare function groupSessionsByMachine(sessions: ActiveSession[], localM
  */
 export declare function dedupeByMachineSession(sessions: ActiveSession[]): ActiveSession[];
 /**
- * Narrow a gathered live set to the machines an explicit `--host`/`--device`
+ * Narrow a gathered live set to the machines an explicit `--device`
  * scope named. The gather picks which boxes to ASK; this asserts what the answer
  * may contain, and the two are not the same question: a host-dispatched run is
  * reported by the box that dispatched it while executing somewhere else, so
@@ -378,7 +347,6 @@ export declare function mergeLocalFirst(sessions: SessionMeta[], localMachine: s
  * newline. The single seam shared by the local `--json` path and the
  * `--json --host` remote fan-out so both emit byte-identical row shapes.
  */
-export declare function serializeSessionsJson(sessions: SessionMeta[]): string;
 /** The intentionally small metadata contract emitted by `sessions --resolve`.
  * It includes only launch identity needed to route/resume. Transcript paths,
  * extracted plans, costs, and content stay on the machine that owns them. */
@@ -393,14 +361,14 @@ export declare function parseRemoteComputerSessionRows(stdout: string, machine:
 export declare function gatherRemoteComputerSessionRows(hosts?: string[]): Promise<ComputerRunRow[]>;
 /**
  * Whether the local machine's sessions belong in an `--active` view. Local is
- * included by default; an explicit `--host`/`--device` list scopes the view to
+ * included by default; an explicit `--device` list scopes the view to
  * exactly those machines, so local is dropped unless it is itself named (by
  * alias or `user@host`, matched on the normalized machine id). Exported for
  * unit testing without touching SSH or the live process table.
  */
 export declare function shouldIncludeLocal(hosts: string[] | undefined, self: string): boolean;
 /**
- * The peers to dial for an `--active` view. No `--host` → `undefined`, which
+ * The peers to dial for an `--active` view. No `--device` → `undefined`, which
  * tells `gatherRemoteActive` to sweep the registered online devices. An
  * explicit list → exactly those, minus this machine (its sessions come from the
  * local seed, so dialing self would be a wasted SSH and a spurious "unreachable"
@@ -412,9 +380,9 @@ export declare function remoteHostsToDial(hosts: string[] | undefined, self: str
 /**
  * The fleet-wide live-session set behind every `--active` surface. Local sessions
  * come from `getActiveSessions()` and (unless `--local`) the registered online
- * devices from `ag devices` are folded in over SSH. An explicit `--host`/`--device`
+ * devices from `ag devices` are folded in over SSH. An explicit `--device`
  * list SCOPES the sweep to exactly those machines — the local machine is included
- * only when it is itself named — so `--host` is a filter, not an addition.
+ * only when it is itself named — so `--device` is a filter, not an addition.
  *
  * This is the single gather: the static renderer AND the interactive browser both
  * call it, so the browser can never disagree with `--active --json` about which
@@ -424,7 +392,7 @@ export declare function remoteHostsToDial(hosts: string[] | undefined, self: str
  * RUSH-2062: default path is cache-first against the daemon-warmed shared
  * snapshot (`session-cache.ts`). Menubar / Factory / watchdog / CLI share one
  * warm result instead of each re-running the full SSH fan-out. `forceRefresh`
- * (or `AGENTS_SESSIONS_FORCE_REFRESH=1`) re-gathers live; scoped `--host` lists
+ * (or `AGENTS_SESSIONS_FORCE_REFRESH=1`) re-gathers live; scoped `--device` lists
  * always gather live so a filter never returns a wrong unscoped snapshot.
  */
 export declare function gatherActiveSessions(opts?: {
@@ -434,6 +402,9 @@ export declare function gatherActiveSessions(opts?: {
 }): Promise<{
     sessions: ActiveSession[];
     remoteDeviceCount: number;
+    /** Peer names that went unheard on this gather (RUSH-2507). Undefined when unknown (e.g. a cache hit). */
+    remoteSkipped?: string[];
+    remoteDiscoveryFailed?: boolean;
 }>;
 /** Apply the routine selector to enriched live rows for every non-browser active view. */
 export declare function filterActiveSessionsByRoutine(sessions: ActiveSession[], routine: boolean | string | undefined): ActiveSession[];
@@ -445,8 +416,8 @@ export declare function requestedLiveStatuses(options: SessionsOptions): LiveSta
 /**
  * A bare interactive fleet listing — no query, no render/filter flag — that the
  * `runSessionBrowser` picker can represent. The single predicate shared by the
- * bare-browser branch and the `--host` early-return guard so they can't drift:
- * when this holds, an explicit `--host`/`--device` scope is folded into the
+ * bare-browser branch and the `--device` early-return guard so they can't drift:
+ * when this holds, an explicit `--device` scope is folded into the
  * browser (preview-rich, selectable) instead of the legacy per-host raw stream.
  */
 export declare function isBareBrowserListing(options: SessionsOptions, query: string | undefined): boolean;
@@ -907,14 +878,51 @@ export declare function metadataResolveOutcome(localMatches: SessionMeta[], remo
     sessions: SessionMeta[];
     unreachable: string[];
 }, selector: string): MetadataResolveOutcome;
-/** Reusable local-first resolver for `agents run --resume` and `agents resume`.
+/** Injectable dependency for the live-registry cold-miss fallback (RUSH-2682). */
+export type LiveMetadataDeps = {
+    loadActive?: typeof loadLocalActiveSessions;
+};
+/**
+ * Local metadata candidates for a selector: the indexed SQLite rows, plus — when
+ * an id-shaped selector misses the index entirely — the live-session registry
+ * (RUSH-2682).
+ *
+ * Indexing is lazy (it only runs inside `discoverSessions`), so a session THIS
+ * box just started is "running" in `agents sessions --active` minutes before its
+ * transcript reaches the local index. Every id resolver (`preview`, `resume`,
+ * `focus`, and the fan-out peer that answers `--resolve-safe-v1`) therefore
+ * consults the SAME live registry `--active` reads before declaring a running
+ * session non-existent. It reshapes process state the registry already computed;
+ * it parses no transcript and renders nothing. The live path is entered ONLY on a
+ * cold id miss, so an indexed hit keeps its richer row and keyword resolution is
+ * unchanged.
+ */
+export declare function computeLocalMetadataMatches(selector: string, scope: {
+    agent?: string;
+    project?: string;
+    local?: boolean;
+    hosts?: string[];
+}, deps?: LiveMetadataDeps): Promise<SessionMeta[]>;
+/**
+ * Resolve an id-shaped selector against the local live-session registry
+ * (RUSH-2682). Reads the daemon-warmed active snapshot first (cheap); if that
+ * snapshot predates a just-started session and misses, it forces ONE fresh
+ * gather before conceding, so a session started seconds ago resolves
+ * synchronously. Never throws — a degraded registry read yields no candidates,
+ * so the caller falls through to the ordinary not-found path.
+ */
+export declare function liveMetadataMatches(selector: string, scope: {
+    agent?: string;
+    project?: string;
+}, self: string, deps?: LiveMetadataDeps): Promise<SessionMeta[]>;
+/** Reusable local-first resolver for `agents run --resume` and `agents sessions resume`.
  * Full UUIDs hit the local SQLite index without any SSH fan-out. */
 export declare function resolveSessionMetadataValue(selector: string, scope?: {
     agent?: string;
     project?: string;
     local?: boolean;
     hosts?: string[];
-}, deps?: Pick<FleetResolveDeps, 'gatherRemoteList'>): Promise<MetadataResolveOutcome>;
+}, deps?: Pick<FleetResolveDeps, 'gatherRemoteList'> & LiveMetadataDeps): Promise<MetadataResolveOutcome>;
 /** Resolve one selector to indexed metadata across the fleet without reading or
  * rendering transcript events. A peer answering the parent sweep returns every
  * local candidate; the parent performs the one logical-session uniqueness gate.
@@ -926,7 +934,7 @@ export declare function resolveSessionMetadata(selector: string, scope: {
     project?: string;
     local?: boolean;
     hosts?: string[];
-}, deps?: Pick<FleetResolveDeps, 'gatherRemoteList'>): Promise<void>;
+}, deps?: Pick<FleetResolveDeps, 'gatherRemoteList'> & LiveMetadataDeps): Promise<void>;
 /**
  * Locate a full session id or short id prefix across the online fleet and render it from the machine
  * that holds it. The local disk already missed; this fans `sessions <id> --json
@@ -934,7 +942,7 @@ export declare function resolveSessionMetadata(selector: string, scope: {
  * groups the rows to distinct machines, then:
  *
  *   - exactly one logical session → delegate rendering to one peer via `runOnPeer`
- *     (its transcript and agent binary live there — a local `--host` hop would
+ *     (its transcript and agent binary live there — a local `--device` hop would
  *     re-discover locally and dead-end), returning `'rendered'`.
  *   - more than one logical session → print every full-id candidate with its
  *     machine labels, returning `{ kind: 'conflict' }`.
@@ -961,4 +969,3 @@ export type FleetResolveResult = {
 export declare function resolveSessionAcrossFleet(query: string, mode: ViewMode, hosts?: string[], deps?: FleetResolveDeps): Promise<FleetResolveResult>;
 /** Register the `agents sessions` command with all its options and help text. */
 export declare function registerSessionsCommands(program: Command): void;
-export {};