@phnx-labs/agents-cli 1.20.77 → 1.20.78

package/dist/commands/sessions-browser.js

@@ -9,14 +9,15 @@
  * Built on {@link dynamicPicker}; every data source (discover, fleet, live index,
  * preview, resume dispatch) is reused from the existing sessions plumbing.
  */
+import path from 'path';
 import { spawnSync } from 'child_process';
 import { dynamicPicker } from '../lib/picker.js';
-import { getActiveSessions } from '../lib/session/active.js';
+import { isSessionTrackedAgent } from '../lib/session/types.js';
 import { discoverSessions } from '../lib/session/discover.js';
 import { gatherRemoteList } from '../lib/session/remote-list.js';
 import { machineId, normalizeHost } from '../lib/session/sync/config.js';
 import { buildPreview } from './sessions-picker.js';
-import { formatPickerLabel, pickerColumnsFor, ticketLabel, mergeLocalFirst, indexActiveBySessionId, handlePickedSession, shouldIncludeLocal, remoteHostsToDial, } from './sessions.js';
+import { formatPickerLabel, pickerColumnsFor, ticketLabel, mergeLocalFirst, gatherActiveSessions, liveHostLabel, LIVE_ROW_PREFIX, cleanPreview, handlePickedSession, shouldIncludeLocal, remoteHostsToDial, } from './sessions.js';
 /** Ordered window cycle for the `W` key. `undefined` = all time. */
 const WINDOW_CYCLE = [undefined, '1d', '7d', '30d'];
 /** Return the next value in `[undefined, ...options]`, wrapping. */
@@ -102,20 +103,25 @@ export function activeBrowserSeed(opts) {
         agent: opts.agent,
         projectScope: 'all',
         device: normalizeDeviceSeed(opts.host?.[0]),
-        window: opts.since ?? '30d',
+        // --all widens the window to all-time (project is already 'all' here);
+        // --since still overrides.
+        window: opts.since ?? (opts.all ? undefined : '30d'),
     };
 }
 /**
  * The initial filter for the bare interactive listing: current-repo subtree by
- * default (matches the static overview's cwd scoping), `--all` widens to every
- * directory, `--since` seeds the window.
+ * default (matches the static overview's cwd scoping). `--all` sets every
+ * non-status filter to its "all" value — every directory (project) AND all-time
+ * (window) — so one flag maxes the view; `--since` still overrides the window and
+ * `-a`/`--device` still narrow their axis.
  */
 export function bareBrowserSeed(opts) {
     return {
         teams: !!opts.teams,
         agent: opts.agent,
+        // --all maxes every non-status filter: all dirs AND all-time. --since wins.
         projectScope: opts.all ? 'all' : 'repo',
-        window: opts.since ?? '30d',
+        window: opts.since ?? (opts.all ? undefined : '30d'),
     };
 }
 /** Copy text to the OS clipboard (best-effort; silently no-ops if unavailable). */
@@ -182,6 +188,99 @@ async function fetchRawPool(f, self, local, hosts) {
     }
     return { key: `${since ?? 'all'}|${f.teams}`, rows };
 }
