@phnx-labs/agents-cli 1.22.119 → 1.22.121

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

@@ -1,18 +1,3 @@
-/**
- * Cross-machine fan-out for the default `agents sessions` listing.
- *
- * `discoverSessions()` only scans the local disk. To browse the whole fleet in
- * one list — without syncing anything — we run `agents sessions <same query>
- * --json` on each peer over SSH and merge the parsed `SessionMeta[]`, tagging
- * every row with the machine it came from so the picker/table can label and
- * group by computer.
- *
- * This is the browse-listing sibling of `remote-active.ts` (which fans out
- * `--active`): same transport, same device set, same recursion guard. The peer
- * runs with `AGENTS_SESSIONS_LOCAL=1` so it answers only for itself and the
- * sweep never recurses. A dead or slow host is skipped with a stderr note,
- * never fatal — one asleep laptop must not blank the list.
- */
 import { spawn } from 'child_process';
 import chalk from 'chalk';
 import { SSH_OPTS, controlOpts, assertValidSshTarget, shellQuote, SSH_CONN_FAILURE_CODE, REMOTE_STDOUT_MAX_BYTES, RemoteUtf8Accumulator, } from '../../ssh-exec.js';
@@ -28,15 +13,10 @@ import { terminalWidth } from '../../text/width.js';
 import { sanitizeForTerminal } from '../../redact.js';
 import { mapBounded } from '../../concurrency.js';
 import { TOOL_QUERY_MAX_CLAUSE_BYTES, TOOL_QUERY_MAX_CALL_ROWS, TOOL_QUERY_MAX_CLAUSES, TOOL_QUERY_MAX_RESULT_SESSIONS, TOOL_QUERY_MAX_SERIALIZED_BYTES, serializedToolSearchEnvelopeBytes, } from '../tool-index.js';
-import { TOOL_ERROR_OUTPUT_MAX_BYTES, TOOL_INPUT_MAX_BYTES, TOOL_SUCCESS_OUTPUT_MAX_BYTES, sanitizeToolEvidenceText, } from '../tool-calls.js';
+import { TOOL_ERROR_OUTPUT_MAX_BYTES, TOOL_INPUT_MAX_BYTES, TOOL_SUCCESS_OUTPUT_MAX_BYTES, sanitizeToolEvidenceText, } from '@phnx-labs/sessions-cli/reader';
 const REMOTE_TOOL_TIMEOUT_MS = 60_000;
-// The per-peer stdout ceiling and the UTF-8-safe accumulator live in ssh-exec.ts
-// (the shared SSH transport both this reader and the top-level `remote-agents-json`
-// fan-out import), so the bound is defined once. Re-exported here for the existing
-// consumers/tests that reach them through this module.
 export { REMOTE_STDOUT_MAX_BYTES, RemoteUtf8Accumulator } from '../../ssh-exec.js';
 export const REMOTE_TOOL_AGGREGATE_MAX_BYTES = TOOL_QUERY_MAX_SERIALIZED_BYTES;
