@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/session/recovery.js

@@ -10,9 +10,8 @@ import { formatNoHealthyAccountError, matchAccountCandidate, pickBalancedCandida
 import { collectRunCandidatesForRun } from '../accounting/account-pool-collect.js';
 import { getVersionHomePath, resolveManagedInstallation } from '../installations/store.js';
 import { readSessionContent } from './db.js';
-import { parseOpenCode, splitSessionFilePath } from './parse.js';
+import { parseOpenCode, splitSessionFilePath } from '@phnx-labs/sessions-cli/reader';
 const RESUMABLE_SESSION_AGENTS = new Set(['claude', 'codex', 'muse', 'opencode']);
-/** One capability boundary for every surface that advertises faithful Resume. */
 export function sessionAgentSupportsResume(agent) {
     return RESUMABLE_SESSION_AGENTS.has(agent);
 }
@@ -22,17 +21,14 @@ export class SessionRecoveryError extends Error {
         this.name = 'SessionRecoveryError';
     }
 }
-/** Canonical origin-device label for every recovery consumer. */
 export function sessionOriginDevice(session, self = machineId()) {
     return normalizeHost(session.machine ?? self);
 }
-/** The peer that must execute recovery, or undefined when this is the origin. */
 export function sessionRecoveryPeer(session, selfCheck = isSelfHost) {
     if (!session.machine || selfCheck(session.machine))
         return undefined;
     return normalizeHost(session.machine);
 }
-/** Whether an explicit placement names the session's origin device. */
 export function sessionRecoveryDestinationMatches(session, requestedHost, self = machineId()) {
     const requested = normalizeHost(requestedHost.split('@').pop() || requestedHost);
     return requested === sessionOriginDevice(session, self);
@@ -75,15 +71,6 @@ function existingDirectory(dir) {
         return undefined;
     }
 }
