@phnx-labs/agents-cli 1.22.35 → 1.22.37

package/dist/commands/sessions-migrate.js

@@ -37,6 +37,7 @@ import { injectIntoTerminal } from '../lib/terminal/index.js';
 import { iLoginShell } from '../lib/terminal/shell.js';
 import { shellQuote as quoteArg } from '../lib/terminal/quote.js';
 import { killSession } from '../lib/tmux/session.js';
+import { getDefaultSocketPath } from '../lib/tmux/paths.js';
 import { listAllHosts, resolveHost } from '../lib/hosts/registry.js';
 import { sshTargetFor } from '../lib/hosts/types.js';
 import { readyProbe, bootstrapAgentsCli, viewHasAgent } from '../lib/hosts/ready.js';
@@ -406,6 +407,44 @@ function prepareEphemeralCwd(sshTarget, source, branch) {
     }
     return dir;
 }
+/**
+ * Pure. The remote shell commands that create the target's tmux session on the
+ * SAME socket its reaper queries, and that probe its liveness afterward.
+ *
+ * `homeRelSocketPath` is `getDefaultSocketPath()` expressed relative to the
+ * LOCAL home dir (`path.relative(os.homedir(), getDefaultSocketPath())`) — a
+ * portable suffix, not a resolved absolute path, because the local and remote
+ * HOME can differ (different user, different OS). It is spliced in after a
+ * literal, unquoted `$HOME/` so the REMOTE shell resolves it; `$HOME` MUST
+ * NEVER be resolved locally (see AGENTS.md's remote-path guidance).
+ *
+ * Extracted as a pure function so the "does the migrated session land on the
+ * agents socket, not tmux's bare default socket" invariant is unit-testable
+ * without an SSH round-trip (RUSH-2521 review — a bare `tmux` here made the
+ * migrated agent's helpers invisible to `readAllPaneOwners`, so the reaper's
+ * next tick killed the still-live, just-migrated agent as `tmux-session-gone`).
+ */
+export function buildMigrateResumeCommands(opts) {
+    const socketDirRelToHome = path.dirname(opts.homeRelSocketPath);
+    const socketFlag = `-S "$HOME/${opts.homeRelSocketPath}"`;
+    const argv = ['set-option', '-g', 'remain-on-exit', 'on', ';', 'new-session', '-d', '-s', opts.sessionName];
+    if (opts.cwd && opts.cwd !== '~')
+        argv.push('-c', opts.cwd);
+    argv.push(opts.inner);
+    // Mirror createSession's second half: keep remain-on-exit on THIS pane (the
+    // liveness probe below reads `pane_dead`), then put the server-wide default
+    // back to off. Leaving `-g on` set made every later pane on the target — user
+    // splits included — retain a corpse when its command finished.
+    argv.push(';', 'set-option', '-t', opts.sessionName, '-p', 'remain-on-exit', 'on');
+    argv.push(';', 'set-option', '-g', 'remain-on-exit', 'off');
+    // Unlike tmux's own scratch dir (auto-created under /tmp), the agents socket's
+    // parent may not exist yet on a fresh worker or ephemeral box that never ran a
+    // tmux-backed `agents` command — `mkdir -p` it before tmux tries to bind there.
+    const launchCmd = `mkdir -p "$HOME/${socketDirRelToHome}" && tmux ${socketFlag} ` + argv.map(shellQuote).join(' ');
+    const q = shellQuote(opts.sessionName);
+    const probeCmd = `sleep 3; tmux ${socketFlag} has-session -t ${q} 2>/dev/null || exit 3; test "$(tmux ${socketFlag} list-panes -t ${q} -F '#{pane_dead}' 2>/dev/null | head -n1)" = 0 || exit 4`;
+    return { launchCmd, probeCmd, socketFlag };
+}
 /**
  * Resume the session on the target through the SAME host path as
  * `sessions resume --host` (tmux backend). Returns true when the resume launched.
@@ -426,14 +465,18 @@ async function resumeOnTarget(sshTarget, source, remoteCwd, mode) {
     // carries spaces or backticks (the rehydrate prompt) reaches the agent as one
     // clean argument — an unquoted join would let the target shell split it and
     // run its backticks.
+    //
+    // The pane exports AGENT_TMUX_SESSION_NAME the way a local `createSession`
+    // pane does, so the target's reaper can attribute the helpers this agent
+    // spawns and collect them when it exits (RUSH-2521, `lib/tmux/orphan-reap.ts`)
+    // — see {@link buildMigrateResumeCommands} for why the session MUST land on
+    // the agents socket rather than tmux's bare default socket.
     const sessionName = `migrate-${source.shortId}`;
-    const inner = iLoginShell(`exec ${command.map(quoteArg).join(' ')}`);
-    const argv = ['tmux', 'set-option', '-g', 'remain-on-exit', 'on', ';', 'new-session', '-d', '-s', sessionName];
+    const homeRelSocketPath = path.relative(os.homedir(), getDefaultSocketPath());
+    const inner = iLoginShell(`export AGENT_TMUX_SESSION_NAME=${sessionName}; exec ${command.map(quoteArg).join(' ')}`);
     const cwd = remoteCwd ?? source.cwd;
-    if (cwd && cwd !== '~')
-        argv.push('-c', cwd);
-    argv.push(inner);
-    const launch = sshExec(sshTarget, argv.map(shellQuote).join(' '), { timeoutMs: 60000 });
+    const { launchCmd, probeCmd } = buildMigrateResumeCommands({ sessionName, homeRelSocketPath, inner, cwd });
+    const launch = sshExec(sshTarget, launchCmd, { timeoutMs: 60000 });
     if (launch.code !== 0) {
         console.log(chalk.red(`  Resume on ${sshTarget} failed: ${launch.stderr.trim().split('\n').pop() || `tmux exited ${launch.code}`}`));
         return false;
@@ -441,9 +484,7 @@ async function resumeOnTarget(sshTarget, source, remoteCwd, mode) {
     // Liveness gate for the invariant: give the agent a moment to boot, then require
     // the pane to be ALIVE (not merely the session to exist) before the caller may
     // stop the source. An agent that dies on launch → we refuse to move.
-    const q = shellQuote(sessionName);
-    const probe = `sleep 3; tmux has-session -t ${q} 2>/dev/null || exit 3; test "$(tmux list-panes -t ${q} -F '#{pane_dead}' 2>/dev/null | head -n1)" = 0 || exit 4`;
-    const check = sshExec(sshTarget, probe, { timeoutMs: 30000 });
+    const check = sshExec(sshTarget, probeCmd, { timeoutMs: 30000 });
     if (check.code !== 0) {
         const why = check.code === 4 ? 'the agent exited immediately on the target'
             : check.code === 3 ? 'the session did not start'

package/dist/commands/sessions-picker.js

@@ -20,7 +20,7 @@ import { itemPicker } from '../lib/picker.js';
 import { createMemoryCache } from '../lib/memory-cache.js';
 import { classifyFileChanges, changeCounts, toolHistogram, detectTestResult } from '../lib/session/digest.js';
 import { extractArtifacts, extractHooks, extractLinks, extractRepos, extractSkills } from '../lib/session/highlights.js';
-import { getSessionPlugins, readSessionPreviewCache, writeSessionPreviewCache } from '../lib/session/db.js';
+import { getSessionPlugins, readSessionPreviewCache, writeSessionPreviewCache, readSessionContent, readArchivedSessionPreview } from '../lib/session/db.js';
 /** A session whose transcript FILE is on another machine (folded in over the
  * live cross-machine fan-out): its `filePath` is on that peer's disk, so the
  * preview can't parse it locally — it shows metadata + a "resume there" note
@@ -130,8 +130,17 @@ export function clearPreviewMemoryCacheForTest() {
     previewCache.clear();
 }
 export function loadSessionPreviewDigest(session) {
-    if (!session.filePath || !fs.existsSync(session.filePath))
+    if (!session.filePath || !fs.existsSync(session.filePath)) {
+        // File gone, but an archived session (RUSH-2436) keeps its last-computed
+        // digest in the DB — serve that so the picker preview still shows its turns
+        // instead of a bare "not indexed here" note. No events to replay.
+        const archived = readArchivedSessionPreview(session.id);
+        if (archived) {
+            archived.plugins = getSessionPlugins(session.id);
+            return { digest: archived, events: [] };
+        }
         return { events: [] };
+    }
     const safe = sanitizeMeta(session);
     let events = [];
     let sourceStamp;
@@ -182,9 +191,19 @@ export function buildPreview(session) {
         previewCache.set(cacheKey, output);
         return output;
     }
-    // No transcript on disk — a live session not indexed locally, or a synthesized
-    // entry (e.g. `sessions go`). Show the header + a clean note, not a parse error.
+    // No transcript on disk — either an archived session (file gone, user turns
+    // still in the DB — RUSH-2436), a live session not indexed locally, or a
+    // synthesized entry (e.g. `sessions go`). Show the header + a clean note.
     if (!session.filePath || !fs.existsSync(session.filePath)) {
+        const archivedContent = readSessionContent(session.id);
+        if (archivedContent && archivedContent.trim() !== '') {
+            const note = '  ' + chalk.yellow('archived — transcript file removed; served from the local DB');
+            const { digest } = loadSessionPreviewDigest(session);
+            const body = digest ? formatCompactPreview(digest, safe) : formatMetaOnlyBody(safe);
+            const output = [formatHeader(safe, []), '', note, body].filter(Boolean).join('\n');
+            previewCache.set(cacheKey, output);
+            return output;
+        }
         const note = '  ' + chalk.gray('Live session — full transcript not indexed here.');
         const metaBody = formatMetaOnlyBody(safe);
         const output = [formatHeader(safe, []), '', note, metaBody].filter(Boolean).join('\n');

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

@@ -1,5 +1,5 @@
 import type { Command } from 'commander';
-import type { SessionMeta } from '../lib/session/types.js';
+import { type SessionMeta } from '../lib/session/types.js';
 import { type Backend, type EngineContext, type Packing } from '../lib/terminal/index.js';
 /** Opening more than this many live sessions at once asks for confirmation first. */
 export declare const CONFIRM_THRESHOLD = 5;
