@phnx-labs/agents-cli 1.20.76 → 1.20.78

package/dist/commands/sessions-picker.js

@@ -6,12 +6,14 @@
  * response) and delegates to the generic `itemPicker` for the interactive UI.
  */
 import fs from 'node:fs';
+import path from 'node:path';
 import chalk from 'chalk';
 import { truncate, humanDuration } from '../lib/format.js';
 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, 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';
@@ -23,6 +25,32 @@ import { classifyFileChanges, changeCounts, toolHistogram, detectTestResult } fr
 function remoteMachineOf(session) {
     return session._remote ? session.machine : undefined;
 }
+/**
+ * Compact checklist tally for list rows and previews (RUSH-2045).
+ * Example: `✓6/8 · A5 wiring runner`. Empty string when there is no list.
+ * Consumes `SessionMeta.todos` / `ActiveSession.todos` as populated by the
+ * state engine — does not re-parse transcripts.
+ */
+export function formatTodoCompact(todos) {
+    if (!todos || !Number.isFinite(todos.total) || todos.total < 1)
+        return '';
+    const done = Number.isFinite(todos.done) ? Math.max(0, todos.done) : 0;
+    const tally = `✓${done}/${todos.total}`;
+    const step = todos.activeForm?.replace(/\s+/g, ' ').trim();
+    return step ? `${tally} · ${step}` : tally;
+}
+/**
+ * Best-effort GitHub repo URL from a checkout path shaped like
+ * `…/github.com/<owner>/<repo>/…`. Used to make the project name clickable
+ * when no Linear project URL is available.
+ */
+export function githubRepoUrlFromCwd(cwd) {
+    if (!cwd)
+        return undefined;
+    const norm = cwd.replace(/\\/g, '/');
+    const m = norm.match(/\/github\.com\/([^/]+\/[^/]+)/);
+    return m ? `https://github.com/${m[1]}` : undefined;
+}
 /**
  * SessionMeta originates in discover.ts (gitBranch, cwd, label, etc. read from
  * untrusted session files). parseSession sanitizes event payloads at its
@@ -31,6 +59,17 @@ function remoteMachineOf(session) {
  */
 function sanitizeMeta(s) {
     const clean = (v) => (v == null ? v : sanitizeForTerminal(v));
+    const todos = s.todos
+        ? {
+            ...s.todos,
+            activeForm: clean(s.todos.activeForm),
+            items: s.todos.items.map((it) => ({
+                ...it,
+                content: sanitizeForTerminal(it.content),
+                activeForm: clean(it.activeForm),
+            })),
+        }
+        : s.todos;
     return {
         ...s,
         id: sanitizeForTerminal(s.id),
@@ -45,6 +84,7 @@ function sanitizeMeta(s) {
         label: clean(s.label),
         ticketId: clean(s.ticketId),
         prUrl: clean(s.prUrl),
+        todos,
     };
 }
 const previewCache = new Map();
@@ -62,7 +102,8 @@ export function buildPreview(session) {
     if (remote) {
         const note = '  ' + chalk.gray(`on `) + chalk.bold.white(remote)
             + chalk.gray(` — enter to resume there, or space then enter to read it over SSH`);
-        const output = [formatHeader(safe, []), '', note].join('\n');
+        const metaBody = formatMetaOnlyBody(safe);
+        const output = [formatHeader(safe, []), '', note, metaBody].filter(Boolean).join('\n');
         previewCache.set(cacheKey, output);
         return output;
     }
@@ -70,7 +111,8 @@ export function buildPreview(session) {
     // entry (e.g. `sessions go`). Show the header + a clean note, not a parse error.
     if (!session.filePath || !fs.existsSync(session.filePath)) {
         const note = '  ' + chalk.gray('Live session — full transcript not indexed here.');
-        const output = [formatHeader(safe, []), '', note].filter(Boolean).join('\n');
+        const metaBody = formatMetaOnlyBody(safe);
+        const output = [formatHeader(safe, []), '', note, metaBody].filter(Boolean).join('\n');
         previewCache.set(cacheKey, output);
         return output;
     }
@@ -99,19 +141,27 @@ function formatHeader(session, events) {
     const { startedAgo, duration } = extractTiming(events);
     const totalMessages = session.messageCount ?? countMessages(events);
     const totalTokens = session.tokenCount;
-    // Line 1: Agent v version · model · account
+    // Line 1: Agent v version · shortId · model · account
     const line1 = [];
     line1.push(chalk.gray(`${displayAgent(session.agent)}${session.version ? ` v${session.version}` : ''}`));
+    if (session.shortId)
+        line1.push(chalk.dim(session.shortId));
     if (model)
         line1.push(chalk.bold.white(model));
     if (session.account)
         line1.push(chalk.gray(session.account));
-    // Line 2: cwd · branch · started X ago · lasted Y
+    // Line 2: cwd · project · branch · started X ago · lasted Y
+    // Project is clickable: Linear issue URL is for tickets (line 4); for the
+    // project name prefer a GitHub repo URL derived from the checkout path.
     const line2 = [];
     if (session.cwd) {
         const label = relativeToCwd(session.cwd);
         line2.push(chalk.bold.white(linkPath(session.cwd, label)));
     }
+    if (session.project) {
+        const repoUrl = githubRepoUrlFromCwd(session.cwd);
+        line2.push(chalk.cyan(repoUrl ? linkUrl(repoUrl, session.project) : session.project));
+    }
     if (session.gitBranch)
         line2.push(chalk.cyan(session.gitBranch));
     if (startedAgo)
@@ -128,7 +178,10 @@ function formatHeader(session, events) {
     }
     if (session.label)
         line3.push(chalk.white(session.label));
-    line3.push(chalk.gray(linkPath(session.filePath, session.id)));
+    if (session.filePath)
+        line3.push(chalk.gray(linkPath(session.filePath, session.id)));
+    else
+        line3.push(chalk.gray(session.id));
     // Line 4: ticket + PR — clickable when a URL is resolvable (OSC 8 hyperlink),
     // plain text otherwise. Only rendered when the session carries either.
     const line4 = [];
@@ -147,6 +200,24 @@ function formatHeader(session, events) {
         ...(line4.length ? [line4.join(DOT)] : []),
     ].join('\n');
 }
+/**
+ * Body lines available from SessionMeta alone (no transcript parse) — used for
+ * remote / unindexed sessions so checklist progress still surfaces when the
+ * parser teammate (or a prior scan) has populated `session.todos`.
+ */
+function formatMetaOnlyBody(session) {
+    const lines = [];
+    if (session.topic) {
+        lines.push(chalk.cyan('Prompt: ') + chalk.white(truncate(session.topic.trim(), (process.stdout.columns || 80) - 12)));
+    }
+    const compact = formatTodoCompact(session.todos);
+    if (compact) {
+        lines.push(chalk.cyan('Todos: ') + chalk.white(compact));
+    }
+    if (lines.length === 0)
+        return '';
+    return lines.map(l => '  ' + l).join('\n');
+}
 function extractModel(events) {
     for (let i = events.length - 1; i >= 0; i--) {
         const m = events[i].model;
@@ -204,6 +275,7 @@ function stripTags(text) {
 const LAST_RESPONSE_MAX_LINES = 15;
 const LAST_RESPONSE_MAX_LINES_WITH_TODOS = 8;
 const TODOS_MAX_ITEMS = 5;
+const DIRS_TOUCHED_MAX = 5;
 function formatCompactPreview(events, session) {
     let firstUser = '';
     let lastAssistant = '';
@@ -211,7 +283,8 @@ function formatCompactPreview(events, session) {
     const toolCounts = {};
     let toolCalls = 0;
     let planFile = '';
-    let latestTodos = null;
+    /** Latest checklist from the transcript (Claude TodoWrite / Codex update_plan). */
+    let latestTodos;
     for (const event of events) {
         if (event.type === 'message') {
             if (event.role === 'user' && !firstUser && event.content) {
@@ -232,25 +305,53 @@ function formatCompactPreview(events, session) {
             if (!planFile && p && /\/plans\/[^/]+\.md$/.test(p)) {
                 planFile = p;
             }
-            if (tool === 'TodoWrite' && Array.isArray(event.args?.todos)) {
-                latestTodos = event.args.todos;
+            // Claude TodoWrite (`todos`) and Codex update_plan (`plan`) — same source as
+            // extractTodoProgress in the state engine. Prefer the most recent write.
+            if (tool === 'TodoWrite' || tool === 'update_plan') {
+                const progress = extractTodoProgress(event.args);
+                if (progress)
+                    latestTodos = progress;
             }
             if (tool)
                 toolCounts[tool] = (toolCounts[tool] ?? 0) + 1;
             toolCalls++;
         }
     }
+    // Prefer the transcript-derived list when we just re-parsed the file (freshest
+    // checklist write); fall back to SessionMeta.todos for rows where the scan/
+    // fan-out attached progress but the event stream has no TodoWrite yet.
+    const todos = latestTodos ?? session.todos;
     // Digest signals folded into the preview: change lifecycle, tool mix, tests.
     const changes = classifyFileChanges(events);
     const chg = changeCounts(changes);
     const lines = [];
     const termWidth = process.stdout.columns || 80;
+    // Originating user prompt (first non-system user turn).
     if (firstUser) {
         const first = extractSessionTopic(firstUser) || cleanSessionPrompt(firstUser).split('\n').find(l => l.trim()) || '';
         if (first) {
             lines.push(chalk.cyan('Prompt: ') + chalk.white(truncate(first.trim(), termWidth - 12)));
         }
     }
+    else if (session.topic) {
+        lines.push(chalk.cyan('Prompt: ') + chalk.white(truncate(session.topic.trim(), termWidth - 12)));
+    }
+    // Compact checklist: ✓done/total · current step (RUSH-2045).
+    const compact = formatTodoCompact(todos);
+    if (compact) {
+        lines.push(chalk.cyan('Todos: ') + chalk.white(compact));
+    }
+    const todosRendered = todos?.items?.length ? renderTodos(todos.items, termWidth) : [];
+    if (todosRendered.length > 0) {
+        for (const l of todosRendered)
+            lines.push('  ' + l);
+    }
+    // Recent activity = directories touched (not raw tool calls). Prefer a
+    // parser-supplied dirsTouched when present; else derive from event paths.
+    const dirs = directoriesTouched(session, events, changes);
+    if (dirs.length) {
+        lines.push(chalk.cyan('Dirs:    ') + chalk.white(dirs.join(chalk.gray(' · '))));
+    }
     const activity = [];
     const changed = chg.created + chg.modified + chg.deleted;
     if (changed) {
@@ -287,14 +388,8 @@ function formatCompactPreview(events, session) {
         const basename = planFile.split('/').pop() || planFile;
         lines.push(chalk.cyan('Plan: ') + chalk.white(linkPath(planFile, basename)));
     }
-    const todosRendered = latestTodos ? renderTodos(latestTodos, termWidth) : [];
-    if (todosRendered.length > 0) {
-        lines.push(chalk.cyan('Todos:'));
-        for (const l of todosRendered)
-            lines.push('  ' + l);
-    }
     if (lastAssistant) {
-        const maxLines = todosRendered.length > 0 ? LAST_RESPONSE_MAX_LINES_WITH_TODOS : LAST_RESPONSE_MAX_LINES;
+        const maxLines = todosRendered.length > 0 || compact ? LAST_RESPONSE_MAX_LINES_WITH_TODOS : LAST_RESPONSE_MAX_LINES;
         const rendered = renderLastResponse(lastAssistant, maxLines);
         if (rendered.length > 0) {
             lines.push('');
@@ -308,6 +403,118 @@ function formatCompactPreview(events, session) {
     }
     return lines.map(l => '  ' + l).join('\n');
 }
+/**
+ * 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 function directoriesTouched(session, events, changes) {
+    const fromMeta = session.dirsTouched;
+    if (Array.isArray(fromMeta) && fromMeta.length > 0) {
+        return fromMeta
+            .map((d) => sanitizeForTerminal(String(d).trim()))
+            .filter(Boolean)
+            .slice(0, DIRS_TOUCHED_MAX);
+    }
+    const counts = new Map();
+    const bump = (raw) => {
+        const dir = relativizeDir(raw, session.cwd);
+        if (!dir)
+            return;
+        counts.set(dir, (counts.get(dir) ?? 0) + 1);
+    };
+    for (const ch of changes)
+        bump(ch.path);
+    for (const event of events) {
+        if (event.type !== 'tool_use' || event._local)
+            continue;
+        const p = event.path || event.args?.file_path || event.args?.path || '';
+        if (p)
+            bump(p);
+    }
+    return [...counts.entries()]
+        .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+        .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. */
+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 + '/'))
+            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, '/');
+    if (home && dir.startsWith(home + '/'))
+        dir = '~' + dir.slice(home.length);
+    // Drop ultra-deep absolute noise; keep last 3 segments.
+    const parts = dir.split('/').filter(Boolean);
+    if (parts.length > 3 && dir.startsWith('/'))
+        dir = parts.slice(-3).join('/');
+    return dir || undefined;
+}
 function renderLastResponse(content, maxLines = LAST_RESPONSE_MAX_LINES) {
     const cleaned = stripTags(content).trim();
     if (!cleaned)

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
@@ -9,6 +10,18 @@ import { type PickedSession } from './sessions-picker.js';
  * a captured transcript tail. Collapses runs of whitespace.
  */
 export declare function cleanPreview(text: string): string;
+/**
+ * Identity + checklist + live snippet for an --active / cross-machine row.
+ * Surfaces agent-adjacent identity the flat table already has (label, project)
+ * with a clickable project when a GitHub URL is resolvable, then the checklist
+ * tally and the latest-turn snippet.
+ *
+ * Free-text fields are cleaned individually; OSC 8 hyperlinks are applied
+ * *after* cleaning so `cleanPreview` does not strip the clickable targets
+ * (RUSH-2045 review). Ticket is clickable via {@link signalBadges}, not here,
+ * so the id is not printed twice.
+ */
+export declare function formatActiveRowDescription(s: ActiveSession): string;
 /**
  * Index live sessions by their full session UUID so a historical `SessionMeta`
  * row (`meta.id`) can be matched to the session that is still running now.
@@ -138,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
@@ -175,6 +207,12 @@ export declare function renderSessionLog(session: SessionMeta, mode?: ViewMode):
  */
 export declare function renderSessionLogJson(session: SessionMeta): Promise<void>;
 /** Column-visibility flags for the picker row, computed once over the whole pool. */
+/** The SSH-launch origin for a picker row, resolved from the live session's
+ * provenance (transport 'ssh'). `device` is set when the client IP matched a
+ * registered device; absent for an unresolved IP (renders a bare `ssh`). */
+export interface SshOriginTag {
+    device?: string;
+}
 export interface PickerColumns {
     /** Render the machine column (only when the pool spans more than one machine). */
     showMachine?: boolean;
@@ -185,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
@@ -205,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): 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
@@ -259,13 +321,64 @@ export interface SessionQueryResolution {
 /**
  * The single entry point for turning a `sessions <query>` argument into rows.
  *
- * A complete session id resolves by id alone. Anything else keeps the existing
- * ladder: id lookup first (so a short id still wins), then the ranked
- * metadata+content search.
+ * An id-shaped query — a complete id OR a hex short-id/prefix (looksLikeSessionId)
+ * — resolves by id alone, through the index, and never falls back to content
+ * search (a bare id must not surface every transcript that merely mentions it).
+ * A genuine search phrase keeps the ranked metadata+content search.
  */
 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 {};