+/**
+ * A live session's stable row key: its session id when the agent reported one,
+ * else a per-machine handle so an id-less live session (a just-booted harness, a
+ * cloud task) still gets exactly one row instead of being dropped. Cloud rows key
+ * on the task id because they have no pid — keying them all on the machine alone
+ * would collapse two cloud tasks into one row, the same silent-drop this whole
+ * change exists to remove.
+ */
+export function liveRowKey(a, self) {
+    if (a.sessionId)
+        return a.sessionId;
+    const handle = a.cloudTaskId ?? (a.pid != null ? String(a.pid) : 'unknown');
+    return `${LIVE_ROW_PREFIX}${a.machine ?? self}:${handle}`;
+}
+/** Index live sessions by {@link liveRowKey} — the join key between the live scan
+ *  and the transcript pool. Id-carrying rows key on the session id, so a live row
+ *  and its transcript row collapse to one. */
+export function indexLiveRows(rows, self) {
+    const byKey = new Map();
+    for (const a of rows)
+        byKey.set(liveRowKey(a, self), a);
+    return byKey;
+}
+/**
+ * Project a live session onto the picker's row shape, for a session the transcript
+ * pool doesn't carry — a peer's session, a transcript outside the current window,
+ * or an agent that has not written one yet. `filePath` is the live transcript path
+ * when the scan resolved one and empty otherwise, which is what
+ * {@link handlePickedSession} keys "there is nothing to open yet" off.
+ */
+export function liveSessionToMeta(a, self) {
+    const machine = a.machine ?? self;
+    const started = a.startedAtMs ?? a.lastActivityMs;
+    const topic = a.topic ?? a.preview;
+    return {
+        id: liveRowKey(a, self),
+        // No session id to short — name the row by what it IS (a cloud task, a pid),
+        // so the id column still identifies the process you'd go looking for.
+        shortId: a.sessionId
+            ? a.sessionId.slice(0, 8)
+            : a.cloudTaskId
+                ? a.cloudTaskId.slice(0, 8)
+                : `p:${a.pid ?? '?'}`,
+        agent: isSessionTrackedAgent(a.kind) ? a.kind : 'claude',
+        timestamp: new Date(started ?? Date.now()).toISOString(),
+        lastActivity: a.lastActivityMs ? new Date(a.lastActivityMs).toISOString() : undefined,
+        project: a.cwd ? path.basename(a.cwd) : undefined,
+        cwd: a.cwd,
+        filePath: a.sessionFile ?? '',
+        // A live topic is raw transcript text: a newline in it would break the row
+        // into two and misalign every column after it. Indexed rows are already
+        // cleaned at scan time, so this puts projected rows on the same footing.
+        topic: topic ? cleanPreview(topic) : undefined,
+        label: a.label ? cleanPreview(a.label) : undefined,
+        machine,
+        // Reading/resuming a peer's session hops back over SSH — same contract the
+        // cross-machine listing sets, so handlePickedSession routes it correctly.
+        _remote: machine !== self,
+        prUrl: a.pr?.url,
+        prNumber: a.pr?.number,
+        ticketId: a.ticket?.id,
+        worktreeSlug: a.worktree?.slug,
+    };
+}
+/**
+ * Fold the live scan INTO the transcript pool. The running filter used to be a
+ * pure intersection (`pool ∩ live`), which meant a session had to already be in
+ * the pool to be shown as running — so every session on another machine, and
+ * every local one outside the pool's window, was invisible in the browser while
+ * `--active --json` listed it. Live sessions the pool lacks are appended as their
+ * own rows, then the whole set is grouped local-machine-first.
+ */
+export function mergeLiveIntoPool(rows, live, self) {
+    const known = new Set(rows.map((r) => r.id));
+    const extra = [];
+    for (const [key, a] of live) {
+        if (!known.has(key))
+            extra.push(liveSessionToMeta(a, self));
+    }
+    return extra.length === 0 ? rows : mergeLocalFirst([...rows, ...extra], self);
+}
+/**
+ * Whether to render the host-program column. It belongs to the running view
+ * only, so this gates on the FILTER — not on the live index being populated.
+ * `liveCache` outlives a toggle of the `r` hotkey, so testing `live` alone would
+ * keep the column after running is turned back off, widening a plain transcript
+ * listing that has no live rows to explain it.
+ */
+export function shouldShowHostColumn(f, live, rows) {
+    if (!f.running || !live)
+        return false;
+    return rows.some((r) => liveHostLabel(live.get(r.id)) !== '');
+}
 /** Apply the cheap in-memory filters (agent / device / project / running). */
 function applyFilters(rows, live, f, self) {
     let out = rows;
@@ -269,11 +368,14 @@ export async function runSessionBrowser(initial = {}, opts = {}) {
                 return []; // superseded — don't touch shared state
             pool = fetched;
         }
-        // Only pay for the live scan when the running filter needs it.
+        // Only pay for the live scan when the running filter needs it. Same fleet
+        // sweep the static `--active` view uses, so the two never disagree about
+        // what is running.
         let live = liveCache;
         if (f.running && !live) {
             try {
-                live = indexActiveBySessionId(await getActiveSessions());
+                const { sessions } = await gatherActiveSessions({ local, hosts });
+                live = indexLiveRows(sessions, self);
             }
             catch {
                 live = new Map();
@@ -286,10 +388,14 @@ export async function runSessionBrowser(initial = {}, opts = {}) {
         rawCache = pool;
         if (live)
             liveCache = live;
-        agentsInPool = distinct(pool.rows.map((r) => r.agent));
-        devicesInPool = distinct(pool.rows.map((r) => r.machine ?? self));
-        const filtered = applyFilters(pool.rows, live ?? new Map(), f, self);
+        // Live sessions the transcript pool lacks become rows of their own, so the
+        // running view lists every active session, not just the ones already indexed.
+        const rows = f.running && live ? mergeLiveIntoPool(pool.rows, live, self) : pool.rows;
+        agentsInPool = distinct(rows.map((r) => r.agent));
+        devicesInPool = distinct(rows.map((r) => r.machine ?? self));
+        const filtered = applyFilters(rows, live ?? new Map(), f, self);
         cols = pickerColumnsFor(filtered);
+        cols.showHost = shouldShowHostColumn(f, live, filtered);
         return filtered;
     };
     const picked = await dynamicPicker({
@@ -297,7 +403,7 @@ export async function runSessionBrowser(initial = {}, opts = {}) {
         initialFilter,
         load,
         keyFor: (s) => s.id,
-        labelFor: (s, q) => formatPickerLabel(s, q, cols, sshOriginTagFor(liveCache, s.id)),
+        labelFor: (s, q) => formatPickerLabel(s, q, cols, sshOriginTagFor(liveCache, s.id), liveHostLabel(liveCache?.get(s.id))),
         matches: sessionMatchesQuery,
         buildPreview,
         headerFor,

package/dist/commands/sessions-export.d.ts

@@ -1,2 +1,5 @@
 import type { Command } from 'commander';
+import type { SessionMeta } from '../lib/session/types.js';
 export declare function registerSessionsExportCommand(sessionsCmd: Command): void;
+/** ids > query > everything-in-scope. Exported for the id-resolution test. */
+export declare function selectSessions(metas: SessionMeta[], selectors: string[]): SessionMeta[];

package/dist/commands/sessions-export.js

@@ -20,7 +20,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import chalk from 'chalk';
-import { discoverSessions, resolveSessionById, isCompleteSessionId } from '../lib/session/discover.js';
+import { discoverSessions, resolveSessionById, looksLikeSessionId } from '../lib/session/discover.js';
 import { findSessionsById } from '../lib/session/db.js';
 import { filterSessionsByQuery, parseAgentFilter } from './sessions.js';
 import { listLocalTranscripts, SYNC_AGENTS } from '../lib/session/sync/agents.js';
@@ -222,8 +222,8 @@ function resolveAgentShorthand(g) {
         return 'antigravity';
     return undefined;
 }
-/** ids > query > everything-in-scope. */
-function selectSessions(metas, selectors) {
+/** ids > query > everything-in-scope. Exported for the id-resolution test. */
+export function selectSessions(metas, selectors) {
     if (selectors.length === 0)
         return metas;
     const byId = [];
@@ -231,9 +231,11 @@ function selectSessions(metas, selectors) {
     for (const sel of selectors) {
         const trimmed = sel.trim();
         // Same reason as resolveSessionQuery: the discovered pool is a minority of
-        // the index, so a complete id absent from it may still be indexed here.
+        // the index, so an id-shaped selector absent from it may still be indexed
+        // here. Gate on looksLikeSessionId, not isCompleteSessionId, so a SHORT id
+        // ("d3470b57") also resolves through the index instead of falling to content.
         const hits = resolveSessionById(metas, trimmed);
-        const resolved = hits.length > 0 || !isCompleteSessionId(trimmed) ? hits : findSessionsById(trimmed);
+        const resolved = hits.length > 0 || !looksLikeSessionId(trimmed) ? hits : findSessionsById(trimmed);
         if (resolved.length > 0)
             byId.push(...resolved);
         else
@@ -243,11 +245,12 @@ function selectSessions(metas, selectors) {
         const seen = new Set();
         return byId.filter(s => (seen.has(s.id) ? false : (seen.add(s.id), true)));
     }
-    // A selector that is a COMPLETE session id and still missed cannot be widened:
-    // the id is unique, so the text query below could only bundle sessions that
-    // merely mention it. Bundling those would ship unrelated transcripts to
-    // whoever receives the export, so select nothing and let the caller report it.
-    const missingIds = unmatched.filter(isCompleteSessionId);
+    // A selector that is an id (complete OR a short hex id/prefix) and still missed
+    // cannot be widened: the id is unique, so the text query below could only bundle
+    // sessions that merely mention it. Bundling those would ship unrelated
+    // transcripts to whoever receives the export, so select nothing and let the
+    // caller report it — a short id like "d3470b57" must never content-search.
+    const missingIds = unmatched.filter(looksLikeSessionId);
     if (missingIds.length > 0) {
         process.stderr.write(chalk.red(`No session with id ${missingIds.join(', ')} on this machine.\n`));
         return [];

package/dist/commands/sessions-picker.d.ts

@@ -1,4 +1,5 @@
-import type { SessionMeta, TodoProgress } from '../lib/session/types.js';
+import type { SessionEvent, SessionMeta, TodoProgress } from '../lib/session/types.js';
+import { classifyFileChanges } from '../lib/session/digest.js';
 /**
  * Compact checklist tally for list rows and previews (RUSH-2045).
  * Example: `✓6/8 · A5 wiring runner`. Empty string when there is no list.
@@ -30,5 +31,18 @@ export interface SessionPickerConfig {
 }
 /** Build a cached multi-line preview string for display in the session picker. */
 export declare function buildPreview(session: SessionMeta): string;
+/** Optional dirs-touched field the parser teammate may attach; we prefer it. */
+type SessionMetaWithDirs = SessionMeta & {
+    dirsTouched?: string[];
+};
+/**
+ * Unique directories the session touched, compact and human-readable.
+ * Prefer `session.dirsTouched` when the parser teammate has populated it;
+ * otherwise derive from file-change + tool paths already available here.
+ */
+export declare function directoriesTouched(session: SessionMetaWithDirs, events: SessionEvent[], changes: ReturnType<typeof classifyFileChanges>): string[];
+/** Relativize a file path to its parent dir, short enough for one preview line. */
+export declare function relativizeDir(filePath: string, cwd?: string): string | undefined;
 /** Show an interactive session picker and return the selected session with its action (resume or view). */
 export declare function sessionPicker(config: SessionPickerConfig): Promise<PickedSession | null>;
+export {};

package/dist/commands/sessions-picker.js

@@ -13,7 +13,7 @@ import { parseSession, sanitizeForTerminal } from '../lib/session/parse.js';
 import { cleanSessionPrompt, extractSessionTopic } from '../lib/session/prompt.js';
 import { linkPath, linkUrl, relativeToCwd } from '../lib/session/render.js';
 import { linearIssueUrl } from '../lib/session/linear.js';
-import { extractTodoProgress } from '../lib/session/state.js';
+import { extractTodoProgress, WORKTREE_RE } from '../lib/session/state.js';
 import { renderMarkdown } from '../lib/markdown.js';
 import { itemPicker } from '../lib/picker.js';
 import { classifyFileChanges, changeCounts, toolHistogram, detectTestResult } from '../lib/session/digest.js';
@@ -408,7 +408,7 @@ function formatCompactPreview(events, session) {
  * Prefer `session.dirsTouched` when the parser teammate has populated it;
  * otherwise derive from file-change + tool paths already available here.
  */
-function directoriesTouched(session, events, changes) {
+export function directoriesTouched(session, events, changes) {
     const fromMeta = session.dirsTouched;
     if (Array.isArray(fromMeta) && fromMeta.length > 0) {
         return fromMeta
@@ -437,19 +437,73 @@ function directoriesTouched(session, events, changes) {
         .map(([d]) => d)
         .slice(0, DIRS_TOUCHED_MAX);
 }
+/**
+ * Claude names its per-project transcript store `~/.claude/projects/<slug>`, where
+ * `<slug>` is the cwd with every `/` AND `.` replaced by `-` — so `/Users/me/app`
+ * → `-Users-me-app` and `.agents/worktrees/x` → `--agents-worktrees-x`. That slug
+ * leaks into transcript paths as a leading segment (`<slug>/<session-id>/…`).
+ *
+ * The encoding is LOSSY and irreversible (`-`, `/`, and `.` all collapse to `-`),
+ * so we never try to decode it back to a path. Instead we ENCODE the comparison
+ * targets (cwd, the worktree marker) into the same slug space and match there. See
+ * {@link relativizeDir}. `encodeClaudeSlug` mirrors Claude's own transform.
+ */
+function encodeClaudeSlug(absPath) {
+    return absPath.replace(/[/.]/g, '-');
+}
+/** The `.agents/worktrees/<name>` marker, Claude-slug-encoded (`/.` → `--`). */
+const SLUG_WORKTREE_RE = /--agents-worktrees-(.+)$/;
 /** Relativize a file path to its parent dir, short enough for one preview line. */
-function relativizeDir(filePath, cwd) {
+export function relativizeDir(filePath, cwd) {
     const norm = filePath.replace(/\\/g, '/');
     if (!norm || norm.includes('node_modules') || norm.includes('/.git/') || norm.includes('/plans/')) {
         return undefined;
     }
     let dir = path.posix.dirname(norm);
+    // Claude project-slug form: a leading `-`-segment (`-home-me-…`) that carries
+    // the cwd, lossily encoded. Handle it in SLUG SPACE — never lossy-decode to a
+    // fake path. The slug is the first path segment; any real `/`-subdirs after it
+    // are Claude's internal storage (`<session-id>/scratchpad|tasks`), not code.
+    if (dir.startsWith('-')) {
+        const slash = dir.indexOf('/');
+        const slug = slash === -1 ? dir : dir.slice(0, slash);
+        // CWD FIRST: if the slug is (or is under) this session's own cwd, the leaked
+        // path is Claude's internal projects-storage scratch (`<id>/scratchpad`) —
+        // not a meaningful code dir — so drop it like node_modules. Precedence over
+        // the worktree collapse so a session editing its OWN worktree isn't relabeled.
+        if (cwd) {
+            const cwdSlug = encodeClaudeSlug(cwd.replace(/\\/g, '/').replace(/\/$/, ''));
+            if (slug === cwdSlug || slug.startsWith(cwdSlug + '-'))
+                return undefined;
+        }
+        // Only a DIFFERENT worktree than cwd reaches here: a worktree encodes its
+        // `/.agents/worktrees/<name>` marker as `--agents-worktrees-<name>`, so
+        // collapse to the worktree name to disambiguate. (The name may contain `-`;
+        // we can't losslessly re-split it, so show the whole encoded remainder.)
+        const wtSlug = slug.match(SLUG_WORKTREE_RE);
+        if (wtSlug)
+            return `⧉ ${wtSlug[1]}`;
+        // An unattributable slug: don't invent a `/`-joined fake path. Show only the
+        // trailing `-`-group as a minimal, honest token.
+        const segs = slug.split('-').filter(Boolean);
+        return segs.length ? segs[segs.length - 1] : undefined;
+    }
+    // CWD FIRST for real paths too: strip the session-cwd prefix so a session
+    // editing its OWN worktree renders the concise relative remainder (`src/lib`),
+    // not the longer `⧉ <slug>/…` collapse.
     if (cwd) {
         const base = cwd.replace(/\\/g, '/').replace(/\/$/, '');
         if (dir === base)
             return '.';
         if (dir.startsWith(base + '/'))
-            dir = dir.slice(base.length + 1);
+            return dir.slice(base.length + 1);
+    }
+    // No cwd match. If the dir is in a (different) git worktree, collapse to the
+    // worktree NAME + in-worktree remainder to disambiguate; else home→`~` + trim.
+    const wt = dir.match(WORKTREE_RE);
+    if (wt) {
+        const after = dir.slice(dir.indexOf(wt[0]) + wt[0].length).replace(/^\//, '');
+        return after ? `⧉ ${wt[1]}/${after}` : `⧉ ${wt[1]}`;
     }
     // Collapse home prefix.
     const home = (process.env.HOME || '').replace(/\\/g, '/');

package/dist/commands/sessions.d.ts

@@ -1,6 +1,7 @@
 import type { Command } from 'commander';
 import type { SessionAgentId, SessionMeta, ViewMode } from '../lib/session/types.js';
 import { type ActiveSession } from '../lib/session/active.js';
+import { gatherRemoteList, runOnPeer } from '../lib/session/remote-list.js';
 import { type PickedSession } from './sessions-picker.js';
 /**
  * Strip terminal/harness noise from a preview so the column stays a single line
@@ -150,6 +151,25 @@ export declare function shouldIncludeLocal(hosts: string[] | undefined, self: st
  * Exported for unit testing.
  */
 export declare function remoteHostsToDial(hosts: string[] | undefined, self: string): string[] | undefined;
+/**
+ * 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`
+ * 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.
+ *
+ * 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
+ * sessions are live (it used to call the local-only `getActiveSessions()` directly
+ * and silently hid every remote session).
+ */
+export declare function gatherActiveSessions(opts?: {
+    local?: boolean;
+    hosts?: string[];
+}): Promise<{
+    sessions: ActiveSession[];
+    remoteDeviceCount: number;
+}>;
 /**
  * Group key for the overview: prefer the indexed project name; else fold the cwd
  * to its repo — a worktree (`.../<repo>/.agents/worktrees/<slug>`) folds to the
@@ -203,6 +223,13 @@ export interface PickerColumns {
     machineWidth?: number;
     /** Render the ticket/PR column (only when at least one row carries a ref). */
     showTicket?: boolean;
+    /**
+     * Render the host-program column — which terminal/editor the session is running
+     * in (`ghostty`, `codium`, `tmux→ghostty`, …). Live-only: it comes from the
+     * active-session scan, so it is set by the running-filtered browser and stays
+     * off for a plain transcript listing, where no row has a host.
+     */
+    showHost?: boolean;
     /**
      * Cells the picker prepends before each row: 2 for the single-select cursor
      * ('> '), 6 for the multi-select cursor + checkbox ('> [x] '). Reserved from
@@ -223,13 +250,30 @@ export declare function machineLabeler(machines: string[]): (m: string) => strin
  * than one box, the ticket column only when some row carries a PR/ticket ref.
  */
 export declare function pickerColumnsFor(sessions: SessionMeta[]): PickerColumns;
-export declare function formatPickerLabel(s: SessionMeta, query: string, cols?: PickerColumns, ssh?: SshOriginTag): string;
+/**
+ * Which program a live session is running in, for the picker's host column: the
+ * immediate host app (`codium`, `ghostty`, `tmux`, `iterm`, …) and — when a tmux
+ * session is currently being watched through a different app — the app it is
+ * viewed in, as `tmux→ghostty`. A tmux session with no attached client stays a
+ * bare `tmux`, which is exactly "running detached". Empty when the session has no
+ * resolvable host (cloud rows, an unreadable process env).
+ */
+export declare function liveHostLabel(a: ActiveSession | undefined): string;
+export declare function formatPickerLabel(s: SessionMeta, query: string, cols?: PickerColumns, ssh?: SshOriginTag, host?: string): string;
 /**
  * Pick a hint to show above the picker. Deterministic (keys off the pool size)
  * so it stays fixed across the picker's re-renders within a single run.
  */
 export declare function formatPickerTip(sessions: SessionMeta[]): string;
 export declare function pickSessionInteractive(sessions: SessionMeta[], message?: string, initialSearch?: string, hiddenCount?: number, enterHint?: string): Promise<PickedSession | null>;
+/**
+ * Row-id prefix for a live session whose agent has not reported a session id yet
+ * (a booting harness, a queued teammate). The browser lists these so nothing live
+ * is hidden, but they address no transcript — {@link isIdlessLiveRow} is what the
+ * pick handler checks before trying to read or resume one.
+ */
+export declare const LIVE_ROW_PREFIX = "live:";
+export declare function isIdlessLiveRow(s: SessionMeta): boolean;
 export declare function handlePickedSession(picked: PickedSession): Promise<void>;
 /**
  * Resume a session in the current terminal — a foreground takeover of this
@@ -285,6 +329,56 @@ export interface SessionQueryResolution {
 export declare function resolveSessionQuery(pool: SessionMeta[], query: string): SessionQueryResolution;
 /** Filter and rank sessions by a multi-term search query across metadata and content. */
 export declare function filterSessionsByQuery(sessions: SessionMeta[], query: string | undefined): SessionMeta[];
+/**
+ * Whether a missed local id lookup should widen to a cross-machine sweep.
+ *
+ * Gate (all must hold):
+ *   - the query is id-shaped (`looksLikeSessionId`) — only an identifier resolves
+ *     across the fleet; a search phrase never does.
+ *   - not `--local` — the caller opted out of cross-machine lookup (deterministic
+ *     local behavior for scripts, RUSH-2024 acceptance: "--local still restricts").
+ *   - `AGENTS_SESSIONS_LOCAL` is unset — we are not ourselves a peer answering a
+ *     parent's sweep, so a locate can never recurse (RUSH-2024: avoid double-fan-out).
+ *
+ * Pure + exported so the gate is unit-tested without driving discovery / SSH.
+ */
+export declare function shouldFanOutForId(query: string, local: boolean | undefined): boolean;
+/** Injectable SSH/peer boundary so the fleet-resolve logic is unit-testable
+ * without a live tailnet. Production wires these to the real remote-list infra. */
+export interface FleetResolveDeps {
+    gatherRemoteList: typeof gatherRemoteList;
+    runOnPeer: typeof runOnPeer;
+}
+/** One distinct machine that reported the id, plus its winning row. */
+interface FleetHit {
+    machine: string;
+    session: SessionMeta;
+}
+/** Group a fleet sweep's rows to the DISTINCT machines that hold the id. Each
+ * peer answered `sessions <id> --json --local`, which (post-fix) id-resolves and
+ * so returns the matching row(s); a peer with a synced MIRROR of the same id can
+ * emit more than one row, so we keep the first per machine. Rows the peer somehow
+ * returned that do NOT match the id (defensive against version skew) are dropped
+ * so a stray content hit can never masquerade as an exact resolution. */
+export declare function fleetHitsById(rows: SessionMeta[], id: string): FleetHit[];
+/**
+ * Locate a full session id across the online fleet and render it from the machine
+ * that holds it. The local disk already missed; this fans `sessions <id> --json
+ * --all` out to every registered online peer (or the explicit `hosts` set),
+ * groups the rows to distinct machines, then:
+ *
+ *   - exactly one machine  → delegate rendering to that peer via `runOnPeer`
+ *     (its transcript and agent binary live there — a local `--host` hop would
+ *     re-discover locally and dead-end), returning `'rendered'`.
+ *   - more than one machine → print the conflict with machine labels so the user
+ *     can disambiguate with `--device <host>`, returning `'conflict'`.
+ *   - none                 → `'not-found'`, letting the caller print the local
+ *     "no session on this machine" message.
+ *
+ * No fuzzy/content fallback: the sweep forwards a UUID, each peer id-resolves it,
+ * and `fleetHitsById` drops anything that isn't an exact id match.
+ */
+export declare function resolveSessionAcrossFleet(id: string, mode: ViewMode, hosts?: string[], deps?: FleetResolveDeps): Promise<'rendered' | 'conflict' | 'not-found'>;
 /** Register the `agents sessions` command with all its options and help text. */
 export declare function registerSessionsCommands(program: Command): void;
 export {};