-/**
- * Realpath of `filePath` when it is genuinely reachable from `homeRoot` (or
- * that root's agent config subdir), else `null`. The one place transcript
- * ownership is decided — reused by native-resume inspection, account
- * attribution, and disambiguation between several accounts sharing one
- * managed binary. Retained trash/backup transcripts are intentionally
- * rejected: they remain readable by `/continue`, but a home must not claim to
- * natively own a transcript it does not.
- */
 function resolveOwnedTranscriptRealpath(filePath, homeRoot, agent) {
     let realFile;
     try {
@@ -108,7 +95,6 @@ function resolveOwnedTranscriptRealpath(filePath, homeRoot, agent) {
 function transcriptOwnedByHome(filePath, homeRoot, agent) {
     return resolveOwnedTranscriptRealpath(filePath, homeRoot, agent) !== null;
 }
-/** History filtering uses login identity, never an organization quota key. */
 export function sessionMatchesAccount(session, account, home) {
     if (account.kind === 'native' && session.agent !== account.agent)
         return false;
@@ -123,18 +109,9 @@ export function sessionMatchesAccount(session, account, home) {
 function candidateAccountId(candidate) {
     return candidate.providerAccountId ?? candidate.nativeAccountId ?? (candidate.fromSlot && candidate.slotDir ? path.basename(candidate.slotDir) : undefined);
 }
-/** The actual native context root for a candidate: its account slot dir when it has one, else the managed version home. */
 function candidateHome(candidate) {
     return candidate.slotDir || getVersionHomePath(candidate.agent, candidate.version);
 }
-/**
- * Whether `candidate` is the proven native owner of `session`'s transcript.
- * A provider (injected credential) candidate never qualifies: it has no
- * isolated context of its own, so a transcript sitting in the version home it
- * happens to ride in is not evidence it produced that transcript (the exact
- * "current credentials in an old home as historical proof" mistake this must
- * not repeat).
- */
 function candidateOwnsTranscript(candidate, session) {
     if (candidate.providerAccount && !session.accountId)
         return false;
@@ -144,7 +121,6 @@ function candidateOwnsTranscript(candidate, session) {
         return session.accountId === acctId;
     return transcriptOwnedByHome(session.filePath, home, candidate.agent);
 }
-/** Stored login identity wins; otherwise require actual native context ownership. */
 function pickOriginCandidate(session, candidates) {
     if (session.accountId)
         return candidates.find(candidate => candidateAccountId(candidate) === session.accountId);
@@ -152,9 +128,6 @@ function pickOriginCandidate(session, candidates) {
     const owners = native.filter(candidate => candidateOwnsTranscript(candidate, session));
     return owners.length === 1 ? owners[0] : undefined;
 }
-/** Read the launch cwd Claude used to choose its projects/<cwd-key> directory.
- * Claude can record attachment envelopes before the first user turn, and those
- * envelopes retain the actual launch cwd even after the session changes dirs. */
 function readClaudeLaunchCwd(filePath) {
     const maxBytes = 2 * 1024 * 1024;
     let fd;
@@ -179,7 +152,6 @@ function readClaudeLaunchCwd(filePath) {
                     return parsed.cwd;
             }
             catch {
-                // A malformed line or vanished cwd cannot identify a usable native home.
             }
         }
     }
@@ -188,13 +160,6 @@ function readClaudeLaunchCwd(filePath) {
     }
     return undefined;
 }
-/**
- * Prove that the indexed transcript is reachable from the exact active
- * native context root that would receive native resume (a version home, or
- * an account slot dir). Retained trash/backup transcripts are intentionally
- * rejected here: they remain readable by `/continue`, but a new installation
- * or account slot must not native-resume an empty isolated home.
- */
 export function inspectNativeResumeSession(session, versionHome) {
     if (session.agent === 'opencode' && (!fs.existsSync(splitSessionFilePath(session.filePath).container) || parseOpenCode(session.filePath).length === 0)) {
         return { available: false, reason: 'the native database has no readable conversation for this session' };
@@ -266,7 +231,6 @@ function resolveExplicitAccountRecovery(session, candidates, agent, device, supp
             : `explicit account '${requested}' differs from the session's recorded origin; continuing on ${matched.accountLabel}${modelSuffix} requires interactive confirmation before replay`,
     };
 }
-/** Keep the native conversation where possible; replay remains a separate choice. */
 export function resolveSessionRecoveryFromCandidates(session, candidates, supportsNative = nativeResume, nativeInspection, options = {}) {
     const agent = runnableSessionAgent(session);
     const device = sessionOriginDevice(session);
@@ -275,15 +239,6 @@ export function resolveSessionRecoveryFromCandidates(session, candidates, suppor
     }
     const source = pickOriginCandidate(session, candidates);
     const sourceReady = source ? readinessFromCandidate(source, undefined, options.model ?? session.model).ready : false;
-    // Native-first with account rotation (PHNX-3626). When the origin login is
-    // usage/rate/session-LIMITED (not signed-out or revoked — those need a login,
-    // not a rotation, so they keep going to /continue per SES-39) but its native
-    // context is installed, native-resume-capable, and still owns the indexed
-    // transcript, keep resume NATIVE by rotating to a healthy INJECTABLE (provider)
-    // account in that SAME context — rather than dropping to /continue on a
-    // different version. Only a provider token/key qualifies: a native login
-    // lives in its own isolated context and cannot be forwarded, so it could
-    // never authenticate a resume that must read the origin's transcript (see §11).
     const originReadiness = source ? readinessFromCandidate(source, undefined, options.model ?? session.model) : null;
     const originLimited = !!originReadiness && !originReadiness.ready
         && (originReadiness.reason === 'rate_limited' || originReadiness.reason === 'out_of_credits' || originReadiness.reason === 'model_limited');
@@ -294,7 +249,6 @@ export function resolveSessionRecoveryFromCandidates(session, candidates, suppor
             const rotated = pickBalancedCandidate(candidates.filter((c) => c.providerAccount && c.accountKey !== source.accountKey), undefined, options.model ?? session.model);
             const account = rotated ? recoveryAccountFromCandidate(rotated.picked) : undefined;
             if (account) {
-                // `originLimited` guarantees the origin is unhealthy with a limit reason.
                 const why = originReadiness.ready ? 'limited' : originReadiness.reason;
                 return {
                     mode: 'native',
@@ -310,10 +264,6 @@ export function resolveSessionRecoveryFromCandidates(session, candidates, suppor
             }
         }
     }
-    // An exact healthy origin is deterministic: preserve its isolated context.
-    // If native resume is unavailable for that harness, /continue still
-    // launches there. Only an unusable/missing/ambiguous origin enters balanced
-    // account selection.
     const selection = sourceReady
         ? { picked: source }
         : pickBalancedCandidate(candidates, undefined, options.model ?? session.model);
@@ -324,14 +274,6 @@ export function resolveSessionRecoveryFromCandidates(session, candidates, suppor
     const version = options.executableVersion ?? selection.picked.version;
     const account = recoveryAccountFromCandidate(selection.picked);
     const continueWith = account ? `healthy ${account.label}` : `the selected ${agent} account`;
-    // Native resume without an injected RecoveryAccount is valid only for the
-    // exact healthy origin login — when sourceReady, `selection.picked` IS
-    // `source` by construction above, so no separate version comparison is
-    // needed (and none would be safe: an accountId-matched origin can carry a
-    // version different from the session's recorded one after a vendor
-    // relabel). A balanced same-version provider selected for a signed-out/
-    // revoked origin must stay on /continue; otherwise we would open the origin
-    // context with no usable credential and fail (or fork state).
     if (sourceReady && supportsNative(agent, version)) {
         const home = candidateHome(selection.picked);
         const inspection = nativeInspection ?? inspectNativeResumeSession(session, home);
@@ -365,13 +307,6 @@ export function resolveSessionRecoveryFromCandidates(session, candidates, suppor
         reason: `${sourceReason(session, source, options.model ?? session.model)}; continuing with ${continueWith}`,
     };
 }
-/**
- * Whether recovery has conversation content to replay for this session: a
- * non-empty transcript file, or archived content in the index for a row this
- * device owns. A mirror digest or live registry entry is not conversation
- * content. The picker consults this before spending a terminal tab on a pick
- * that {@link assertRecoverableTranscript} would refuse one hop later.
- */
 export function sessionTranscriptReadable(session) {
     const file = splitSessionFilePath(session.filePath).container;
     try {
@@ -379,25 +314,15 @@ export function sessionTranscriptReadable(session) {
             && (session.agent !== 'opencode' || parseOpenCode(session.filePath).length > 0))
             return true;
     }
-    catch { /* The canonical scan already tried to repair this path. */ }
+    catch { }
     return !session.mirrorSyncedAt && !session.mirrorSource && Boolean(readSessionContent(session.id)?.trim());
 }
-/** Refuse recovery for a session with nothing to replay (PHNX-4080). */
 export function assertRecoverableTranscript(session) {
     if (sessionTranscriptReadable(session))
         return;
     throw new SessionRecoveryError(`Session ${session.shortId} has no readable transcript after checking its account homes and index. ` +
         `No agent was started. Start a new conversation with: agents run ${session.agent}`);
 }
-/**
- * Resolve recovery for a durable session, reading the live account pool.
- *
- * Uses {@link collectRunCandidatesForRun} (native version-home logins PLUS
- * durable provider accounts, RUSH-3182) rather than the native-only
- * {@link collectRunCandidates}, so an origin-account limit can rotate to a
- * healthy provider account and stay NATIVE (PHNX-3626). `collect` is injectable
- * for tests and for callers that must stay native-only.
- */
 export async function resolveSessionRecovery(session, collect = collectRunCandidatesForRun, options = {}) {
     const agent = runnableSessionAgent(session);
     const { hydrateSessionTranscript } = await import('./discover.js');
@@ -410,9 +335,6 @@ export async function resolveSessionRecovery(session, collect = collectRunCandid
         ...options, executableVersion: installation.label,
     });
 }
-/** Stable self-command used by focus, resume, and attach. The owning device runs
- * the recovery resolver above; callers must not native-resume another version's
- * isolated home themselves. */
 export function sessionRecoveryRunArgs(session) {
     return ['run', 'auto', '--resume', session.id, '--interactive'];
 }

package/dist/lib/session/relative-time.js

@@ -1,4 +1 @@
-// Moved to ../text/relative-time.ts (move 1 of the core-module refactor — see
-// .agents/artifacts/2026-08-20/plan-*.md). Kept as a re-export shim so
-// existing importers don't break.
 export * from '../text/relative-time.js';

package/dist/lib/session/remote/peer-stream.d.ts

@@ -1,66 +1,24 @@
 import type { DeviceProfile } from '../../devices/registry.js';
-/** First reconnect delay after a failed subscription. */
 export declare const PEER_BACKOFF_BASE_MS = 2000;
-/** Ceiling the doubling delay saturates at. */
 export declare const PEER_BACKOFF_CAP_MS = 60000;
-/** Consecutive failed spawns before the peer is parked. */
 export declare const PEER_PARK_AFTER_FAILURES = 3;
-/**
- * Consecutive failed spawns before the peer is RETIRED — the capped 60 s ladder
- * gives way to {@link PEER_RETIRED_RECHECK_MS}.
- *
- * The cap alone bounds the delay but not the total work: a box that is off for a
- * weekend was dialed every 60 s for two days, ~2,880 ssh children per watcher
- * per peer, each one already known to fail. Ten consecutive failures is well
- * past any transient network event, so past that point the peer is treated as
- * genuinely absent and re-dialed on the slow cadence instead.
- */
 export declare const PEER_RETIRE_AFTER_FAILURES = 10;
-/**
- * Re-dial cadence for a retired peer. Still bounded rather than never, because a
- * box can come back without anything touching the device registry — waiting
- * only on a registry change would leave it unreachable until an operator acted.
- */
 export declare const PEER_RETIRED_RECHECK_MS: number;
-/**
- * Reconnect delay for `failures` consecutive failed spawns: 0 for a healthy
- * peer, then {@link PEER_BACKOFF_BASE_MS} doubling to {@link PEER_BACKOFF_CAP_MS},
- * and {@link PEER_RETIRED_RECHECK_MS} once the peer is retired.
- */
 export declare function peerBackoffDelayMs(failures: number, base?: number, cap?: number, retireAfter?: number, retiredMs?: number): number;
 interface PeerStreamOptions {
-    /** The device to subscribe to. */
     device: DeviceProfile;
-    /** Remote command to run over ssh, already shell-quoted for the peer's OS. */
     command: string;
     signal: AbortSignal;
-    /**
-     * One line of the peer's stdout. Return `true` when the line was a valid
-     * protocol event — that is the health signal that resets the backoff.
-     */
     onLine: (line: string) => boolean;
-    /** Report the peer as unavailable, with the captured reason. */
     onUnavailable: (reason: string) => void;
-    /** Override the first backoff delay (tests). */
     backoffBaseMs?: number;
-    /** Override the backoff ceiling (tests). */
     backoffCapMs?: number;
-    /** Override the park threshold (tests). */
     parkAfterFailures?: number;
-    /** Override the retire threshold (tests). */
     retireAfterFailures?: number;
-    /** Override the retired re-dial cadence (tests). */
     retiredRecheckMs?: number;
-    /** Override the ssh binary (tests). */
     sshBin?: string;
-    /** Override the parked peer's registry re-check cadence (tests). */
     registryPollMs?: number;
-    /** Override the registry file a parked peer waits on (tests). */
     registryPath?: string;
 }
-/**
- * Hold one peer subscription open for the life of the signal, reconnecting with
- * backoff. Resolves when the signal aborts or the peer cannot be addressed.
- */
 export declare function streamFromPeer(options: PeerStreamOptions): Promise<void>;
 export {};

package/dist/lib/session/remote/peer-stream.js

@@ -1,68 +1,16 @@
-/**
- * One peer's `--local` watch subscription, with connection hygiene.
- *
- * Both fleet fan-outs (`watchFleetSessions`, `watchFleetFeed`) subscribe to
- * every dialable device with a long-lived `ssh <peer> agents … watch --json
- * --local`. Both used to respawn that child on a bare 2 s timer with the
- * child's stderr set to `'ignore'`, so an offline peer — and `isDialableDevice`
- * deliberately never excludes one — got a fresh ssh every ConnectTimeout + 2 s
- * for the whole life of the watcher, with the reason discarded. That is the
- * ssh-child churn the 2026-09-03 incident reported.
- *
- * This module is the single implementation both fan-outs call:
- *
- * - exponential backoff per peer, {@link PEER_BACKOFF_BASE_MS} doubling to
- *   {@link PEER_BACKOFF_CAP_MS}, reset the moment the peer delivers a healthy
- *   protocol event;
- * - the child's stderr captured (bounded to {@link PEER_STDERR_BYTES}) and
- *   surfaced as the `unavailable` reason instead of being thrown away;
- * - a peer that fails {@link PEER_PARK_AFTER_FAILURES} spawns in a row parked —
- *   it stops the reconnect cycle and re-dials only when the device registry
- *   changes or the capped backoff elapses;
- * - a peer that fails {@link PEER_RETIRE_AFTER_FAILURES} in a row RETIRED — the
- *   capped 60 s ladder is itself unbounded in total work, so past that point the
- *   re-dial drops to {@link PEER_RETIRED_RECHECK_MS};
- * - abort listeners removed per iteration, so a watcher open for hours does not
- *   accumulate one per reconnect on the caller's AbortSignal.
- */
 import { spawn } from 'node:child_process';
 import * as fs from 'node:fs';
 import { createInterface } from 'node:readline';
 import { deviceIdentityArgs, sshTargetFor } from '../../devices/connect.js';
 import { SSH_OPTS, controlOpts } from '../../ssh-exec.js';
 import { getDevicesRegistryPath } from '../../state.js';
-/** First reconnect delay after a failed subscription. */
 export const PEER_BACKOFF_BASE_MS = 2_000;
-/** Ceiling the doubling delay saturates at. */
 export const PEER_BACKOFF_CAP_MS = 60_000;
-/** Consecutive failed spawns before the peer is parked. */
 export const PEER_PARK_AFTER_FAILURES = 3;
-/**
- * Consecutive failed spawns before the peer is RETIRED — the capped 60 s ladder
- * gives way to {@link PEER_RETIRED_RECHECK_MS}.
- *
- * The cap alone bounds the delay but not the total work: a box that is off for a
- * weekend was dialed every 60 s for two days, ~2,880 ssh children per watcher
- * per peer, each one already known to fail. Ten consecutive failures is well
- * past any transient network event, so past that point the peer is treated as
- * genuinely absent and re-dialed on the slow cadence instead.
- */
 export const PEER_RETIRE_AFTER_FAILURES = 10;
-/**
- * Re-dial cadence for a retired peer. Still bounded rather than never, because a
- * box can come back without anything touching the device registry — waiting
- * only on a registry change would leave it unreachable until an operator acted.
- */
 export const PEER_RETIRED_RECHECK_MS = 15 * 60_000;
-/** Bytes of a peer's stderr retained for the `unavailable` reason. */
 const PEER_STDERR_BYTES = 2_048;
-/** How often a parked peer re-checks the device registry for a refresh. */
 const PEER_REGISTRY_POLL_MS = 5_000;
-/**
- * Reconnect delay for `failures` consecutive failed spawns: 0 for a healthy
- * peer, then {@link PEER_BACKOFF_BASE_MS} doubling to {@link PEER_BACKOFF_CAP_MS},
- * and {@link PEER_RETIRED_RECHECK_MS} once the peer is retired.
- */
 export function peerBackoffDelayMs(failures, base = PEER_BACKOFF_BASE_MS, cap = PEER_BACKOFF_CAP_MS, retireAfter = PEER_RETIRE_AFTER_FAILURES, retiredMs = PEER_RETIRED_RECHECK_MS) {
     if (failures <= 0)
         return 0;
@@ -70,17 +18,14 @@ export function peerBackoffDelayMs(failures, base = PEER_BACKOFF_BASE_MS, cap =
         return retiredMs;
     return Math.min(cap, base * 2 ** (failures - 1));
 }
-/** Bounded tail of a child's stderr, kept for the unavailable reason. */
 function stderrTail(chunks, next, limit) {
     const joined = chunks + next;
     return joined.length > limit ? joined.slice(joined.length - limit) : joined;
 }
-/** Collapse captured stderr to one quotable line. */
 function reasonFor(exit, stderr) {
     const detail = stderr.split('\n').map((line) => line.trim()).filter(Boolean).pop();
     return detail ? `${exit}: ${detail}` : exit;
 }
-/** Await a delay, a device-registry change, or abort — whichever comes first. */
 async function parkedWait(options, delayMs) {
     const registry = options.registryPath ?? getDevicesRegistryPath();
     const pollMs = options.registryPollMs ?? PEER_REGISTRY_POLL_MS;
@@ -111,10 +56,6 @@ async function parkedWait(options, delayMs) {
         options.signal.addEventListener('abort', finish, { once: true });
     });
 }
-/**
- * Hold one peer subscription open for the life of the signal, reconnecting with
- * backoff. Resolves when the signal aborts or the peer cannot be addressed.
- */
 export async function streamFromPeer(options) {
     const parkAfter = options.parkAfterFailures ?? PEER_PARK_AFTER_FAILURES;
     let failures = 0;
@@ -124,7 +65,6 @@ export async function streamFromPeer(options) {
             target = sshTargetFor(options.device);
         }
         catch (error) {
-            // No address at all is not a transient failure: retrying cannot fix it.
             options.onUnavailable(error instanceof Error ? error.message : String(error));
             return;
         }
@@ -138,8 +78,6 @@ export async function streamFromPeer(options) {
         child.stderr?.on('data', (chunk) => { stderr = stderrTail(stderr, chunk, PEER_STDERR_BYTES); });
         const reader = createInterface({ input: child.stdout });
         reader.on('line', (line) => {
-            // A peer that is delivering protocol is healthy, so the next disconnect
-            // starts the backoff over rather than inheriting an old failure streak.
             if (options.onLine(line))
                 failures = 0;
         });
@@ -148,8 +86,6 @@ export async function streamFromPeer(options) {
             child.once('close', resolve);
         });
         reader.close();
-        // Removed per iteration: a watcher open for hours would otherwise leak one
-        // listener per reconnect onto the caller's signal.
         options.signal.removeEventListener('abort', stop);
         if (options.signal.aborted)
             return;

package/dist/lib/session/remote/remote-bundle.d.ts

@@ -3,11 +3,5 @@ interface RemotePullResult {
     bundles: ParsedBundle[];
     errors: string[];
 }
-/**
- * Run `agents sessions export …exportArgs --stdout` on each host and parse the
- * streamed bundle. A host that fails (unreachable, remote error, bad output) is
- * collected in `errors` and skipped — one asleep peer never aborts the pull.
- * `exportArgs` must NOT contain --device (the remote export runs for itself only).
- */
 export declare function pullBundlesFromHosts(hosts: string[], exportArgs: string[]): Promise<RemotePullResult>;
 export {};

package/dist/lib/session/remote/remote-bundle.js

@@ -1,25 +1,10 @@
-/**
- * Multi-device session transfer over the EXISTING SSH fleet transport
- * (RUSH-1712) — no R2, no daemon. `agents sessions export --device <h>` and
- * `agents sessions import --from-host <h>` both run `agents sessions export
- * … --stdout` ON the peer and stream the bundle back over the same SSH path the
- * cross-machine listing already uses (resolveExplicitTargets + ssh-exec), then
- * either write it (export) or import it (import) locally.
- *
- * This deliberately reuses ssh-exec / resolve-target rather than adding a second
- * transport: the raw form `agents ssh boxA 'agents sessions export --stdout' |
- * agents sessions import -` works with plain export/import; this module is just
- * the one-shot wrapper around it.
- */
 import chalk from 'chalk';
 import { sshExec } from '../../ssh-exec.js';
 import { shellQuote } from '../../ssh-exec.js';
 import { resolveExplicitTargets } from '../../devices/resolve-target.js';
 import { remoteShellFor, buildWindowsAgentsCommand } from '../../hosts/remote-cmd.js';
 import { parseBundle } from '../bundle.js';
-/** Remote export can traverse many sessions; give it a generous ceiling. */
 const REMOTE_EXPORT_TIMEOUT_MS = 300_000;
-/** Build `agents <args>` for the peer's login shell (bash or PowerShell). */
 function remoteAgentsCommand(args, os) {
     if (remoteShellFor(os) === 'powershell') {
         return buildWindowsAgentsCommand({ args });
@@ -27,12 +12,6 @@ function remoteAgentsCommand(args, os) {
     const inner = ['agents', ...args].map((t, i) => (i === 0 ? t : shellQuote(t))).join(' ');
     return `bash -lc ${shellQuote(inner)}`;
 }
-/**
- * Run `agents sessions export …exportArgs --stdout` on each host and parse the
- * streamed bundle. A host that fails (unreachable, remote error, bad output) is
- * collected in `errors` and skipped — one asleep peer never aborts the pull.
- * `exportArgs` must NOT contain --device (the remote export runs for itself only).
- */
 export async function pullBundlesFromHosts(hosts, exportArgs) {
     const targets = await resolveExplicitTargets(hosts);
     const bundles = [];

package/dist/lib/session/remote/remote-list.d.ts

@@ -1,6 +1,6 @@
 import { type DeviceProfile } from '../../devices/registry.js';
 import { type RemoteAgentsJsonParseResult } from '../../remote-agents-json.js';
-import type { SessionMeta } from '../types.js';
+import type { SessionMeta } from '@phnx-labs/sessions-cli/reader';
 import { type ToolProgramCountEnvelope, type ToolSearchEnvelope } from '../tool-index.js';
 export { REMOTE_STDOUT_MAX_BYTES, RemoteUtf8Accumulator } from '../../ssh-exec.js';
 export declare const REMOTE_TOOL_AGGREGATE_MAX_BYTES: number;
@@ -8,33 +8,14 @@ interface RemoteToolByteBudget {
     remainingBytes: number;
     exhausted: boolean;
 }
-/** Claim received bytes against one fleet-query budget before retaining them. */
 export declare function consumeRemoteToolByteBudget(budget: RemoteToolByteBudget, bytes: number): boolean;
-/** Charge sanitized, machine-stamped evidence because redaction may expand it. */
 export declare function consumeParsedRemoteToolSearchBudget(budget: RemoteToolByteBudget, envelope: ToolSearchEnvelope): boolean;
-/**
- * The command run on each peer: answer for itself, as JSON, without recursing.
- * `forwardedArgs` carry the caller's own query/filters (already including the
- * leading `sessions` and a `--json`) so each peer returns a comparable slice.
- * A Windows peer gets a PowerShell invocation (ssh lands in cmd.exe/PowerShell
- * there, where `bash -lc` is not a command); every other OS keeps `bash -lc`.
- */
 export declare function remoteListCommand(forwardedArgs: string[], os?: string): string;
-/**
- * Parse a peer's `sessions --json` stdout into `SessionMeta[]`, tagging each
- * with `machine`. Defensive against version skew / partial output: non-JSON or
- * a non-array yields `[]`, and non-object entries are dropped rather than
- * throwing. The `machine` we dialed always wins over any value the peer set on
- * its own rows, so grouping keys off the computer we asked. Exported for unit
- * testing without a live tailnet.
- */
 export declare function parseRemoteList(stdout: string, machine: string): SessionMeta[];
 export declare function parseRemoteListPayload(stdout: string, machine: string, safeResolver?: boolean): {
     items: SessionMeta[];
     valid: boolean;
 };
-/** Run one remote `agents sessions … --json` and capture stdout. Resolves
- * `{ code: null }` on spawn error or timeout (host treated as dead). */
 export declare function sshCapture(target: string, remoteCmd: string, timeoutMs: number, aggregateBudget?: RemoteToolByteBudget, options?: {
     multiplex?: boolean;
     port?: number;
@@ -46,34 +27,12 @@ export declare function sshCapture(target: string, remoteCmd: string, timeoutMs:
 }>;
 interface RemoteListResult {
     sessions: SessionMeta[];
-    /** How many peer machines we attempted to reach (drives the empty-fleet tip). */
     deviceCount: number;
-    /**
-     * Peers that failed to answer, by display name. The stderr note above is
-     * enough for a printed listing, but the interactive browser repaints over it —
-     * so callers rendering a full-screen UI need the outcome as data to tell
-     * "that box is asleep" apart from "that box has no matching sessions".
-     */
     unreachable: string[];
 }
-/** Keep browse and tool-search fan-out on the same automatic peer set. */
 export declare function isAutomaticSessionPeer(d: DeviceProfile, self: string): boolean;
-/**
- * Gather listing sessions from other machines. With an explicit `hosts` list
- * (from `--device`), fan out to exactly those. Otherwise sweep the registered,
- * online devices from `ag devices`, excluding this machine and any without an
- * address. `forwardedArgs` are the caller's own sessions args (query + filters,
- * already `--json`) so every peer returns the same slice this machine asked for.
- */
 interface GatherRemoteListOptions {
-    /**
-     * Opt-in early-exit for a globally-unique id lookup (a full UUID): the first
-     * peer to return the matching row resolves the fan-out and cancels the rest.
-     * Omitted for browse/label/prefix sweeps, which must wait for every peer to
-     * know whether the match is unique or conflicting.
-     */
     isDefinitive?: (session: SessionMeta, machine: string) => boolean;
-    /** Per-peer deadline for slower indexed browse queries. */
     timeoutMs?: number;
 }
 export declare function gatherRemoteList(forwardedArgs: string[], hosts?: string[], opts?: GatherRemoteListOptions): Promise<RemoteListResult>;
@@ -100,29 +59,11 @@ export declare function parseRemoteToolProgramCount(stdout: string, machine: str
 }>;
 export declare function gatherRemoteToolProgramCounts(forwardedArgs: string[], hosts: string[] | undefined, expectedProgram: string): Promise<RemoteToolProgramCountResult>;
 export declare function parseRemoteToolSearch(stdout: string, machine: string, expectedClauses?: string[]): ToolSearchEnvelope | undefined;
-/**
- * Fleet sibling of {@link gatherRemoteList} for the versioned tool-search
- * envelope. Each peer executes the same local-only query against its own
- * SQLite index; only compact matches cross SSH.
- */
 export declare function gatherRemoteToolSearch(forwardedArgs: string[], hosts?: string[], maxAggregateBytes?: number, expectedClauses?: string[]): Promise<RemoteToolSearchResult>;
-/** Resolve a peer's SSH target (and OS) from the device registry by its
- * normalized machine id — the same id the fan-out tags rows with. Returns
- * undefined when no registered device with an address matches. */
 export declare function resolvePeerTarget(machine: string): Promise<{
     target: string;
     os?: string;
 } | undefined>;
-/**
- * Fetch one remote session's preview digest from its owning peer — the data
- * behind the picker pane for a `_remote` row, whose transcript file this
- * machine cannot parse. Runs the peer's own `agents sessions preview <id>
- * --local --json` (the same envelope `agents sessions preview` already
- * delegates to for a remote id) and returns its `preview` object, verbatim and
- * UNSANITIZED — the caller owns scrubbing peer-supplied strings before any of
- * them reach a TTY. Undefined on every failure: unregistered machine, SSH
- * error, timeout, version-skewed peer with no `--json` preview envelope.
- */
 export declare function fetchPeerPreviewDigest(sessionId: string, machine: string, timeoutMs?: number): Promise<unknown | undefined>;
 export type PeerPreviewEnvelopeResult = {
     ok: true;
@@ -131,58 +72,8 @@ export type PeerPreviewEnvelopeResult = {
     ok: false;
     reason: 'no-target' | 'unreachable' | 'invalid-json';
 };
-/**
- * Fetch the FULL `agents sessions preview <id> --local --json` envelope
- * (session/active/preview/error, not just the `.preview` slice
- * {@link fetchPeerPreviewDigest} narrows to) from a session's owning peer in
- * exactly ONE bounded {@link sshCapture} hop. This is the canonical exact
- * ID+owner preview loader (PHNX-3999): the peer's own command already runs the
- * owner-side bounded parsers/fold (`loadSessionPreviewDigest`) and existing
- * redaction, so a caller that already knows the owning device needs no
- * separate metadata round trip before this one — unlike the general fleet
- * resolver, which fans out a `sessions <id> --json --all` metadata query first
- * because it does NOT yet know which peer (if any) holds the id.
- */
 export declare function fetchPeerPreviewEnvelope(sessionId: string, machine: string, timeoutMs?: number): Promise<PeerPreviewEnvelopeResult>;
-/** Parse the JSON envelope returned by `sessions preview --json`. */
 export declare function parsePeerPreviewDigest(parsed: unknown): unknown | undefined;
-/**
- * Run `agents <args>` ON a peer over SSH, attached to this terminal (inherited
- * stdio). `args` is the full arg vector after the binary — callers pass e.g.
- * `['sessions', id, '--markdown']` or `['sessions', 'resume', id]`. Used when a
- * picked session lives on another machine: its transcript and agent binary are
- * there, so both reading (no TTY) and resuming (TTY) must execute on the peer —
- * not via a local `--device` hop, which would discover locally and dead-end for a
- * session that exists only on the peer. Resolves 'no-target' when the machine
- * isn't a dialable registered device; the caller surfaces a clear message.
- *
- * `opts.env` adds variables to the remote command. It deliberately does NOT
- * carry `AGENTS_FLEET_REMOTE` the way the `--device` passthrough does: that marker
- * gates consent-sensitive actions on the far side
- * (lib/browser/remote-control.ts), and a resumed agent is a long-lived session
- * that would inherit it for its whole life — `agents browser start` inside it
- * would then be refused as a cross-machine drive. A one-shot `--device` command
- * can carry the marker; a session cannot.
- *
- * `opts.sessionId` (with `tty`) prints the session id and resume command when
- * the SSH hop ends, so OpenSSH's `Shared connection … closed.` is not the last
- * thing on the local shell (RUSH-3227). Omit it for one-shot non-TTY renders.
- *
- * Resolves `'unreachable'` when the SSH connection itself failed — ssh could not
- * launch (spawn error) or exited with {@link SSH_CONN_FAILURE_CODE} (255, its
- * connect-failure convention) — as opposed to `'ok'` for a hop that actually
- * reached the peer (whatever the remote command's own exit code). This lets a
- * caller prefer the recorded device yet fall back locally when it is genuinely
- * offline (PHNX-3626); callers that ignore `'unreachable'` behave exactly as
- * before (it was `'ok'`).
- */
-/**
- * Classify a finished SSH hop by its exit code: `'unreachable'` when the
- * connection itself failed (ssh's {@link SSH_CONN_FAILURE_CODE} = 255, or a null
- * code from a killed/never-launched child), else `'ok'` — the remote command ran,
- * whatever its own exit status. Pure so the offline-device fallback is unit-tested
- * without a live SSH hop (PHNX-3626).
- */
 export declare function peerHopOutcome(code: number | null): 'ok' | 'unreachable';
 export declare function peerHopCloseNotice(opts: {
     tty?: boolean;