@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/registry.js

@@ -1,10 +1,3 @@
-/**
- * Package registry client -- search, resolve, and install from remote registries.
- *
- * Queries the MCP registry (registry.modelcontextprotocol.io) and future skill
- * registries to find packages, then resolves them into installable entries
- * with transport, runtime, and argument metadata.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import { createHash } from 'crypto';
@@ -26,22 +19,6 @@ export function validatedPyPISpec(spec) {
     }
     return spec;
 }
-/**
- * Seeded presets offered for `type`, minus any the user has removed.
- *
- * These are resolved here rather than written into agents.yaml. Seeding used to
- * happen on the state READ path and persisted the entry — but agents.yaml is
- * git-tracked in the user's DotAgents repo, so that write left the working tree
- * dirty and every `agents repo pull` aborted with "Working tree has uncommitted
- * changes", naming neither the file nor the cause. Since every `agents`
- * invocation reads state, the dirt returned the instant it was cleared, and the
- * loop could not be escaped through the CLI at all (RUSH-1925).
- *
- * `seededPresets` is the removal tombstone: a key listed there means the user
- * removed that preset, so it is not offered again. Users who were seeded under
- * the old behaviour have the key listed *and* the entry in their own
- * `registries:` block, which still wins below — so nothing disappears for them.
- */
 function offeredSeeds(type, meta) {
     const removed = new Set(meta.seededPresets || []);
     const offered = {};
@@ -51,22 +28,18 @@ function offeredSeeds(type, meta) {
     }
     return offered;
 }
-/** Get all registries of a given type, merging defaults with user overrides. */
 export function getRegistries(type) {
     const meta = readMeta();
     const defaultRegs = DEFAULT_REGISTRIES[type] || {};
     const userRegs = meta.registries?.[type] || {};
-    // Merge defaults with user config (user overrides defaults)
     return { ...defaultRegs, ...offeredSeeds(type, meta), ...userRegs };
 }
-/** Get only the enabled registries of a given type. */
 export function getEnabledRegistries(type) {
     const registries = getRegistries(type);
     return Object.entries(registries)
         .filter(([, config]) => config.enabled)
         .map(([name, config]) => ({ name, config }));
 }