@@ -17,6 +17,8 @@ export interface ResumeOptions {
     /** --terminal-app: force macOS Terminal.app. Named to avoid reading as `run --terminal`. */
     terminalApp?: boolean;
     splits?: boolean;
+    attachOnly?: boolean;
+    local?: boolean;
 }
 export declare function registerSessionsResumeCommand(sessionsCmd: Command): void;
 /** IDs and tmux aliases are actions, not picker search text. Human phrases keep
@@ -28,8 +30,8 @@ export declare function resumeSelectorInPlace(selector: string): Promise<void>;
 /** Direct identities use focus as the lifecycle dispatcher: it rechecks the
  * live fleet, attaches a healthy pane, and falls through to `agents resume`
  * only when the process is no longer attachable. */
-export declare function dispatchSessionLifecycleInPlace(selector: string, hosts?: string[]): Promise<void>;
-export declare function buildSessionLifecycleArgs(selector: string, hosts?: string[]): string[];
+export declare function dispatchSessionLifecycleInPlace(selector: string, hosts?: string[], attachOnly?: boolean, local?: boolean): Promise<void>;
+export declare function buildSessionLifecycleArgs(selector: string, hosts?: string[], attachOnly?: boolean, local?: boolean): string[];
 export declare function resolveResumePacking(options: Pick<ResumeOptions, 'splits'>): Packing;
 export declare function resumeHostMismatch(session: Pick<SessionMeta, 'shortId' | 'machine'>, requestedHost: string, self?: string): string | null;
 /**

package/dist/commands/sessions-resume.js

@@ -10,6 +10,7 @@
  */
 import * as fs from 'fs';
 import chalk from 'chalk';