-/** Claim received bytes against one fleet-query budget before retaining them. */
 export function consumeRemoteToolByteBudget(budget, bytes) {
     if (budget.exhausted || bytes > budget.remainingBytes) {
         budget.remainingBytes = 0;
@@ -48,17 +28,9 @@ export function consumeRemoteToolByteBudget(budget, bytes) {
         budget.exhausted = true;
     return true;
 }
-/** Charge sanitized, machine-stamped evidence because redaction may expand it. */
 export function consumeParsedRemoteToolSearchBudget(budget, envelope) {
     return consumeRemoteToolByteBudget(budget, serializedToolSearchEnvelopeBytes(envelope));
 }
-/**
- * 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 function remoteListCommand(forwardedArgs, os) {
     if (remoteShellFor(os) === 'powershell') {
         return buildWindowsAgentsCommand({
@@ -69,14 +41,6 @@ export function remoteListCommand(forwardedArgs, os) {
     const inner = [`${NO_FANOUT_ENV}=1`, 'agents', ...forwardedArgs].map((t, i) => i === 0 ? t : shellQuote(t)).join(' ');
     return `bash -lc ${shellQuote(inner)}`;
 }
-/**
- * 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 function parseRemoteList(stdout, machine) {
     let parsed;
     try {
@@ -91,8 +55,6 @@ export function parseRemoteList(stdout, machine) {
         ? [{ ...value, machine, _remote: true }]
         : []);
 }
-/** Strict parser used at the live peer boundary. A successful process with
- * malformed/non-array JSON is an incomplete source, not an empty machine. */
 const SAFE_RESOLVER_KEYS = new Set([
     'id', 'shortId', 'agent', 'origin', 'timestamp', 'lastActivity', 'project',
     'version', 'harness', 'mode', 'label', 'topic', 'machine',
@@ -120,14 +82,10 @@ export function parseRemoteListPayload(stdout, machine, safeResolver = false) {
         if (safeResolver && !isSafeResolverRow(x)) {
             return { items: [], valid: false };
         }
-        // `_remote` marks these as living on the peer's disk (not a local mirror),
-        // so the picker routes read/resume back over SSH instead of the local FS.
         out.push({ ...x, machine, _remote: true });
     }
     return { items: out, valid: true };
 }
-/** Run one remote `agents sessions … --json` and capture stdout. Resolves
- * `{ code: null }` on spawn error or timeout (host treated as dead). */
 export function sshCapture(target, remoteCmd, timeoutMs, aggregateBudget, options = {}) {
     assertValidSshTarget(target);
     return new Promise((resolve) => {
@@ -172,7 +130,6 @@ export function sshCapture(target, remoteCmd, timeoutMs, aggregateBudget, option
         child.on('close', (code) => done(code));
     });
 }
-/** Keep browse and tool-search fan-out on the same automatic peer set. */
 export function isAutomaticSessionPeer(d, self) {
     if (!isDialableDevice(d))
         return false;
@@ -364,9 +321,6 @@ function parseRemoteToolSession(value, machine) {
     };
 }
 export function parseRemoteToolSearch(stdout, machine, expectedClauses) {
-    // The fleet tool-search fan-out reads a raw sshCapture (not the stripped
-    // gatherRemoteAgentsJson wrapper), so a Windows peer's PowerShell CLIXML banner
-    // must be removed here too or the box reads as "no envelope" (RUSH-2286).
     stdout = stripClixml(stdout);
     if (Buffer.byteLength(stdout) > REMOTE_STDOUT_MAX_BYTES)
         return undefined;
@@ -422,11 +376,6 @@ export function parseRemoteToolSearch(stdout, machine, expectedClauses) {
         return 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 async function gatherRemoteToolSearch(forwardedArgs, hosts, maxAggregateBytes = REMOTE_TOOL_AGGREGATE_MAX_BYTES, expectedClauses = []) {
     const self = machineId();
     const targets = [];
@@ -451,7 +400,6 @@ export async function gatherRemoteToolSearch(forwardedArgs, hosts, maxAggregateB
                 targets.push({ target: sshTargetFor(d), machine: normalizeHost(d.name), name: d.name, os: d.platform });
             }
             catch {
-                // A registered control record without a dialable address is not a query target.
             }
         }
     }
@@ -467,11 +415,7 @@ export async function gatherRemoteToolSearch(forwardedArgs, hosts, maxAggregateB
     const results = await mapBounded(targets, async (target) => {
         if (aggregateBudget.exhausted)
             return { target, truncated: target.name };
-        const capture = await sshCapture(target.target, remoteListCommand(forwardedArgs, target.os), REMOTE_TOOL_TIMEOUT_MS, aggregateBudget, 
-        // A tool-index deadline must own the SSH connection. Killing a
-        // multiplexed child would leave its remote command running on the
-        // persistent control master.
-        { multiplex: false });
+        const capture = await sshCapture(target.target, remoteListCommand(forwardedArgs, target.os), REMOTE_TOOL_TIMEOUT_MS, aggregateBudget, { multiplex: false });
         if (capture.aggregateBudgetExceeded)
             return { target, truncated: target.name };
         if (capture.code !== 0)
@@ -501,9 +445,6 @@ export async function gatherRemoteToolSearch(forwardedArgs, hosts, maxAggregateB
         truncated: results.map((result) => result.truncated).filter((name) => !!name),
     };
 }
-/** 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 async function resolvePeerTarget(machine) {
     let reg;
     try {
@@ -519,44 +460,18 @@ export async function resolvePeerTarget(machine) {
             return { target: sshTargetFor(d), os: d.platform };
         }
         catch {
-            return undefined; // matched the machine, but it has no address to dial
+            return undefined;
         }
     }
     return undefined;
 }
-/** Interactive ceiling for a picker-driven peer preview fetch. Tighter than the
- * fan-out's 60s: the user is arrowing through rows, and a peer that can't
- * answer a one-session digest in this window should degrade to the metadata
- * card rather than hold a "fetching…" pane open. */
 const PEER_PREVIEW_TIMEOUT_MS = 15_000;
-/**
- * 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 async function fetchPeerPreviewDigest(sessionId, machine, timeoutMs = PEER_PREVIEW_TIMEOUT_MS) {
     const envelope = await fetchPeerPreviewEnvelope(sessionId, machine, timeoutMs);
     if (!envelope.ok)
         return undefined;
     return parsePeerPreviewDigest(envelope.envelope);
 }
-/**
- * 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 async function fetchPeerPreviewEnvelope(sessionId, machine, timeoutMs = PEER_PREVIEW_TIMEOUT_MS) {
     const peer = await resolvePeerTarget(machine);
     if (!peer)
@@ -572,7 +487,6 @@ export async function fetchPeerPreviewEnvelope(sessionId, machine, timeoutMs = P
         return { ok: false, reason: 'invalid-json' };
     }
 }
-/** Parse the JSON envelope returned by `sessions preview --json`. */
 export function parsePeerPreviewDigest(parsed) {
     if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
         return undefined;
@@ -581,43 +495,6 @@ export function parsePeerPreviewDigest(parsed) {
         return undefined;
     return preview;
 }
-/**
- * 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 function peerHopOutcome(code) {
     return code === SSH_CONN_FAILURE_CODE || code === null ? 'unreachable' : 'ok';
 }
@@ -630,39 +507,28 @@ export async function runOnPeer(args, machine, opts = {}) {
     const peer = await resolvePeerTarget(machine);
     if (!peer)
         return 'no-target';
-    assertValidSshTarget(peer.target); // registry-sourced, but validate like the fan-out does
+    assertValidSshTarget(peer.target);
     const cols = terminalWidth();
     const env = { ...(cols > 0 ? { COLUMNS: String(cols) } : {}), ...opts.env };
     const assignments = Object.entries(env).map(([k, v]) => `${k}=${shellQuote(v)}`);
     const invocation = assignments.concat(['agents', ...args].map(shellQuote)).join(' ');
-    // OpenSSH uses 255 for transport failure, but also propagates a reached remote
-    // program's 255 verbatim. Remap only the remote program's 255 inside the peer
-    // shell so the outer SSH status remains an unambiguous connectivity signal.
     const remoteCmd = remoteShellFor(peer.os) === 'powershell'
         ? buildWindowsAgentsCommand({ args, env: assignments.length ? env : undefined, remapExit255: true })
         : `bash -lc ${shellQuote(`${invocation}; agents_rc=$?; if [ "$agents_rc" -eq 255 ]; then exit 254; fi; exit "$agents_rc"`)}`;
     const sshArgs = [...SSH_OPTS, ...controlOpts()];
     if (opts.tty)
-        sshArgs.push('-tt'); // force a PTY so the resumed agent is interactive
+        sshArgs.push('-tt');
     sshArgs.push(peer.target, remoteCmd);
     return new Promise((resolve) => {
         const child = spawn('ssh', sshArgs, { stdio: 'inherit' });
-        // ssh prints its own connection errors to the inherited stderr; a spawn
-        // failure (e.g. ssh not on PATH) has no such output, so name it. Either way
-        // we resolve once it settles so the picker flow completes.
         child.on('error', (err) => {
             process.stderr.write(chalk.red(`Failed to reach ${machine}: ${err?.message ?? 'ssh failed to launch'}\n`));
             resolve('unreachable');
         });
         child.on('close', (code) => {
-            // Interactive TTY hop: OpenSSH prints "Shared connection … closed." and
-            // nothing else. Leave the session id on the local shell (RUSH-3227).
             const notice = peerHopCloseNotice(opts, machine, code);
             if (notice)
                 process.stderr.write(notice);
-            // ssh exits 255 only when the connection itself failed (host down/asleep),
-            // distinct from the remote command's own non-zero exit. Report that so a
-            // caller can fall back locally instead of silently completing.
             resolve(peerHopOutcome(code));
         });
     });

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

@@ -1,133 +1,35 @@
-/**
- * POSIX single-quote a string for safe interpolation into a remote shell command.
- * Always wraps (unlike the bare-passthrough variant in `ssh-exec.ts`) — the
- * forwarded `agents` argv is embedded verbatim inside `bash -lc '<cmd>'`, so
- * every token is quoted to keep the command boundary unambiguous.
- */
 export declare function shellQuote(s: string): string;
-/**
- * Strip the `--device`/`-D` flag (and its value) from a raw `agents sessions` argv,
- * leaving the args to forward to the remote unchanged. The remote runs the same
- * binary, so every other flag (`--since`, `--last`, `--json`, query, …) carries
- * over for free. Handles every form commander accepts: `--device h`, `--device=h`,
- * `-D h`, `-D=h`, and the glued short form `-Dh`.
- *
- * @param argv full process argv; the sessions args begin at index 2
- *             (`[runtime, script, 'sessions', ...]`).
- */
 export declare function buildForwardedArgs(argv: string[], hosts?: Set<string>): string[];
-/**
- * Force a forwarded `agents sessions` listing to span the peer's WHOLE index.
- *
- * A remote listing runs in the peer's SSH-login cwd — its home dir — and the
- * default listing is silently cwd-scoped, so `sessions --device box` reads as
- * empty even when the box's index is full (`No sessions found for /home/<user>`).
- * Across SSH a peer's cwd is meaningless, so `--device` defaults to `--all`
- * (whole-index) scope. This only drops the *cwd* narrowing — an explicit path
- * query, `--project`, `--since`, or `--agent` filter still narrows on top, and
- * a query that looks like a path takes precedence over `--all` on the remote.
- * Idempotent: never adds a second `--all`.
- */
 export declare function ensureWholeIndex(forwardedArgs: string[]): string[];
-/**
- * Build the single remote command string for `ssh <host> <cmd>`. Forwarded args
- * are quoted for the inner login shell, then the whole `agents …` invocation is
- * quoted again so it survives `bash -lc <...>`.
- *
- * `os` selects the remote shell: a Windows host gets a PowerShell invocation
- * (ssh lands in cmd.exe/PowerShell there, where `bash -lc` does not exist);
- * anything else — including unknown/absent — keeps the POSIX form unchanged.
- * The forwarded terminal width rides across as an env var either way so the
- * remote renders its table to the local screen.
- */
 export declare function buildRemoteCommand(forwardedArgs: string[], columns?: number, os?: string): string;
-/** The four outcomes of one `ssh <host> agents sessions …` invocation. */
 type SshOutcome = 'ok' | 'unreachable' | 'query-failed' | 'spawn-error';
-/**
- * Classify an ssh `spawnSync` result. ssh(1) reserves exit 255 for its own
- * connection-layer failures (host down, timeout, refused, auth, changed host
- * key) — distinct from any other non-zero, which is the remote `agents sessions`
- * exit code forwarded back (the query ran but failed). The two must be handled
- * differently: 255 may fall back to cache, a forwarded failure must surface.
- */
 export declare function classifySshFailure(res: {
     error?: Error | null;
     status: number | null;
 }): SshOutcome;
-/**
- * How long a successful remote fetch may be served without re-SSHing.
- * Short on purpose: session listings must stay near-live (RUSH-2062). Match the
- * active-session snapshot window so surfaces share one freshness model.
- */
 export declare const REMOTE_CACHE_MAX_AGE_MS = 15000;
-/**
- * Deterministic cache path for a (host, forwarded-args) pair. The forwarded args
- * are hashed so distinct queries cache independently; the host stays readable in
- * the filename (sanitised so `user@host` and aliases are filesystem-safe).
- */
 export declare function remoteCachePath(host: string, forwardedArgs: string[]): string;
-/**
- * Pure freshness check for a remote-sessions cache entry. A reachable host
- * skips SSH only while this returns true; unreachable fallback ignores age.
- */
 export declare function isRemoteCacheFresh(mtimeMs: number, nowMs: number, maxAgeMs?: number): boolean;
 interface RemoteCacheHit {
     output: string;
     mtimeMs: number;
 }
-/**
- * Read a cached remote fetch. When `maxAgeMs` is set, returns null if the
- * entry is older than the window (cache-first path for reachable hosts).
- * Omit `maxAgeMs` to accept any age (unreachable fallback).
- */
 export declare function readRemoteCache(host: string, forwardedArgs: string[], opts?: {
     maxAgeMs?: number;
     nowMs?: number;
 }): RemoteCacheHit | null;
-/** Banner shown above replayed cache rows when the peer is offline. */
 export declare function formatStaleBanner(host: string, mtimeMs: number): string;
-/** Message shown when a host is unreachable and there is no cache to fall back to. */
 export declare function formatUnreachable(host: string): string;
-/** Persist a successful fetch for later cache-first / offline replay.
- * Best-effort: a cache write must never break the live query. Exported for tests. */
 export declare function writeRemoteCache(host: string, forwardedArgs: string[], output: string): void;
-/**
- * Serve a *fresh* cache entry for a reachable-host skip (no banner — the data
- * is still within the freshness window). Returns false when missing/stale so
- * the caller SSHes. RUSH-2062: without this, a reachable host never skipped SSH
- * even when the cache was just written.
- */
 export declare function serveWarmRemoteCache(host: string, forwardedArgs: string[], opts?: {
     maxAgeMs?: number;
     nowMs?: number;
 }): boolean;
-/** Replay a cached fetch for an unreachable host (any age). Banner goes to
- * stderr (so a piped stdout stays exactly the cached rows); returns false when
- * nothing is cached for this exact (host, query). */
 export declare function replayRemoteCache(host: string, forwardedArgs: string[]): boolean;
 interface RunRemoteSessionsOptions {
-    /** Skip warm cache and SSH every host (force-refresh). */
     forceRefresh?: boolean;
-    /** Override freshness window for the warm path. */
     maxAgeMs?: number;
-    /** Clock (tests). */
     nowMs?: number;
 }
-/**
- * Run the current `agents sessions` invocation on one or more remote machines over
- * SSH, writing each remote's output to the terminal.
- *
- * Cache policy (RUSH-2062):
- * - **Default:** serve a fresh cache hit without SSH; SSH only on miss/stale.
- * - **`forceRefresh`:** always SSH, then rewrite the cache.
- * - **Unreachable:** fall back to any cached output (with a stale banner).
- *
- * Sets `process.exitCode = 1` if any host could not be answered (live or cached).
- * Reads the invocation from `process.argv` (override via `argv` for testing).
- *
- * Output is captured rather than `stdio: 'inherit'`-streamed so it can be cached.
- * Session output is small and the remote returns quickly, so buffering is
- * imperceptible; `maxBuffer` is generous for the rare large `--markdown <id>` dump.
- */
 export declare function runRemoteSessions(hosts: string[], argv?: string[], opts?: RunRemoteSessionsOptions): void;
 export {};

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

@@ -34,42 +34,21 @@ import { resolveRemoteOsSync } from '../../hosts/remote-os.js';
 import { NO_FANOUT_ENV } from '../remote-active.js';
 import { formatRelativeTime } from '../../text/relative-time.js';
 import { terminalWidth } from '../../text/width.js';
-/**
- * POSIX single-quote a string for safe interpolation into a remote shell command.
- * Always wraps (unlike the bare-passthrough variant in `ssh-exec.ts`) — the
- * forwarded `agents` argv is embedded verbatim inside `bash -lc '<cmd>'`, so
- * every token is quoted to keep the command boundary unambiguous.
- */
 export function shellQuote(s) {
     return `'${s.replace(/'/g, `'\\''`)}'`;
 }
-/**
- * Strip the `--device`/`-D` flag (and its value) from a raw `agents sessions` argv,
- * leaving the args to forward to the remote unchanged. The remote runs the same
- * binary, so every other flag (`--since`, `--last`, `--json`, query, …) carries
- * over for free. Handles every form commander accepts: `--device h`, `--device=h`,
- * `-D h`, `-D=h`, and the glued short form `-Dh`.
- *
- * @param argv full process argv; the sessions args begin at index 2
- *             (`[runtime, script, 'sessions', ...]`).
- */
 export function buildForwardedArgs(argv, hosts = new Set()) {
     const args = argv.slice(2);
     const out = [];
     for (let i = 0; i < args.length; i++) {
         const a = args[i];
         if (a === '--device' || a === '--devices') {
-            // Commander's `<target...>` variadic accepts both `--device a --device b`
-            // and `--device a b` — consume every consecutive token that is a known host
-            // so the variadic form doesn't leak the extra hosts into the remote argv.
-            // Fall back to consuming the single next token when we have no host set
-            // (e.g. malformed input) so the flag value never leaks either way.
             if (hosts.size > 0) {
                 while (i + 1 < args.length && hosts.has(args[i + 1]))
                     i++;
             }
             else {
-                i++; // also consume the separate value token
+                i++;
             }
             continue;
         }
@@ -79,38 +58,10 @@ export function buildForwardedArgs(argv, hosts = new Set()) {
     }
     return out;
 }
-/**
- * Force a forwarded `agents sessions` listing to span the peer's WHOLE index.
- *
- * A remote listing runs in the peer's SSH-login cwd — its home dir — and the
- * default listing is silently cwd-scoped, so `sessions --device box` reads as
- * empty even when the box's index is full (`No sessions found for /home/<user>`).
- * Across SSH a peer's cwd is meaningless, so `--device` defaults to `--all`
- * (whole-index) scope. This only drops the *cwd* narrowing — an explicit path
- * query, `--project`, `--since`, or `--agent` filter still narrows on top, and
- * a query that looks like a path takes precedence over `--all` on the remote.
- * Idempotent: never adds a second `--all`.
- */
 export function ensureWholeIndex(forwardedArgs) {
     return forwardedArgs.includes('--all') ? forwardedArgs : [...forwardedArgs, '--all'];
 }
-/**
- * Build the single remote command string for `ssh <host> <cmd>`. Forwarded args
- * are quoted for the inner login shell, then the whole `agents …` invocation is
- * quoted again so it survives `bash -lc <...>`.
- *
- * `os` selects the remote shell: a Windows host gets a PowerShell invocation
- * (ssh lands in cmd.exe/PowerShell there, where `bash -lc` does not exist);
- * anything else — including unknown/absent — keeps the POSIX form unchanged.
- * The forwarded terminal width rides across as an env var either way so the
- * remote renders its table to the local screen.
- */
 export function buildRemoteCommand(forwardedArgs, columns, os) {
-    // `--device <box>` means "that box's own sessions" — so the peer must answer for
-    // ITSELF and not re-sweep its fleet. Without this the remote `agents sessions`
-    // fans back out to every device IT knows (including us), printing a spurious
-    // `<this-machine>: unreachable`. AGENTS_SESSIONS_LOCAL=1 pins the peer local,
-    // matching the JSON fan-out path (`remote-list.ts`).
     if (remoteShellFor(os) === 'powershell') {
         const env = { [NO_FANOUT_ENV]: '1' };
         if (columns && columns > 0)
@@ -118,19 +69,9 @@ export function buildRemoteCommand(forwardedArgs, columns, os) {
         return buildWindowsAgentsCommand({ args: forwardedArgs, env });
     }
     const inner = ['agents', ...forwardedArgs].map(shellQuote).join(' ');
-    // Forward the caller's terminal width so the remote renders the table to the
-    // local screen (over SSH the remote's own COLUMNS is unset/wrong). `VAR=val
-    // cmd` scopes the env to that process — the remote's terminalWidth() reads it.
     const envPrefix = `${NO_FANOUT_ENV}=1` + (columns && columns > 0 ? ` COLUMNS=${columns}` : '');
     return `bash -lc ${shellQuote(`${envPrefix} ${inner}`)}`;
 }
-/**
- * Classify an ssh `spawnSync` result. ssh(1) reserves exit 255 for its own
- * connection-layer failures (host down, timeout, refused, auth, changed host
- * key) — distinct from any other non-zero, which is the remote `agents sessions`
- * exit code forwarded back (the query ran but failed). The two must be handled
- * differently: 255 may fall back to cache, a forwarded failure must surface.
- */
 export function classifySshFailure(res) {
     if (res.error)
         return 'spawn-error';
@@ -140,38 +81,18 @@ export function classifySshFailure(res) {
         return 'unreachable';
     return 'query-failed';
 }
-/** Root of the offline-replay cache (`~/.agents/.cache/remote-sessions/`). */
 const REMOTE_CACHE_DIR = join(getCacheDir(), 'remote-sessions');
-/**
- * How long a successful remote fetch may be served without re-SSHing.
- * Short on purpose: session listings must stay near-live (RUSH-2062). Match the
- * active-session snapshot window so surfaces share one freshness model.
- */
 export const REMOTE_CACHE_MAX_AGE_MS = 15_000;
-/**
- * Deterministic cache path for a (host, forwarded-args) pair. The forwarded args
- * are hashed so distinct queries cache independently; the host stays readable in
- * the filename (sanitised so `user@host` and aliases are filesystem-safe).
- */
 export function remoteCachePath(host, forwardedArgs) {
     const hash = createHash('sha256').update(forwardedArgs.join('\u0000')).digest('hex').slice(0, 16);
     const safeHost = host.replace(/[^a-zA-Z0-9._@-]/g, '_');
     return join(REMOTE_CACHE_DIR, `${safeHost}__${hash}.txt`);
 }
-/**
- * Pure freshness check for a remote-sessions cache entry. A reachable host
- * skips SSH only while this returns true; unreachable fallback ignores age.
- */
 export function isRemoteCacheFresh(mtimeMs, nowMs, maxAgeMs = REMOTE_CACHE_MAX_AGE_MS) {
     if (!Number.isFinite(mtimeMs) || !Number.isFinite(maxAgeMs) || maxAgeMs < 0)
         return false;
     return nowMs - mtimeMs <= maxAgeMs;
 }
-/**
- * Read a cached remote fetch. When `maxAgeMs` is set, returns null if the
- * entry is older than the window (cache-first path for reachable hosts).
- * Omit `maxAgeMs` to accept any age (unreachable fallback).
- */
 export function readRemoteCache(host, forwardedArgs, opts = {}) {
     try {
         const p = remoteCachePath(host, forwardedArgs);
@@ -189,32 +110,21 @@ export function readRemoteCache(host, forwardedArgs, opts = {}) {
         return null;
     }
 }
-/** Banner shown above replayed cache rows when the peer is offline. */
 export function formatStaleBanner(host, mtimeMs) {
     const ago = formatRelativeTime(new Date(mtimeMs).toISOString());
     return chalk.yellow(`${host}: offline — showing cached results from ${ago}`);
 }
-/** Message shown when a host is unreachable and there is no cache to fall back to. */
 export function formatUnreachable(host) {
     return chalk.red(`${host}: unreachable over SSH (asleep, offline, or host key changed?) — ConnectTimeout 10s`);
 }
-/** Persist a successful fetch for later cache-first / offline replay.
- * Best-effort: a cache write must never break the live query. Exported for tests. */
 export function writeRemoteCache(host, forwardedArgs, output) {
     try {
         mkdirSync(REMOTE_CACHE_DIR, { recursive: true });
         writeFileSync(remoteCachePath(host, forwardedArgs), output);
     }
     catch {
-        // ignore — caching is an optimisation, not a guarantee
     }
 }
-/**
- * Serve a *fresh* cache entry for a reachable-host skip (no banner — the data
- * is still within the freshness window). Returns false when missing/stale so
- * the caller SSHes. RUSH-2062: without this, a reachable host never skipped SSH
- * even when the cache was just written.
- */
 export function serveWarmRemoteCache(host, forwardedArgs, opts = {}) {
     const hit = readRemoteCache(host, forwardedArgs, {
         maxAgeMs: opts.maxAgeMs ?? REMOTE_CACHE_MAX_AGE_MS,
@@ -225,36 +135,17 @@ export function serveWarmRemoteCache(host, forwardedArgs, opts = {}) {
     process.stdout.write(hit.output);
     return true;
 }
-/** Replay a cached fetch for an unreachable host (any age). Banner goes to
- * stderr (so a piped stdout stays exactly the cached rows); returns false when
- * nothing is cached for this exact (host, query). */
 export function replayRemoteCache(host, forwardedArgs) {
-    const hit = readRemoteCache(host, forwardedArgs); // no maxAge — any age ok
+    const hit = readRemoteCache(host, forwardedArgs);
     if (!hit)
         return false;
     process.stderr.write(formatStaleBanner(host, hit.mtimeMs) + '\n');
     process.stdout.write(hit.output);
     return true;
 }
-/**
- * Run the current `agents sessions` invocation on one or more remote machines over
- * SSH, writing each remote's output to the terminal.
- *
- * Cache policy (RUSH-2062):
- * - **Default:** serve a fresh cache hit without SSH; SSH only on miss/stale.
- * - **`forceRefresh`:** always SSH, then rewrite the cache.
- * - **Unreachable:** fall back to any cached output (with a stale banner).
- *
- * Sets `process.exitCode = 1` if any host could not be answered (live or cached).
- * Reads the invocation from `process.argv` (override via `argv` for testing).
- *
- * Output is captured rather than `stdio: 'inherit'`-streamed so it can be cached.
- * Session output is small and the remote returns quickly, so buffering is
- * imperceptible; `maxBuffer` is generous for the rare large `--markdown <id>` dump.
- */
 export function runRemoteSessions(hosts, argv = process.argv, opts = {}) {
     for (const host of hosts)
-        assertValidSshTarget(host); // fail fast on any bad target
+        assertValidSshTarget(host);
     const forwarded = ensureWholeIndex(buildForwardedArgs(argv, new Set(hosts)));
     const cols = terminalWidth();
     const multi = hosts.length > 1;
@@ -264,15 +155,12 @@ export function runRemoteSessions(hosts, argv = process.argv, opts = {}) {
     for (const host of hosts) {
         if (multi)
             process.stdout.write(chalk.cyan(`\n── ${host} ──\n`));
-        // Cache-first: a warm hit skips SSH entirely so reachable hosts share one
-        // snapshot across menubar/CLI/watchdog instead of re-fanning every call.
         if (!forceRefresh && serveWarmRemoteCache(host, forwarded, {
             maxAgeMs: opts.maxAgeMs,
             nowMs: opts.nowMs,
         })) {
             continue;
         }
-        // Per-host: a Windows peer needs a PowerShell command, POSIX peers `bash -lc`.
         const remoteCmd = buildRemoteCommand(forwarded, cols, resolveRemoteOsSync(host));
         const res = spawnSync('ssh', [...SSH_OPTS, ...controlOpts(), host, remoteCmd], {
             encoding: 'utf8',
@@ -286,8 +174,6 @@ export function runRemoteSessions(hosts, argv = process.argv, opts = {}) {
                 writeRemoteCache(host, forwarded, res.stdout ?? '');
                 break;
             case 'unreachable':
-                // Served-from-cache counts as answered (degraded, but with data + a clear
-                // banner), so it does not increment failures. No cache → a real failure.
                 if (!replayRemoteCache(host, forwarded)) {
                     failures++;
                     console.error(formatUnreachable(host));
@@ -298,8 +184,6 @@ export function runRemoteSessions(hosts, argv = process.argv, opts = {}) {
                 console.error(chalk.red(`${host}: ${res.error?.message ?? 'failed to launch ssh'}`));
                 break;
             case 'query-failed':
-                // The remote ran but its query exited non-zero — surface its own output
-                // and exit code; never mask a genuine error with stale cache.
                 failures++;
                 if (res.stdout)
                     process.stdout.write(res.stdout);