-/** Add or update a registry configuration in agents.yaml. */
 export function setRegistry(type, name, config) {
     const meta = readMeta();
     if (!meta.registries) {
@@ -75,24 +48,15 @@ export function setRegistry(type, name, config) {
     if (!meta.registries[type]) {
         meta.registries[type] = {};
     }
-    // Seeded presets are resolved in memory and never materialized in agents.yaml
-    // (see offeredSeeds), so a partial update — `registry disable`, `enable`, or
-    // `config --api-key` — has nothing stored to merge with. Without the
-    // SEEDED_REGISTRIES fallback it would persist only the changed fields and drop
-    // `url`, and because userRegs wins over the in-memory seed in getRegistries the
-    // preset would stay broken even after re-enabling.
     const existing = meta.registries[type][name]
         || DEFAULT_REGISTRIES[type]?.[name]
         || SEEDED_REGISTRIES[type]?.[name];
     meta.registries[type][name] = { ...existing, ...config };
     writeMeta(meta);
 }
-/** Remove a user-configured or seeded registry. Returns false if it did not exist. */
 export function removeRegistry(type, name) {
     const meta = readMeta();
     const inUserConfig = !!meta.registries?.[type]?.[name];
-    // A seeded preset has no entry in agents.yaml until the user edits it, so
-    // removal is recorded as a tombstone in seededPresets instead of a deletion.
     const isOfferedSeed = !!offeredSeeds(type, meta)[name];
     if (!inUserConfig && !isOfferedSeed)
         return false;
@@ -104,12 +68,6 @@ export function removeRegistry(type, name) {
     writeMeta(meta);
     return true;
 }
-/**
- * Cap every registry network call. Without this a slow or unreachable registry
- * hangs the calling command indefinitely (`agents add`, `agents mcp`, package
- * resolution) — and makes CI flake when the registry is unreachable. On timeout
- * the fetch aborts, callers fall back to their git/no-match path.
- */
 const REGISTRY_FETCH_TIMEOUT_MS = 8000;
 async function fetchMcpRegistry(url, query, limit = 20, apiKey) {
     const params = new URLSearchParams();
@@ -132,7 +90,6 @@ async function fetchMcpRegistry(url, query, limit = 20, apiKey) {
     }
     return response.json();
 }
-/** Search MCP registries for servers matching a query string. */
 export async function searchMcpRegistries(query, options) {
     const registries = getEnabledRegistries('mcp');
     const results = [];
@@ -160,32 +117,15 @@ export async function searchMcpRegistries(query, options) {
             }
         }
         catch (err) {
-            // Log but continue with other registries
             console.error(`Failed to search ${name}: ${err.message}`);
         }
     }
     return results;
 }
-/**
- * Convert an MCP server registry entry into an install spec suitable for
- * writing into `manifest.mcp`. Returns `null` if the entry has no package we
- * know how to launch (e.g. only remote endpoints, which the current manifest
- * shape supports via `url`+`transport: 'http'` but isn't yet wired to the
- * registry's `remotes` field).
- *
- * Supported package shapes:
- *   - npm / runtime=node      → `npx -y <name>`
- *   - pypi / runtime=python   → `uvx <name>`
- *   - runtime=docker          → `docker run --rm -i <name>`
- *   - runtime=binary          → `<name>` (assumed to be on PATH)
- */
 export function mcpEntryToInstallSpec(entry) {
     const pkg = entry.packages?.[0];
     if (!pkg)
         return null;
-    // Remote transports (sse / streamable-http) need a URL the registry doesn't
-    // currently expose in this client's type. Skip for now; caller can fall back
-    // to manual --transport http with an explicit URL.
     if (pkg.transport === 'sse' || pkg.transport === 'streamable-http') {
         return null;
     }
@@ -206,11 +146,8 @@ export function mcpEntryToInstallSpec(entry) {
     if (runtime === 'binary') {
         return { command: name, transport: 'stdio' };
     }
-    // Unknown registry/runtime — fall back to bare name so the user gets *something*
-    // to inspect via `agents mcp view`, rather than a silent miss.
     return { command: name, transport: 'stdio' };
 }
-/** Look up detailed info for an MCP server by exact name. */
 export async function getMcpServerInfo(serverName, registryName) {
     const registries = getEnabledRegistries('mcp');
     const targetRegistries = registryName
@@ -218,9 +155,7 @@ export async function getMcpServerInfo(serverName, registryName) {
         : registries;
     for (const { config } of targetRegistries) {
         try {
-            // Search with exact name
             const response = await fetchMcpRegistry(config.url, serverName, 10, config.apiKey);
-            // Find exact match
             const match = response.servers.find(({ server }) => server.name === serverName ||
                 server.name.endsWith(`/${serverName}`));
             if (match) {
@@ -228,14 +163,12 @@ export async function getMcpServerInfo(serverName, registryName) {
             }
         }
         catch {
-            // Continue to next registry
         }
     }
     return null;
 }
 const skillIndexCache = new Map();
 const SKILL_INDEX_TTL_MS = 10 * 60_000;
-/** Fetch and cache a flat skill-index JSON document. */
 async function fetchSkillIndex(url, apiKey) {
     const cached = skillIndexCache.get(url);
     if (cached && Date.now() - cached.fetchedAt < SKILL_INDEX_TTL_MS) {
@@ -255,7 +188,6 @@ async function fetchSkillIndex(url, apiKey) {
     skillIndexCache.set(url, { fetchedAt: Date.now(), doc });
     return doc;
 }
-/** Map a raw skill-index row into the canonical SkillEntry shape. */
 export function normalizeSkillEntry(raw) {
     return {
         name: raw.name,
@@ -271,7 +203,6 @@ export function normalizeSkillEntry(raw) {
         sha256: raw.sha256,
     };
 }
-/** Case-insensitive substring match against the fields users expect to search. */
 function skillMatchesQuery(entry, query) {
     if (!query)
         return true;
@@ -288,7 +219,6 @@ function skillMatchesQuery(entry, query) {
         .toLowerCase();
     return haystack.includes(q);
 }
-/** Search skill registries for entries matching a query string. */
 export async function searchSkillRegistries(query, options) {
     const registries = getEnabledRegistries('skill');
     if (registries.length === 0)
@@ -331,7 +261,6 @@ export async function searchSkillRegistries(query, options) {
     }
     return results;
 }
-/** Look up a skill by identifier (or name) across enabled skill registries. */
 export async function getSkillEntry(skillIdentifier, registryName) {
     const registries = getEnabledRegistries('skill');
     const targets = registryName
@@ -345,26 +274,19 @@ export async function getSkillEntry(skillIdentifier, registryName) {
                 return normalizeSkillEntry(match);
         }
         catch {
-            /* try next registry */
         }
     }
     return null;
 }
-/** Derive a cloneable git source from a skill entry's repo/source metadata. */
 export function skillEntryToGitSource(entry) {
     if (entry.repo) {
-        // Already an owner/repo; cloneRepo understands the `gh:` shorthand.
         return `gh:${entry.repo.replace(/\.git$/, '')}`;
     }
     if (entry.source === 'official') {
-        // Hermes 'official' entries live in NousResearch/hermes-agent; the path
-        // sits under optional-skills/. cloneRepo pulls the whole repo — the
-        // per-path narrowing is a follow-on improvement.
         return 'gh:NousResearch/hermes-agent';
     }
     return null;
 }
-/** Unified search across all enabled registries of the specified type(s). */
 export async function search(query, options) {
     const results = [];
     if (!options?.type || options.type === 'mcp') {
@@ -377,44 +299,33 @@ export async function search(query, options) {
     }
     return results;
 }
-/** Parse a package identifier into its type (mcp, skill, git) and name. */
 export function parsePackageIdentifier(identifier) {
-    // mcp:filesystem -> MCP registry
     if (identifier.startsWith('mcp:')) {
         return { type: 'mcp', name: identifier.slice(4) };
     }
-    // skill:user/repo -> skill registry (or git fallback)
     if (identifier.startsWith('skill:')) {
         return { type: 'skill', name: identifier.slice(6) };
     }
-    // plugin:name@source | plugin:/path | plugin:gh:user/repo — Phase 5 packaging
-    // umbrella. Spec after the prefix is the same grammar as `agents plugins install`.
     if (identifier.startsWith('plugin:')) {
         return { type: 'plugin', name: identifier.slice('plugin:'.length) };
     }
-    // gh:user/repo -> git source
     if (identifier.startsWith('gh:')) {
         return { type: 'git', name: identifier };
     }
-    // https://... or git@... -> git source
     if (identifier.startsWith('https://') || identifier.startsWith('git@')) {
         return { type: 'git', name: identifier };
     }
-    // Local repo/path
     if (identifier.startsWith('/') ||
         identifier.startsWith('./') ||
         identifier.startsWith('../') ||
         fs.existsSync(identifier)) {
         return { type: 'git', name: identifier };
     }
-    // user/repo format -> could be either, need to search
     if (identifier.includes('/') && !identifier.includes(':')) {
         return { type: 'unknown', name: identifier };
     }
-    // Single word -> search MCP registries first
     return { type: 'unknown', name: identifier };
 }
-/** Resolve a package identifier to an installable package with source metadata. */
 export async function resolvePackage(identifier) {
     const parsed = parsePackageIdentifier(identifier);
     if (parsed.type === 'plugin') {
@@ -448,16 +359,12 @@ export async function resolvePackage(identifier) {
                     skillEntry: entry,
                 };
             }
-            // Entry found but has no installable repo (e.g. lobehub-only listings).
             return null;
         }
-        // Fall back to git shorthand when the identifier isn't in any registry.
         const gitSource = parsed.name.startsWith('gh:') ? parsed.name : `gh:${parsed.name}`;
         return { type: 'git', source: gitSource };
     }
-    // Unknown type - search registries
     if (parsed.type === 'unknown') {
-        // Try MCP first
         const mcpEntry = await getMcpServerInfo(parsed.name);
         if (mcpEntry) {
             return {
@@ -466,47 +373,20 @@ export async function resolvePackage(identifier) {
                 mcpEntry,
             };
         }
-        // If it looks like a git path (user/repo), treat as git
         if (parsed.name.includes('/')) {
             return { type: 'git', source: `gh:${parsed.name}` };
         }
     }
     return null;
 }
-// ============================================================================
-// PUBLISH — generate a self-hosted skill index + verify integrity on install
-// ============================================================================
-/** Lowercase hex sha256 of a file's bytes. Small files only (SKILL.md). */
 export function sha256OfFile(file) {
     return createHash('sha256').update(fs.readFileSync(file)).digest('hex');
 }
-/**
- * Parse an 'owner/repo' slug from a git remote URL (https or scp-style ssh) or
- * a filesystem-path remote whose path is slug-shaped (`…/github.com/owner/repo`).
- * Returns null if the remote is not a recognizable GitHub-style shape.
- *
- * Backslashes are folded to forward slashes first: a real git URL never
- * contains one, but a local-path remote on Windows does
- * (`C:\…\github.com\org\a.git`), and without the fold the same remote that
- * parses as `org/a` on POSIX returns null on win32 — which made the
- * projects-pull slug verification fail closed as `blocked` there (RUSH-2694).
- */
 export function parseOwnerRepoFromRemote(remoteUrl) {
     const s = remoteUrl.trim().replace(/\\/g, '/').replace(/\.git$/, '');
-    // https://github.com/owner/repo  or  git@github.com:owner/repo
     const m = s.match(/github\.com[/:]([^/]+\/[^/]+)$/);
     return m ? m[1] : null;
 }
-/**
- * Walk a repo's skills/ and build a flat {@link SkillIndexDocument}. Each entry
- * carries the sha256 of its SKILL.md so install can verify integrity after
- * cloning.
- *
- * `repoSlug` is the 'owner/repo' the skills are published under, written into
- * each entry's `repo` field so {@link skillEntryToGitSource} resolves it to
- * `gh:owner/repo`. `identifier` is set to the skill's directory name so
- * `agents install skill:<name>` resolves against this index.
- */
 export function buildSkillIndex(repoPath, repoSlug, opts) {
     const discovered = discoverSkillsFromRepo(repoPath);
     const skills = discovered.map((s) => ({
@@ -526,13 +406,6 @@ export function buildSkillIndex(repoPath, repoSlug, opts) {
         skills,
     };
 }
-/**
- * Verify a cloned skill's SKILL.md against the sha256 recorded in its registry
- * entry. Returns ok when the entry carries no sha256 — indexes published before
- * integrity hashes (or by third parties) simply skip the check. Returns an
- * error when the file is missing or its hash differs, so install can abort
- * rather than silently trusting a tampered artifact.
- */
 export function verifySkillIntegrity(repoPath, entry) {
     if (!entry.sha256)
         return { ok: true };

package/dist/lib/reminders.d.ts

@@ -1,29 +1,8 @@
 export interface Reminder {
-    /** Succinct form shown in the statusline (a few words). */
     short: string;
-    /** Full principle, shown by `agents reminders`. Falls back to `short`. */
     full: string;
 }
-/**
- * Point the reminders file at a fixture for tests, mirroring
- * `setClaudeUsageCachePathForTest` in accounting/usage.ts. Returns the prior
- * override so a test can restore it. Pass `null` to clear.
- */
 export declare function setRemindersFilePathForTest(filePath: string | null): string | null;
 export declare function remindersFilePath(): string;
-/**
- * Load reminders from disk.
- *
- * Returns `[]` when the file does not exist — the feature is simply not opted
- * in. Throws on a present-but-malformed file so `agents reminders` can surface
- * the problem; the statusline caller deliberately swallows that, because a
- * broken prompt is worse than a missing reminder line.
- */
 export declare function loadReminders(filePath?: string): Reminder[];
-/**
- * Deterministically pick one reminder for a session. Same `sessionId` always
- * maps to the same reminder, so it is stable within a session; different session
- * ids spread across the list, so concurrent agents show different reminders.
- * Returns `null` when there are no reminders.
- */
 export declare function pickReminderForSession(reminders: Reminder[], sessionId?: string): Reminder | null;

package/dist/lib/reminders.js

@@ -1,23 +1,8 @@
-/**
- * Personal operating reminders.
- *
- * A small, user-owned list of principles kept in
- * `~/.agents/reminders/reminders.yaml` and surfaced succinctly in the Claude
- * statusline — one per session, chosen deterministically from the session id so
- * concurrent agents each show a different one and it stays stable within a
- * session. Presence of the file with at least one entry is the opt-in; there is
- * no separate flag. The file syncs across the fleet via `agents repo push/pull`.
- */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { parse as parseYaml } from 'yaml';
 import { getUserAgentsDir } from './state.js';
 let remindersFilePathOverride = null;
-/**
- * Point the reminders file at a fixture for tests, mirroring
- * `setClaudeUsageCachePathForTest` in accounting/usage.ts. Returns the prior
- * override so a test can restore it. Pass `null` to clear.
- */
 export function setRemindersFilePathForTest(filePath) {
     const prev = remindersFilePathOverride;
     remindersFilePathOverride = filePath;
@@ -29,14 +14,6 @@ export function remindersFilePath() {
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
-/**
- * Load reminders from disk.
- *
- * Returns `[]` when the file does not exist — the feature is simply not opted
- * in. Throws on a present-but-malformed file so `agents reminders` can surface
- * the problem; the statusline caller deliberately swallows that, because a
- * broken prompt is worse than a missing reminder line.
- */
 export function loadReminders(filePath = remindersFilePath()) {
     let raw;
     try {
@@ -64,12 +41,6 @@ export function loadReminders(filePath = remindersFilePath()) {
     }
     return reminders;
 }
-/**
- * Deterministically pick one reminder for a session. Same `sessionId` always
- * maps to the same reminder, so it is stable within a session; different session
- * ids spread across the list, so concurrent agents show different reminders.
- * Returns `null` when there are no reminders.
- */
 export function pickReminderForSession(reminders, sessionId) {
     if (reminders.length === 0)
         return null;
@@ -77,7 +48,6 @@ export function pickReminderForSession(reminders, sessionId) {
     const index = key ? hashString(key) % reminders.length : 0;
     return reminders[index];
 }
-/** FNV-1a 32-bit — stable, dependency-free, well-distributed for short ids. */
 function hashString(value) {
     let hash = 0x811c9dc5;
     for (let i = 0; i < value.length; i++) {

package/dist/lib/remote-agents-json.d.ts

@@ -3,34 +3,12 @@ interface RemoteAgentsJsonOptions<T> {
     noFanoutEnv: string;
     hosts?: string[];
     parse: (stdout: string, machine: string) => T[] | RemoteAgentsJsonParseResult<T>;
-    /**
-     * Suppress the per-device "unreachable — skipped" stderr line. The skipped
-     * names still come back in {@link RemoteAgentsJsonResult.skipped}, so a caller
-     * that fans out by DEFAULT can report them once, compactly, instead of
-     * printing a line per offline box above its output. Never a silent drop.
-     */
     quiet?: boolean;
-    /** Per-peer deadline. Long-running maintenance commands override 12 seconds. */
     timeoutMs?: number;
-    /**
-     * Opt-in early-exit for a globally-unique lookup (a full session UUID). When a
-     * peer returns an item that satisfies {@link isDefinitive}, the fan-out
-     * resolves immediately and SIGTERMs every still-outstanding peer instead of
-     * waiting for the slowest one to hit {@link REMOTE_TIMEOUT_MS}.
-     *
-     * OMITTED BY DEFAULT — tool-search, program-count, and the default session
-     * listing keep the all-settle behavior (ambiguity, or a label/prefix conflict,
-     * is only known once every peer has answered). Only the full-UUID resolve path
-     * opts in, since only a UUID guarantees the first hit is the only hit.
-     */
     earlyExit?: {
         isDefinitive: (item: T, machine: string) => boolean;
     };
 }
-/**
- * The SSH boundary as a swappable dependency so the fan-out logic is testable
- * without a live tailnet. Production wires this to the real {@link sshCapture}.
- */
 export type SshCaptureFn = (target: string, remoteCmd: string, opts: {
     timeoutMs: number;
     signal?: AbortSignal;
@@ -49,11 +27,8 @@ export interface RemoteAgentsJsonParseResult<T> {
 interface RemoteAgentsJsonResult<T> {
     items: T[];
     deviceCount: number;
-    /** Devices that were dialed but answered with an error / no CLI / a timeout. */
     skipped: string[];
-    /** Devices that exited successfully but returned invalid JSON for this command. */
     parseFailed: string[];
-    /** Whether automatic target discovery failed before any peer could be dialed. */
     discoveryFailed: boolean;
 }
 export declare function normalizeRemoteAgentsJsonParse<T>(parsed: T[] | RemoteAgentsJsonParseResult<T>): RemoteAgentsJsonParseResult<T>;
@@ -61,13 +36,7 @@ export declare function parseRemoteAgentsJsonPayload<T>(stdout: string, machine:
     items: T[];
     parseFailed: boolean;
 };
-/** Build the command one peer runs, with a guard that prevents recursive fan-out. */
 export declare function remoteAgentsJsonCommand(args: string[], noFanoutEnv: string, os?: string): string;
-/**
- * The subset of a spawned `ssh` child this capture loop drives. Structural so a
- * unit test can feed synthetic `data`/`close` events through a fake without a
- * live SSH connection.
- */
 export interface CapturableChild {
     stdout: {
         on(event: 'data', listener: (chunk: Buffer) => void): unknown;
@@ -75,18 +44,6 @@ export interface CapturableChild {
     on(event: 'error' | 'close', listener: (arg?: number | null) => void): unknown;
     kill(signal?: NodeJS.Signals): unknown;
 }
-/**
- * Stream one child's stdout into memory under a hard per-peer byte ceiling.
- *
- * A cross-machine fan-out awaits every peer's capture under one `Promise.all`,
- * so an unbounded buffer means a single runaway peer (a corrupt or
- * pathologically large payload) exhausts the caller's heap and takes the whole
- * sweep down — RUSH-2065. Once the accumulated bytes would exceed
- * {@link REMOTE_STDOUT_MAX_BYTES}, the child is SIGKILLed and the capture settles
- * as `code: null` (unreachable) rather than trust a truncated body. A definitive
- * early-exit `signal` SIGTERMs the child the same way, and the timer is the
- * per-peer deadline.
- */
 export declare function captureBoundedStdout(child: CapturableChild, { timeoutMs, signal }: {
     timeoutMs: number;
     signal?: AbortSignal;
@@ -94,6 +51,5 @@ export declare function captureBoundedStdout(child: CapturableChild, { timeoutMs
     code: number | null;
     stdout: string;
 }>;
-/** Query explicit hosts, or every registered online peer when hosts is omitted. */
 export declare function gatherRemoteAgentsJson<T>(options: RemoteAgentsJsonOptions<T>, deps?: GatherRemoteAgentsJsonDeps): Promise<RemoteAgentsJsonResult<T>>;
 export {};

package/dist/lib/remote-agents-json.js

@@ -1,11 +1,3 @@
-/**
- * Shared cross-machine fan-out for JSON-producing `agents` commands.
- *
- * Registered online devices are queried in parallel over the canonical SSH
- * transport. A recursion-guard environment variable makes each peer answer for
- * itself, and version-skewed or unreachable peers are skipped without hiding
- * healthy results from the rest of the fleet.
- */
 import { spawn } from 'child_process';
 import { setMaxListeners } from 'node:events';
 import chalk from 'chalk';
@@ -20,14 +12,11 @@ export function normalizeRemoteAgentsJsonParse(parsed) {
     return Array.isArray(parsed) ? { items: parsed, valid: true } : parsed;
 }
 export function parseRemoteAgentsJsonPayload(stdout, machine, parse) {
-    // A Windows peer can prefix the JSON with a PowerShell CLIXML banner; strip it
-    // before handing stdout to the command-specific parser (RUSH-2286).
     const parsed = normalizeRemoteAgentsJsonParse(parse(stripClixml(stdout), machine));
     return parsed.valid
         ? { items: parsed.items, parseFailed: false }
         : { items: [], parseFailed: true };
 }
-/** Build the command one peer runs, with a guard that prevents recursive fan-out. */
 export function remoteAgentsJsonCommand(args, noFanoutEnv, os) {
     if (remoteShellFor(os) === 'powershell') {
         return buildWindowsAgentsCommand({ args, env: { [noFanoutEnv]: '1' } });
@@ -35,18 +24,6 @@ export function remoteAgentsJsonCommand(args, noFanoutEnv, os) {
     const inner = `${noFanoutEnv}=1 agents ${args.map(shellQuote).join(' ')}`;
     return `bash -lc ${shellQuote(inner)}`;
 }
-/**
- * Stream one child's stdout into memory under a hard per-peer byte ceiling.
- *
- * A cross-machine fan-out awaits every peer's capture under one `Promise.all`,
- * so an unbounded buffer means a single runaway peer (a corrupt or
- * pathologically large payload) exhausts the caller's heap and takes the whole
- * sweep down — RUSH-2065. Once the accumulated bytes would exceed
- * {@link REMOTE_STDOUT_MAX_BYTES}, the child is SIGKILLed and the capture settles
- * as `code: null` (unreachable) rather than trust a truncated body. A definitive
- * early-exit `signal` SIGTERMs the child the same way, and the timer is the
- * per-peer deadline.
- */
 export function captureBoundedStdout(child, { timeoutMs, signal }) {
     return new Promise((resolve) => {
         const decoded = new RemoteUtf8Accumulator();
@@ -58,22 +35,15 @@ export function captureBoundedStdout(child, { timeoutMs, signal }) {
             settled = true;
             clearTimeout(timer);
             signal?.removeEventListener('abort', onAbort);
-            // A killed/aborted capture never cleanly ends its decoder; return what
-            // decoded so far (the caller treats a non-zero code as unreachable and
-            // ignores stdout anyway).
             resolve({ code, stdout: code === null ? decoded.current() : decoded.end() });
         };
         const timer = setTimeout(() => {
             child.kill('SIGKILL');
             done(null);
         }, timeoutMs);
-        // A definitive hit on a fast peer cancels the rest: SIGTERM the child so an
-        // unreachable peer is not left running to its full timeout.
         const onAbort = () => { child.kill('SIGTERM'); done(null); };
         signal?.addEventListener('abort', onAbort, { once: true });
         child.stdout?.on('data', (data) => {
-            // Over the ceiling, SIGKILL the child and treat it as unreachable rather
-            // than trust a partial payload — the RUSH-2065 OOM guard.
             if (stdoutBytes + data.byteLength > REMOTE_STDOUT_MAX_BYTES) {
                 child.kill('SIGKILL');
                 done(null);
@@ -94,7 +64,6 @@ const sshCapture = (target, remoteCmd, { timeoutMs, signal, extraSshArgs }) => {
     const child = spawn('ssh', args, { stdio: ['ignore', 'pipe', 'ignore'] });
     return captureBoundedStdout(child, { timeoutMs, signal });
 };
-/** Query explicit hosts, or every registered online peer when hosts is omitted. */
 export async function gatherRemoteAgentsJson(options, deps = {}) {
     const capture = deps.capture ?? sshCapture;
     const self = machineId();
@@ -111,8 +80,6 @@ export async function gatherRemoteAgentsJson(options, deps = {}) {
             return { items: [], deviceCount: 0, skipped: [], parseFailed: [], discoveryFailed: true };
         }
         for (const device of Object.values(devices)) {
-            // Live SSH-probe verdict first, cached tailscale snapshot only as a
-            // fallback — see isDialableDevice (mirrors session/remote-list.ts).
             if (!isDialableDevice(device))
                 continue;
             if (normalizeHost(device.name) === self)
@@ -129,19 +96,12 @@ export async function gatherRemoteAgentsJson(options, deps = {}) {
                 });
             }
             catch {
-                // A registered profile without a dialable address is not a peer yet.
             }
         }
     }
     const skipped = [];
     const parseFailed = [];
-    // The controller exists ONLY for early-exit: the first definitive hit aborts
-    // every still-outstanding peer. When earlyExit is not requested there is no
-    // controller and no per-peer abort listener, so the default path is a plain
-    // all-settle Promise.all, byte-identical to before (tool-search, program-count).
     const controller = options.earlyExit ? new AbortController() : undefined;
-    // A fleet can hold more peers than Node's default 10-listener cap; each peer's
-    // capture adds one abort listener, so lift the cap to avoid a spurious warning.
     if (controller)
         setMaxListeners(targets.length + 1, controller.signal);
     let earlyResolved = false;
@@ -152,9 +112,6 @@ export async function gatherRemoteAgentsJson(options, deps = {}) {
             signal: controller?.signal,
             extraSshArgs: target.extraSshArgs,
         });
-        // A peer we deliberately cancelled is neither a hit nor a failure — it never
-        // got to answer, so it must not pollute skipped/parseFailed (which drive the
-        // "unreachable" listing and the fail-closed partial-resolution gate).
         const cancelled = controller?.signal.aborted ?? false;
         if (result.code !== 0) {
             if (!cancelled) {
@@ -178,7 +135,7 @@ export async function gatherRemoteAgentsJson(options, deps = {}) {
         if (controller && options.earlyExit && !earlyResolved
             && parsed.items.some((item) => options.earlyExit.isDefinitive(item, target.machine))) {
             earlyResolved = true;
-            controller.abort(); // SIGTERM the remaining peers; they settle fast below.
+            controller.abort();
         }
         return parsed.items;
     }));