+import { isAgentTmuxAlias } from '../lib/session/types.js';
 import { discoverSessions } from '../lib/session/discover.js';
 import { filterTeamSessions } from '../lib/session/team-filter.js';
 import { multiItemPicker, itemPicker } from '../lib/picker.js';
@@ -42,6 +43,8 @@ export function registerSessionsResumeCommand(sessionsCmd) {
         .option('--tmux', 'Force the tmux backend')
         .option('--vscodium', 'Force the VSCodium agent-terminal backend (swarm-ext)')
         .option('--terminal-app', 'Force macOS Terminal.app (no split support — panes become tabs)')
+        .option('--local', 'Only this machine (skip the cross-host sweep)')
+        .option('--attach-only', 'With an id/alias: attach a living pane only — never resume a copy')
         .option('--splits', 'Pack two sessions side by side per tab (default: one tab per session)');
     setHelpSections(cmd, {
         examples: `
@@ -55,6 +58,9 @@ export function registerSessionsResumeCommand(sessionsCmd) {
       agents sessions resume 019fd114
       agents sessions resume ag-codex-c1f3d813
 
+      # Attach a living pane only — never resume a copy (the old go)
+      agents sessions resume 019fd114 --attach-only
+
       # Force a backend / side-by-side splits / a remote host
       agents sessions resume --ghostty
       agents sessions resume --vscodium
@@ -62,7 +68,10 @@ export function registerSessionsResumeCommand(sessionsCmd) {
       agents sessions resume --host zion --tmux
     `,
         notes: `
-      - A UUID/prefix or ag-<agent>-<suffix> alias bypasses the picker: a live pane is attached; an inactive session resumes on its owning device.
+      - This is the ONE verb for getting back in. It detects the state: a live tmux pane is attached, a headless session comes to the foreground, an ended one recovers on its owning device.
+      - A UUID/prefix or ag-<agent>-<suffix> alias bypasses the picker. A live alias attaches by name even when the session index cannot attribute it.
+      - Retired spellings still work for one release and print the replacement: sessions attach, sessions go, reconnect.
+      - Going the other way (foreground -> background) is 'agents sessions detach <id>'.
       - With no identity selector, space toggles a session, enter confirms, and tab toggles the preview pane.
       - Layout: one tab per session by default. --splits packs session pairs side by side in each tab.
       - Backend: auto-detected from the terminal you're in (iTerm / Ghostty / tmux); override with --iterm/--ghostty/--tmux/--vscodium.
@@ -82,7 +91,7 @@ async function sessionsResumeAction(query, options) {
         return;
     }
     if (query && isDirectResumeSelector(query)) {
-        await dispatchSessionLifecycleInPlace(query.trim(), options.host ? [options.host] : []);
+        await dispatchSessionLifecycleInPlace(query.trim(), options.host ? [options.host] : [], options.attachOnly === true, options.local === true);
         return;
     }
     const { agent, version } = parseAgentFilter(options.agent);
@@ -182,7 +191,15 @@ async function sessionsResumeAction(query, options) {
         console.log(chalk.yellow('Terminal.app cannot split panes — opening one tab per session instead.'));
     }
     console.log(chalk.gray(`Opening ${items.length} session${items.length === 1 ? '' : 's'} in ${where} (${packing})…`));
-    const results = await openSurfaces(items.map((it) => ({ cwd: it.cwd, command: it.command })), { backend, host: options.host, packing });
+    // agent + sessionId ride the SurfaceItem into the vscodium-agent spawn URI
+    // so the extension can set the tab chip without process-tree sniffing (#2478).
+    const results = await openSurfaces(items.map((it) => ({
+        cwd: it.cwd,
+        command: it.command,
+        agent: it.session.agent || undefined,
+        sessionId: it.session.id || undefined,
+        title: it.session.label || it.session.topic || undefined,
+    })), { backend, host: options.host, packing });
     let opened = 0;
     results.forEach((r, i) => {
         const s = items[i].session;
@@ -201,7 +218,7 @@ async function sessionsResumeAction(query, options) {
  * the existing pre-filtered picker, while an explicit identity resumes directly. */
 export function isDirectResumeSelector(query) {
     const selector = query.trim();
-    return looksLikeSessionId(selector) || /^ag-[a-z][a-z0-9-]*-[0-9a-f]{8}$/i.test(selector);
+    return looksLikeSessionId(selector) || isAgentTmuxAlias(selector);
 }
 /** Re-enter through the top-level command so fleet routing and harness policy
  * stay centralized. The child inherits this terminal for a real interactive resume. */
@@ -211,11 +228,16 @@ export async function resumeSelectorInPlace(selector) {
 /** Direct identities use focus as the lifecycle dispatcher: it rechecks the
  * live fleet, attaches a healthy pane, and falls through to `agents resume`
  * only when the process is no longer attachable. */
-export async function dispatchSessionLifecycleInPlace(selector, hosts = []) {
-    await spawnCliInPlace(buildSessionLifecycleArgs(selector, hosts));
+export async function dispatchSessionLifecycleInPlace(selector, hosts = [], attachOnly = false, local = false) {
+    await spawnCliInPlace(buildSessionLifecycleArgs(selector, hosts, attachOnly, local));
 }
-export function buildSessionLifecycleArgs(selector, hosts = []) {
-    return ['sessions', 'focus', selector, ...hosts.flatMap(host => ['--host', host])];
+export function buildSessionLifecycleArgs(selector, hosts = [], attachOnly = false, local = false) {
+    return [
+        'sessions', 'focus', selector,
+        ...hosts.flatMap(host => ['--host', host]),
+        ...(attachOnly ? ['--attach-only'] : []),
+        ...(local ? ['--local'] : []),
+    ];
 }
 function asyncExitCode(child) {
     return new Promise((resolve) => {

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

@@ -0,0 +1,2 @@
+import type { Command } from 'commander';
+export declare function registerSessionsWatchCommand(parent: Command): void;

package/dist/commands/sessions-watch.js

@@ -0,0 +1,53 @@
+import { machineId } from '../lib/machine-id.js';
+import { setHelpSections } from '../lib/help.js';
+import { watchFleetSessions, watchLocalSessions } from '../lib/session/watch.js';
+export function registerSessionsWatchCommand(parent) {
+    const command = parent.command('watch')
+        .description('Stream canonical live and recoverable session row changes as NDJSON')
+        .option('--json', 'Emit versioned NDJSON envelopes')
+        .option('--local', 'Watch only this machine');
+    setHelpSections(command, {
+        examples: `
+      # Subscribe to session changes for a long-lived UI consumer
+      agents sessions watch --json
+
+      # Subscribe only to this machine
+      agents sessions watch --json --local
+    `,
+        notes: `
+      - Each line is one versioned reset, upsert, remove, scope, or heartbeat envelope.
+      - rowKey is opaque. Order changes by streamId + sequence.
+      - An unavailable scope retains its last rows until that scope reconnects.
+    `,
+    });
+    command.action(async (_options, invoked) => {
+        const options = invoked.optsWithGlobals();
+        if (!options.json)
+            invoked.error('error: required option \'--json\' not specified');
+        const controller = new AbortController();
+        const stop = () => controller.abort();
+        const stopOnClosedConsumer = (error) => {
+            if (error.code === 'EPIPE')
+                controller.abort();
+            else {
+                process.exitCode = 1;
+                controller.abort(error);
+            }
+        };
+        process.once('SIGINT', stop);
+        process.once('SIGTERM', stop);
+        process.stdout.on('error', stopOnClosedConsumer);
+        try {
+            const emit = (event) => process.stdout.write(`${JSON.stringify(event)}\n`);
+            if (options.local)
+                await watchLocalSessions({ scope: machineId(), signal: controller.signal, emit });
+            else
+                await watchFleetSessions({ signal: controller.signal, emit });
+        }
+        finally {
+            process.off('SIGINT', stop);
+            process.off('SIGTERM', stop);
+            process.stdout.off('error', stopOnClosedConsumer);
+        }
+    });
+}

package/dist/commands/sessions.d.ts

@@ -3,8 +3,10 @@ import { type ProjectDef } from '../lib/projects.js';
 import type { SessionAgentId, SessionMeta, ViewMode } from '../lib/session/types.js';
 import { type ActiveSession } from '../lib/session/active.js';
 import { gatherRemoteList, runOnPeer } from '../lib/session/remote-list.js';
+import { type RemoteAgentsJsonParseResult } from '../lib/remote-agents-json.js';
 import { type RunMeta } from '../lib/routines.js';
 import { type PickedSession } from './sessions-picker.js';
+import { type ComputerRunRow } from '../lib/computer/sessions-list.js';
 import { type ToolSearchEnvelope, type ToolProgramCountEnvelope } from '../lib/session/tool-index.js';
 interface SessionFilterOptions {
     agent?: string;
@@ -254,6 +256,22 @@ export declare function serializeActiveSessionsForJson(sessions: ActiveSession[]
     prLink: string | null;
     viewingIn: string | null;
 }>;
+export interface SessionPickerJsonRow extends SessionMeta {
+    state: ActiveSession['status'] | 'inactive';
+    resumable: boolean;
+    unwatched: boolean;
+    viewingIn: string | null;
+    sourceDevice: string;
+    lastActivityMs: number;
+    pid: number | null;
+    recovery: {
+        command: 'agents';
+        args: string[];
+        cwd?: string;
+    } | null;
+}
+/** Canonical JSON row consumed by resume pickers and other session UIs. */
+export declare function serializeSessionPickerRows(sessions: SessionMeta[], liveSessions: ActiveSession[], self?: string): SessionPickerJsonRow[];
 /**
  * Build the (one or two) rendered lines for a single active-session row.
  * Indent is the leading whitespace (2 spaces for flat groups, 4 inside a window
@@ -332,6 +350,15 @@ export declare function groupSessionsByMachine(sessions: ActiveSession[], localM
  * correlated, so they're all kept.
  */
 export declare function dedupeByMachineSession(sessions: ActiveSession[]): ActiveSession[];
+/**
+ * Narrow a gathered live set to the machines an explicit `--host`/`--device`
+ * scope named. The gather picks which boxes to ASK; this asserts what the answer
+ * may contain, and the two are not the same question: a host-dispatched run is
+ * reported by the box that dispatched it while executing somewhere else, so
+ * `--device <dispatcher>` used to list sessions that were not running there at
+ * all (RUSH-2479). No scope → unchanged. Pure; exported for unit testing.
+ */
+export declare function filterActiveSessionsByHostScope(sessions: ActiveSession[], hosts: string[] | undefined, self: string): ActiveSession[];
 /**
  * Order a merged listing so the local machine's sessions come first, then each
  * remote machine as a contiguous block (more sessions first, then name), with
@@ -356,6 +383,14 @@ export declare function serializeSessionsJson(sessions: SessionMeta[]): string;
  * It includes only launch identity needed to route/resume. Transcript paths,
  * extracted plans, costs, and content stay on the machine that owns them. */
 export declare function serializeResolvedSessionsJson(sessions: SessionMeta[]): string;
+/** Parse one peer's computer-run array without accepting banners or partial
+ * JSON. The fan-out boundary supplies the machine name when an older peer row
+ * omitted it. */
+export declare function parseRemoteComputerSessionRows(stdout: string, machine: string): RemoteAgentsJsonParseResult<ComputerRunRow>;
+/** Collect computer history from named peers, or every automatic peer when
+ * hosts is omitted. Every peer is forced to JSON and receives the recursion
+ * guard through the shared fleet transport. */
+export declare function gatherRemoteComputerSessionRows(hosts?: string[]): Promise<ComputerRunRow[]>;
 /**
  * Whether the local machine's sessions belong in an `--active` view. Local is
  * included by default; an explicit `--host`/`--device` list scopes the view to
@@ -829,6 +864,11 @@ export type MetadataResolveOutcome = {
  * the wrong session (whichever peer replied first). Labels therefore stay
  * all-settle so a cross-machine label conflict surfaces as an ambiguity, and a
  * short-id PREFIX stays all-settle for the same reason (RUSH-2203).
+ *
+ * This is about cancelling a sweep that is still IN FLIGHT, where a peer that
+ * has not answered yet is still expected to. It is deliberately stricter than
+ * `isUniqueEnoughSelector`, which decides what to do once the sweep is OVER and
+ * a peer has definitively not answered — see SES-9a.
  */
 export declare function isDefinitiveMatch(session: SessionMeta, selector: string): boolean;
 /**
@@ -849,9 +889,20 @@ export declare function fleetCandidatesByQuery(rows: SessionMeta[], query: strin
 export declare function metadataResolveForwardedArgs(selector: string, scope: Pick<SessionFilterOptions, 'agent' | 'project'>): string[];
 /** Build the local-only peer argv for a distributed tool search. */
 export declare function toolSearchForwardedArgs(argv: string[], hosts: string[]): string[];
-/** Resolution fails closed for prefixes/keywords when a peer did not answer.
- * A full UUID is globally unique, so one exact hit is sufficient even when an
- * unrelated registered device is offline. */
+/**
+ * Whether a selector names ONE session precisely enough to resolve from the
+ * reachable fleet alone when some peer did not answer (SES-9a).
+ *
+ * Deliberately stricter than `looksLikeSessionId`, which accepts any 6+ char
+ * `[0-9a-f-]` run and so matches ordinary words (`facade`, `decade`, `beaded`).
+ * Those are keywords a user typed as a search, not identifiers, and they must
+ * keep waiting for every peer.
+ */
+export declare function isUniqueEnoughSelector(selector: string): boolean;
+/** Resolution fails closed for keywords and labels when a peer did not answer.
+ * An id-shaped selector at least `SHORT_SESSION_ID_WIDTH` hex chars wide (or a
+ * complete id) resolves from a single reachable hit even when an unrelated
+ * registered device is offline — see SES-9a for the accepted collision risk. */
 export declare function metadataResolveOutcome(localMatches: SessionMeta[], remote: {
     sessions: SessionMeta[];
     unreachable: string[];
@@ -864,6 +915,18 @@ export declare function resolveSessionMetadataValue(selector: string, scope?: {
     local?: boolean;
     hosts?: string[];
 }, deps?: Pick<FleetResolveDeps, 'gatherRemoteList'>): Promise<MetadataResolveOutcome>;
+/** Resolve one selector to indexed metadata across the fleet without reading or
+ * rendering transcript events. A peer answering the parent sweep returns every
+ * local candidate; the parent performs the one logical-session uniqueness gate.
+ * Backs `agents sessions --resolve <selector> --json`. Exported (deps already
+ * injectable) so tests can drive this real call site against a fake fan-out
+ * instead of only the pure resolver it wraps. */
+export declare function resolveSessionMetadata(selector: string, scope: {
+    agent?: string;
+    project?: string;
+    local?: boolean;
+    hosts?: string[];
+}, deps?: Pick<FleetResolveDeps, 'gatherRemoteList'>): Promise<void>;
 /**
  * Locate a full session id or short id prefix across the online fleet and render it from the machine
  * that holds it. The local disk already missed; this fans `sessions <id> --json