@phnx-labs/agents-cli 1.20.89 → 1.20.90

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

@@ -6,6 +6,7 @@ import { type SessionAttachment } from './types.js';
 import { type SessionProvenance } from './provenance.js';
 import { type DeviceRegistry } from '../devices/registry.js';
 import { type Presence } from './detached.js';
+import { type HostLink } from './host-link.js';
 /**
  * The owner (actor id) to show for a session in `--active`. Prefers the actor
  * recorded on the live-attribution source (the pid registry / teammate record),
@@ -44,7 +45,11 @@ export type ActiveContext = 'terminal' | 'teams' | 'cloud' | 'headless';
  * antigravity) gets a real working/waiting/idle from its own parser — see
  * {@link computeLiveSignals}, {@link lifecycleStatus} and {@link resolveFallbackStatus}.
  */
-export type ActiveStatus = 'running' | 'idle' | 'queued' | 'input_required' | 'closed' | 'abandoned' | 'unknown';
+export type ActiveStatus = 'running' | 'idle' | 'queued' | 'input_required' | 'closed' | 'abandoned'
+/** Alive, but no client is attached — the host window died and the agent outlived it. */
+ | 'orphaned'
+/** The host window died and took the agent with it — an unclean exit, not a normal close. */
+ | 'crashed' | 'unknown';
 export interface ActiveSession {
     context: ActiveContext;
     kind: string;
@@ -122,6 +127,35 @@ export interface ActiveSession {
      * from the detach store — never asserted by a source.
      */
     presence?: Presence;
+    /**
+     * Whether anything is still on the other end of this session — folded on at the
+     * end of {@link getActiveSessions} by {@link foldHostLink} from the raw signals
+     * below, never asserted by a source. Drives the `orphaned` / `crashed` statuses.
+     */
+    hostLink?: HostLink;
+    /**
+     * Whether this session's process was alive at scan time — the boolean
+     * {@link applyState} already computes, kept rather than thrown away.
+     *
+     * `status` cannot stand in for it. `abandoned` fires on transcript staleness
+     * BEFORE the liveness check, so it covers a live-but-stuck process as well as
+     * a long-dead one; only `closed`/`crashed` are unconditionally dead. A consumer
+     * that must tell "still there, just quiet" from "gone" needs this, not the
+     * status. Absent from cloud rows (no pid) and from a peer running an older CLI.
+     */
+    pidAlive?: boolean;
+    /**
+     * Clients attached to this session's tmux session (`#{session_attached}`), for
+     * a tmux-hosted row. Absent — NOT zero — when the session is not tmux-hosted:
+     * zero means "tmux says nobody is looking", absent means "we cannot tell".
+     */
+    tmuxClients?: number;
+    /**
+     * When the owning IDE window last refreshed its slice of the live-terminals
+     * registry. Absent for a session no IDE window owns. A stale value means that
+     * window is gone — see {@link HOST_HEARTBEAT_STALE_MS}.
+     */
+    windowHeartbeatMs?: number;
     /** How many live PIDs resolve to this same session (subagents/forks). 1 unless collapsed. */
     pidCount?: number;
     /**
@@ -208,6 +242,24 @@ export interface ActiveSession {
         app: string;
         tab?: number;
     };
+    /**
+     * The editor tab that launched this agent (`AGENT_TERMINAL_ID`), from the pid
+     * 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
+     * this is how that tab re-identifies its own session. Absent for any launch that
+     * did not inherit a terminal id.
+     */
+    terminalId?: string;
+    /**
+     * tmux pane id (`%N`) when this row was discovered via the tmux source AND its
+     * session id could not be resolved (a born-unidentifiable non-Claude pane). It
+     * is the dedupe key for such id-less rows, so two anonymous panes in the same
+     * cwd render as two distinct rows instead of collapsing onto each other. Unset
+     * once a session id resolves (the id is the identity then).
+     */
+    paneId?: string;
 }
 export declare function activeStatusFromCloudStatus(status: CloudTaskStatus): ActiveStatus;
 export interface ActiveQueryOptions {
@@ -238,6 +290,22 @@ export declare const ABANDONED_STALE_MS: number;
  * `.exe` suffix (`claude.exe`), so basename + suffix-strip before the lookup.
  */
 export declare function agentKindFromComm(commRaw: string): string | undefined;
+/** Agent kind from an `ag-<agent>-<shortid>` tmux session name, else undefined. */
+export declare function agentKindFromName(sessName: string): string | undefined;
+/** The 8-char session-id prefix from an `ag-<agent>-<shortid>` name, else undefined. */
+export declare function shortIdFromName(sessName: string): string | undefined;
+/**
+ * Map every `ag-<agent>-<shortid>` tmux session name to its full session UUID in
+ * ONE batched DB lookup. The live scan calls this once per poll (not per pane),
+ * then resolvePaneIdentity reads the map — the recovery that makes a detached
+ * agent findable by `focus <id>` even when its durable identity records are gone.
+ * `findSessionsByShortIds` is injected so this stays unit-testable without a DB.
+ */
+export declare function resolveNamesToSessionIds(sessionNames: string[], deps: {
+    findSessionsByShortIds: (shortIds: string[]) => Map<string, {
+        id: string;
+    }>;
+}): Map<string, string>;
 /**
  * True when `pid` names a live process AND — when a session's recorded
  * `startedAtMs` is supplied — that process is plausibly the SAME one, not a later
@@ -446,11 +514,11 @@ export interface PaneIdentity {
  * `source: 'teams'` panes are skipped — teammates are surfaced by listTeamsActive.
  * Pure so it is unit-tested without tmux.
  */
-export declare function resolvePaneIdentity(pane: string, meta: {
+export declare function resolvePaneIdentity(pane: string, sessName: string, meta: {
     labels?: Record<string, string>;
     source?: string;
     pane?: string;
-} | null, liveEntry: PidSessionEntry | undefined, getHookIndex: () => HookSessionIndex): PaneIdentity | undefined;
+} | null, liveEntry: PidSessionEntry | undefined, getHookIndex: () => HookSessionIndex, nameToFullId: Map<string, string>): PaneIdentity | undefined;
 /**
  * Agents hosted in the shared-socket tmux server — the authoritative source for
  * tmux-hosted interactive spawns (see src/lib/exec.ts `runInTmux`). Enumerates
@@ -471,6 +539,44 @@ export declare function listTmuxAgentSessions(): Promise<ActiveSession[]>;
  * terminal/headless row for the same session id.
  */
 export declare function getActiveSessions(opts?: ActiveQueryOptions): Promise<ActiveSession[]>;
+/**
+ * Fold tmux's attached-client count onto every tmux-hosted row.
+ *
+ * Keyed off `provenance.mux` — which {@link enrichProvenance} has already stamped
+ * on any row whose process env names a tmux pane — rather than off
+ * {@link listTmuxAgentSessions}. That source only emits a row when it can resolve
+ * the pane's agent IDENTITY (launch registry or session meta), and on a machine
+ * where neither resolves it emits nothing at all while the same sessions still
+ * arrive through the terminal/headless sources carrying full tmux provenance.
+ * Hanging the client count off the identity-resolving source would have made the
+ * whole orphan signal silently dead on exactly those machines.
+ *
+ * One `list-panes` per distinct socket, and only when some row is tmux-hosted —
+ * a fleet with no tmux pays nothing. A query failure leaves the count undefined,
+ * which the classifier reads as "cannot tell", never as a false zero.
+ */
+export declare function foldTmuxClients(rows: ActiveSession[]): Promise<void>;
+/**
+ * Fold the host link onto each row and, where it changes the answer, onto the
+ * status. Runs AFTER {@link foldPresence}, because a deliberately backgrounded
+ * session (`presence` `background`/`parked`) is supposed to have no client and
+ * must not be reported as an orphan.
+ *
+ * Precedence is deliberate, and the two new statuses slot in where they add
+ * information rather than destroy it:
+ *
+ *   - `abandoned` wins outright. A days-stale session is already dangling; that
+ *     it also lost its window is not the headline, and it keeps a crashed row
+ *     from lingering as an alert forever.
+ *   - `crashed` REPLACES `closed`. Both mean the process is gone, but `closed`
+ *     reads as a normal exit; `crashed` says the host window went down with it
+ *     and never cleaned up.
+ *   - `orphaned` replaces only `idle` / `input_required`. A session still WORKING
+ *     with nobody watching is a normal headless run, and flagging every one would
+ *     bury the real signal. A session sitting idle — or worse, waiting on a
+ *     question — with no client attached is the stranded case: nobody is coming.
+ */
+export declare function foldHostLink(rows: ActiveSession[]): void;
 /**
  * Resolve each teams row's `orchestratorLabel` from the orchestrator's own row,
  * when that orchestrator session is itself in the active set (it usually is — the

package/dist/lib/session/active.js

@@ -29,7 +29,7 @@ import { readSessionActorRecord } from './actor-sidecar.js';
 import { loadHookSessionIndex, resolveHookSessionRecord, readStateSessionRecord } from './hook-sessions.js';
 import { buildClaudeLabelMap, getAgentSessionDirs } from './discover.js';
 import { buildRunNameMap } from './run-names.js';
-import { latestSessionFileForCwd } from './db.js';
+import { latestSessionFileForCwd, findSessionsByShortIds } from './db.js';
 import { extractSessionTopic } from './prompt.js';
 import { readSessionTailWithRaw } from './tail.js';
 import { parseSession } from './parse.js';
@@ -39,6 +39,7 @@ import { isSessionTrackedAgent } from './types.js';
 import { detectProvenance } from './provenance.js';
 import { loadDevices } from '../devices/registry.js';
 import { presenceFromStore } from './detached.js';
+import { classifyHostLink, HOST_HEARTBEAT_STALE_MS } from './host-link.js';
 import { mapBounded } from '../concurrency.js';
 const execFileAsync = promisify(execFile);
 /**
@@ -88,6 +89,12 @@ const LIVE_TERMINALS_FILE = path.join(getTerminalsDir(), 'live-terminals.json');
  * healthy session writes several times a minute.
  */
 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.
+ */
+const TMUX_LIST_PANES_TIMEOUT_MS = 5_000;
 /**
  * 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
@@ -106,6 +113,25 @@ export const ACTIVE_SESSION_STALE_MS = 24 * 60 * 60_000;
  * concern) — this is the lifecycle threshold, not the freshness window.
  */
 export const ABANDONED_STALE_MS = 2 * 24 * 60 * 60_000;
+/**
+ * Field separator for every `tmux list-panes -F` query here.
+ *
+ * NOT a tab. tmux sanitizes non-printable characters out of format output (3.6a
+ * rewrites a literal tab — and any non-ASCII sentinel — to `_`), so a
+ * tab-separated format comes back as one unsplittable field.
+ * {@link listTmuxAgentSessions} split on `\t`, so on such a tmux every line
+ * failed its `sessName` guard and the function returned ZERO rows, silently
+ * losing the authoritative tmux source (exact `%pane`, real identities) on every
+ * box running a recent tmux.
+ *
+ * `:` specifically, and not some other printable: tmux itself replaces `:` (and
+ * `.`) in a session name with `_`, so the separator provably cannot occur inside
+ * the one free-text field that is not last. A path CAN contain `:`, which is why
+ * `pane_current_path` is queried last and its tail rejoined rather than
+ * destructured. A separator that a session name may contain — `|`, say — would
+ * just reintroduce the same class of bug with a lower probability.
+ */
+const TMUX_FIELD_SEP = ':';
 /** Executables we recognize as agent CLIs when scanning the process table. */
 const AGENT_CLI_NAMES = {
     claude: 'claude',
@@ -137,6 +163,56 @@ export function agentKindFromComm(commRaw) {
     const key = stripped === base ? base : stripped.toLowerCase();
     return AGENT_CLI_NAMES[key];
 }
+/**
+ * A tmux agent session name is `ag-<agent>-<shortid>` (see src/lib/exec.ts
+ * `runInTmux`), where `<agent>` is the agent kind passed to `agents run` (may
+ * contain a hyphen, e.g. `cursor-agent`) and `<shortid>` is the first 8 hex chars
+ * of the session UUID. Anchored on the 8-hex suffix so the agent part is split
+ * unambiguously. The agent part is NOT cross-checked against AGENT_CLI_NAMES (that
+ * map is the narrower ps-scan comm set): the panes live on the agent-only socket,
+ * and validating there would silently drop grok/kimi/antigravity — the exact
+ * harness-parity gap we are fixing.
+ */
+const AG_NAME_RE = /^ag-([a-z][a-z0-9-]*?)-([0-9a-f]{8})$/i;
+/** Agent kind from an `ag-<agent>-<shortid>` tmux session name, else undefined. */
+export function agentKindFromName(sessName) {
+    const m = AG_NAME_RE.exec(sessName);
+    return m ? m[1].toLowerCase() : undefined;
+}
+/** The 8-char session-id prefix from an `ag-<agent>-<shortid>` name, else undefined. */
+export function shortIdFromName(sessName) {
+    const m = AG_NAME_RE.exec(sessName);
+    return m ? m[2].toLowerCase() : undefined;
+}
+/**
+ * Map every `ag-<agent>-<shortid>` tmux session name to its full session UUID in
+ * ONE batched DB lookup. The live scan calls this once per poll (not per pane),
+ * then resolvePaneIdentity reads the map — the recovery that makes a detached
+ * agent findable by `focus <id>` even when its durable identity records are gone.
+ * `findSessionsByShortIds` is injected so this stays unit-testable without a DB.
+ */
+export function resolveNamesToSessionIds(sessionNames, deps) {
+    const shortIdToNames = new Map();
+    for (const name of sessionNames) {
+        const short = shortIdFromName(name);
+        if (!short)
+            continue;
+        const arr = shortIdToNames.get(short);
+        if (arr)
+            arr.push(name);
+        else
+            shortIdToNames.set(short, [name]);
+    }
+    const out = new Map();
+    if (shortIdToNames.size === 0)
+        return out;
+    const metas = deps.findSessionsByShortIds([...shortIdToNames.keys()]);
+    for (const [short, meta] of metas) {
+        for (const name of shortIdToNames.get(short) ?? [])
+            out.set(name, meta.id);
+    }
+    return out;
+}
 /**
  * A process that began more than this long AFTER a session's recorded
  * `startedAtMs` cannot be that session's process — the OS handed its pid to
@@ -204,7 +280,20 @@ export function isPidAlive(pid, startedAtMs) {
     }
     return true;
 }
-/** Read the live-terminals registry, dedupe by sessionId, keep only pid-alive entries. */
+/**
+ * Read the live-terminals registry, dedupe by sessionId.
+ *
+ * A pid-alive entry is a live session. A pid-DEAD entry is normally noise — a
+ * terminal that closed a moment ago, before its window republished — and is
+ * dropped. But a dead pid whose owning window ALSO stopped republishing is the
+ * signature of a crash: the window went down hard and never ran the teardown that
+ * would have removed this entry. Those are KEPT, so the session reaches the
+ * listing at all — it used to vanish outright, a VS Code crash simply erasing its
+ * agents from `--active`. Such a row arrives as `closed` (dead pid) carrying the
+ * stale `windowHeartbeatMs`, which is what {@link foldHostLink} promotes to
+ * `crashed`. `pidDead` is local to the dedupe below: a live entry must win a dead
+ * one for the same session.
+ */
 function readLiveTerminals() {
     let raw;
     try {
@@ -222,12 +311,27 @@ function readLiveTerminals() {
     }
     if (!parsed || typeof parsed !== 'object')
         return [];
+    const now = Date.now();
     const merged = new Map();
     for (const [windowId, slice] of Object.entries(parsed)) {
+        const at = Date.parse(slice?.at ?? '');
+        const windowHeartbeatMs = Number.isFinite(at) ? at : undefined;
+        const windowGone = windowHeartbeatMs !== undefined && now - windowHeartbeatMs >= HOST_HEARTBEAT_STALE_MS;
         for (const e of (slice?.entries ?? [])) {
-            if (!e?.sessionId || !isPidAlive(e.pid, e.startedAtMs))
+            if (!e?.sessionId)
                 continue;
-            merged.set(e.sessionId, { ...e, windowId });
+            const alive = isPidAlive(e.pid, e.startedAtMs);
+            // Dead pid + a window still republishing = an ordinary close mid-debounce.
+            // Dead pid + a window that stopped republishing = the crash we must report.
+            if (!alive && !windowGone)
+                continue;
+            const entry = { ...e, windowId, windowHeartbeatMs, pidDead: !alive };
+            // A live entry always wins a dead one for the same session (the agent was
+            // relaunched into a new window while the crashed window's slice lingers).
+            const prev = merged.get(e.sessionId);
+            if (prev && !prev.pidDead && !alive)
+                continue;
+            merged.set(e.sessionId, entry);
         }
     }
     return Array.from(merged.values());
@@ -476,7 +580,7 @@ function statusFromActivity(activity) {
  */
 function applyState(base, state, fallbackFile, pidAlive) {
     if (!state)
-        return { ...base, status: resolveFallbackStatus(fallbackFile, pidAlive) };
+        return { ...base, pidAlive, status: resolveFallbackStatus(fallbackFile, pidAlive) };
     // Lifecycle (closed/abandoned) is computed from PID + mtime and OVERRIDES the
     // activity-derived status: a dead or days-stale process is closed/abandoned no
     // matter what its last parsed transcript turn looked like (a dead session whose
@@ -485,6 +589,7 @@ function applyState(base, state, fallbackFile, pidAlive) {
     const life = lifecycleStatus(pidAlive, base.lastActivityMs ?? sessionFileTimes(fallbackFile).mtimeMs);
     return {
         ...base,
+        pidAlive,
         status: life ?? statusFromActivity(state.activity),
         activity: state.activity,
         awaitingReason: state.awaitingReason,
@@ -684,6 +789,7 @@ export async function listTerminalsActive() {
             startedAtMs: t.startedAtMs,
             lastActivityMs: sessionFileTimes(sessionFile).mtimeMs,
             windowId: t.windowId,
+            windowHeartbeatMs: t.windowHeartbeatMs,
             owner: resolveOwner(pidEntry?.actor, resolvedId),
         }, state, sessionFile, pidAlive);
     });
@@ -1116,6 +1222,7 @@ export async function listUnattributedActive(attributed) {
             lastActivityMs: mtimeMs,
             pidCount: 1 + (foldedByRoot.get(pid) ?? 0),
             owner: resolveOwner(entry?.actor, resolvedId),
+            terminalId: entry?.terminalId,
         }, state, sessionFile, true));
     }
     // Housekeeping: drop registry files for pids that have since died.
@@ -1140,26 +1247,41 @@ export async function listUnattributedActive(attributed) {
  * `source: 'teams'` panes are skipped — teammates are surfaced by listTeamsActive.
  * Pure so it is unit-tested without tmux.
  */
-export function resolvePaneIdentity(pane, meta, liveEntry, getHookIndex) {
+export function resolvePaneIdentity(pane, sessName, meta, liveEntry, getHookIndex, nameToFullId) {
     if (meta?.source === 'teams')
         return undefined;
+    // The tmux session name encodes the agent kind (100% of ag-* panes) and, for a
+    // spawn whose id was known at creation (Claude), the session-id prefix — already
+    // resolved to a full UUID in the batch map. It is the last-resort id source when
+    // every durable record is missing (the common fleet case: meta/pid-reg/hook all
+    // ~3% populated), and would otherwise leave the pane id-less and mis-collapsed.
+    const nameAgent = agentKindFromName(sessName);
+    const nameSessionId = nameToFullId.get(sessName);
     if (liveEntry) {
         // Exact id: the id recorded at launch (Claude), else the agent's own
         // SessionStart hook joined by launchId/terminalId (non-Claude, or agents we
-        // didn't launch) — kind-guarded against a stale reused-pid file.
+        // didn't launch) — kind-guarded against a stale reused-pid file — else the id
+        // carried in the pane's own tmux name.
         const sessionId = liveEntry.sessionId
             ?? resolveHookSessionRecord(getHookIndex(), {
                 pid: liveEntry.pid,
                 kind: liveEntry.agent,
                 launchId: liveEntry.launchId,
                 terminalId: liveEntry.terminalId,
-            })?.session_id;
+            })?.session_id
+            ?? nameSessionId;
         return { agent: liveEntry.agent, sessionId, pid: liveEntry.pid };
     }
+    // No live-registry entry. Session-meta labels are the wrapped-origin fallback;
+    // prefer them, then fall back to the name so a pane with neither a registry
+    // entry nor meta labels still resolves (agent from the name, id from the batch
+    // map when present) instead of being dropped and mis-attributed by the ps-scan.
     const agent = meta?.labels?.agent;
     const sessionId = meta?.labels?.sessionId;
     if (agent && sessionId && (meta?.pane == null || meta.pane === pane))
         return { agent, sessionId };
+    if (nameAgent)
+        return { agent: nameAgent, sessionId: nameSessionId };
     return undefined;
 }
 /**
@@ -1184,8 +1306,12 @@ export async function listTmuxAgentSessions() {
     try {
         res = await runTmux({
             socket,
-            args: ['list-panes', '-a', '-F', '#{pane_id}\t#{session_name}\t#{pane_pid}\t#{pane_current_path}'],
+            args: ['list-panes', '-a', '-F', ['#{pane_id}', '#{session_name}', '#{pane_pid}', '#{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`.
+            timeoutMs: TMUX_LIST_PANES_TIMEOUT_MS,
         });
     }
     catch {
@@ -1208,17 +1334,29 @@ export async function listTmuxAgentSessions() {
     // (a non-Claude split) and needs the SessionStart-hook join.
     let hookIndex;
     const getHookIndex = () => (hookIndex ??= loadHookSessionIndex());
+    // Resolve every `ag-<agent>-<shortid>` pane name to its full session UUID in one
+    // batched DB round-trip, so resolvePaneIdentity can recover the id straight from
+    // the pane name — the signal present on 100% of ag-* panes when the durable
+    // identity stores are empty.
+    const nameToFullId = resolveNamesToSessionIds(res.stdout.split('\n').map((l) => l.split(TMUX_FIELD_SEP)[1]).filter((n) => !!n), { findSessionsByShortIds });
     const out = [];
     const seen = new Set();
     for (const line of res.stdout.split('\n')) {
         if (!line.trim())
             continue;
-        const [pane, sessName, pidRaw, curPath] = line.split('\t');
+        // The path is the LAST field, so rejoin its tail: a directory containing the
+        // separator must not truncate it (the earlier fields cannot contain one).
+        const parts = line.split(TMUX_FIELD_SEP);
+        const [pane, sessName, pidRaw] = parts;
+        const curPath = parts.slice(3).join(TMUX_FIELD_SEP);
         if (!pane || !sessName)
             continue;
         const meta = readSessionMeta(sessName);
         const liveEntry = liveByPane.get(pane);
-        let id = resolvePaneIdentity(pane, meta, liveEntry, getHookIndex);
+        let id = resolvePaneIdentity(pane, sessName, meta, liveEntry, getHookIndex, nameToFullId);
+        // Only a genuinely foreign pane — no live entry, no meta labels, and not one
+        // of our `ag-*` names — is dropped now; every agent pane survives to be either
+        // id-resolved or emitted as its own distinct id-less row.
         if (!id)
             continue;
         // RUSH-2007 Layer A: a non-Claude tmux session whose id resolved via neither the
@@ -1247,7 +1385,11 @@ export async function listTmuxAgentSessions() {
         // does NOT also surface this agent as a duplicate headless row.
         const pid = id.pid ?? (parseInt(pidRaw, 10) || undefined);
         const cwd = liveEntry?.cwd ?? meta?.cwd ?? (curPath || undefined);
-        const sessionFile = findSessionFileForKind(id.agent, cwd, id.sessionId);
+        // Only resolve a transcript when we KNOW the session id. With no id,
+        // findSessionFileForKind falls back to the newest .jsonl in the cwd — which
+        // collapses every co-located pane onto one stranger's transcript (the ×N-badge
+        // bug). Refuse to guess: an id-less pane surfaces as its own row instead.
+        const sessionFile = id.sessionId ? findSessionFileForKind(id.agent, cwd, id.sessionId) : undefined;
         const topic = sessionFile ? quickExtractTopic(sessionFile) : undefined;
         const pidAlive = pid ? isPidAlive(pid, liveEntry?.startedAtMs) : true;
         const { state, tokPerSec } = computeLiveSignals(id.agent, sessionFile, cwd, pidAlive);
@@ -1279,6 +1421,9 @@ export async function listTmuxAgentSessions() {
             lastActivityMs: mtimeMs,
             provenance,
             owner: resolveOwner(liveEntry?.actor, id.sessionId ?? sessionIdFromFile(sessionFile)),
+            // An id-less pane keys its dedupe on the unique pane, so two anonymous
+            // co-located panes stay two rows instead of folding into one.
+            paneId: id.sessionId ?? sessionIdFromFile(sessionFile) ? undefined : pane,
         }, state, sessionFile, pidAlive));
     }
     return out;
@@ -1312,9 +1457,120 @@ export async function getActiveSessions(opts = {}) {
     await enrichProvenance(merged);
     await resolveOrigins(merged);
     foldPresence(merged);
+    await foldTmuxClients(merged);
+    foldHostLink(merged);
     annotateOrchestratorLabels(merged);
     return merged;
 }
+/**
+ * Fold tmux's attached-client count onto every tmux-hosted row.
+ *
+ * Keyed off `provenance.mux` — which {@link enrichProvenance} has already stamped
+ * on any row whose process env names a tmux pane — rather than off
+ * {@link listTmuxAgentSessions}. That source only emits a row when it can resolve
+ * the pane's agent IDENTITY (launch registry or session meta), and on a machine
+ * where neither resolves it emits nothing at all while the same sessions still
+ * arrive through the terminal/headless sources carrying full tmux provenance.
+ * Hanging the client count off the identity-resolving source would have made the
+ * whole orphan signal silently dead on exactly those machines.
+ *
+ * One `list-panes` per distinct socket, and only when some row is tmux-hosted —
+ * a fleet with no tmux pays nothing. A query failure leaves the count undefined,
+ * which the classifier reads as "cannot tell", never as a false zero.
+ */
+export async function foldTmuxClients(rows) {
+    const tmuxRows = rows.filter((s) => s.provenance?.mux?.kind === 'tmux' && s.provenance.mux.pane);
+    if (tmuxRows.length === 0)
+        return;
+    const { runTmux } = await import('../tmux/binary.js');
+    const sockets = new Set(tmuxRows.map((s) => s.provenance.mux.socket));
+    for (const socket of sockets) {
+        const byPane = new Map();
+        try {
+            const res = await runTmux({
+                socket,
+                args: ['list-panes', '-a', '-F', `#{pane_id}${TMUX_FIELD_SEP}#{session_attached}`],
+                throwOnError: false,
+            });
+            if (res.code !== 0)
+                continue;
+            for (const line of res.stdout.split('\n')) {
+                const [pane, attached] = line.split(TMUX_FIELD_SEP);
+                if (!pane)
+                    continue;
+                const n = parseInt(attached ?? '', 10);
+                // A tmux too old to report `session_attached` yields NaN — leave the pane
+                // unmapped so it stays "cannot tell" rather than becoming a false zero.
+                if (Number.isFinite(n))
+                    byPane.set(pane, n);
+            }
+        }
+        catch {
+            continue; // best-effort: no count is honest, a guessed count is not
+        }
+        for (const s of tmuxRows) {
+            if (s.provenance.mux.socket !== socket)
+                continue;
+            const n = byPane.get(s.provenance.mux.pane);
+            if (n !== undefined)
+                s.tmuxClients = n;
+        }
+    }
+}
+/**
+ * Fold the host link onto each row and, where it changes the answer, onto the
+ * status. Runs AFTER {@link foldPresence}, because a deliberately backgrounded
+ * session (`presence` `background`/`parked`) is supposed to have no client and
+ * must not be reported as an orphan.
+ *
+ * Precedence is deliberate, and the two new statuses slot in where they add
+ * information rather than destroy it:
+ *
+ *   - `abandoned` wins outright. A days-stale session is already dangling; that
+ *     it also lost its window is not the headline, and it keeps a crashed row
+ *     from lingering as an alert forever.
+ *   - `crashed` REPLACES `closed`. Both mean the process is gone, but `closed`
+ *     reads as a normal exit; `crashed` says the host window went down with it
+ *     and never cleaned up.
+ *   - `orphaned` replaces only `idle` / `input_required`. A session still WORKING
+ *     with nobody watching is a normal headless run, and flagging every one would
+ *     bury the real signal. A session sitting idle — or worse, waiting on a
+ *     question — with no client attached is the stranded case: nobody is coming.
+ */
+export function foldHostLink(rows) {
+    for (const s of rows) {
+        // Cloud tasks have no local pid, window, or tmux server; there is no host
+        // link to classify and no honest answer to give.
+        if (s.context === 'cloud')
+            continue;
+        // A days-stale row is already `abandoned`; whether its window is also gone
+        // adds nothing, and its pid liveness is genuinely unknown from the status
+        // (abandoned outranks closed), so claim no host link rather than guess one.
+        if (s.status === 'abandoned')
+            continue;
+        // `closed` IS the dead-pid status — `lifecycleStatus` assigns it from
+        // `!pidAlive` and nothing else — so the status is the pid answer here.
+        const link = classifyHostLink({
+            pidAlive: s.status !== 'closed',
+            windowHeartbeatMs: s.windowHeartbeatMs,
+            tmuxClients: s.tmuxClients,
+            deliberatelyDetached: s.presence === 'background' || s.presence === 'parked',
+        });
+        s.hostLink = link;
+        // `foldPresence` gives every terminal row a DERIVED `attached` — "a live
+        // interactive TUI you're watching" — which is exactly the claim a lost host
+        // disproves. A stored record never yields `attached` (it is background or
+        // parked), so clearing only that value drops the derived lie and leaves a
+        // real detach record untouched.
+        if (link !== 'connected' && s.presence === 'attached')
+            s.presence = undefined;
+        if (link === 'host-gone' && s.status === 'closed')
+            s.status = 'crashed';
+        else if (link === 'no-client' && (s.status === 'idle' || s.status === 'input_required')) {
+            s.status = 'orphaned';
+        }
+    }
+}
 /**
  * Resolve each teams row's `orchestratorLabel` from the orchestrator's own row,
  * when that orchestrator session is itself in the active set (it usually is — the
@@ -1450,7 +1706,7 @@ export function dedupeBySession(sessions) {
     const out = [];
     const byKey = new Map();
     for (const s of sessions) {
-        const key = s.sessionId || s.sessionFile || s.cloudTaskId || s.agentId || anonymousWorkerKey(s);
+        const key = s.sessionId || s.sessionFile || s.cloudTaskId || s.agentId || s.paneId || anonymousWorkerKey(s);
         if (!key) {
             out.push(s);
             continue;

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

@@ -341,6 +341,20 @@ export declare function getSessionById(id: string): SessionMeta | null;
  * ambiguous prefix disambiguates against the caller's context.
  */
 export declare function findSessionsById(idQuery: string, scope?: Pick<QueryOptions, 'agent' | 'version' | 'cwd' | 'project'>): SessionMeta[];
+/**
+ * Batch-resolve many 8-char short ids to their sessions in ONE indexed query.
+ * The live-scan path (listTmuxAgentSessions) turns every `ag-<agent>-<shortid>`
+ * tmux pane name back into a full session id this way, so it pays a single
+ * `short_id IN (…)` round-trip per scan instead of N per-pane lookups.
+ *
+ * Returns a map keyed by short_id (lowercased). Short ids are the first 8 chars
+ * of the lowercase session UUID (deriveShortId), so a lowercased `IN` matches and
+ * still uses idx_sessions_short_id. When several sessions share a short id — only
+ * time-ordered ids (ULID/UUIDv7) ever collide; random UUIDv4 short ids are unique
+ * in practice — the most-recently-active one wins (the caller can further
+ * disambiguate by cwd).
+ */
+export declare function findSessionsByShortIds(shortIds: string[]): Map<string, SessionMeta>;
 /** A single full-text search result with ranking score. */
 export interface FtsHit {
     sessionId: string;

package/dist/lib/session/db.js

@@ -1567,6 +1567,41 @@ export function findSessionsById(idQuery, scope = {}) {
         return exact;
     return querySessions({ ...scope, idPrefix: q });
 }
+/**
+ * Batch-resolve many 8-char short ids to their sessions in ONE indexed query.
+ * The live-scan path (listTmuxAgentSessions) turns every `ag-<agent>-<shortid>`
+ * tmux pane name back into a full session id this way, so it pays a single
+ * `short_id IN (…)` round-trip per scan instead of N per-pane lookups.
+ *
+ * Returns a map keyed by short_id (lowercased). Short ids are the first 8 chars
+ * of the lowercase session UUID (deriveShortId), so a lowercased `IN` matches and
+ * still uses idx_sessions_short_id. When several sessions share a short id — only
+ * time-ordered ids (ULID/UUIDv7) ever collide; random UUIDv4 short ids are unique
+ * in practice — the most-recently-active one wins (the caller can further
+ * disambiguate by cwd).
+ */
+export function findSessionsByShortIds(shortIds) {
+    const out = new Map();
+    const uniq = [...new Set(shortIds.map((s) => s.trim().toLowerCase()).filter(Boolean))];
+    if (uniq.length === 0)
+        return out;
+    const db = getDB();
+    const CHUNK = 500; // stay well under SQLite's default 999-variable limit
+    for (let i = 0; i < uniq.length; i += CHUNK) {
+        const batch = uniq.slice(i, i + CHUNK);
+        const placeholders = batch.map(() => '?').join(',');
+        // timestamp ASC so a later (newer) row overwrites an earlier one per short_id.
+        const rows = db
+            .prepare(`SELECT * FROM sessions WHERE short_id IN (${placeholders}) ORDER BY timestamp ASC`)
+            .all(...batch);
+        for (const row of rows) {
+            const key = (row.short_id ?? '').toLowerCase();
+            if (key)
+                out.set(key, rowToMeta(row));
+        }
+    }
+    return out;
+}
 /**
  * Escape a raw user query into a safe FTS5 MATCH expression.
  * Splits on non-word characters, keeps tokens >= 2 chars, and OR-joins