@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/hosts/routing-flag.js

@@ -1,16 +1,3 @@
-/**
- * Leaf argv helpers for host/device routing flags.
- *
- * Zero imports on purpose. `bootstrap.ts` gates the dynamic
- * `import('./lib/hosts/passthrough.js')` on {@link hasHostRoutingFlag} so the
- * ~187 ms passthrough module graph is never loaded when no routing flag is
- * present (the majority of CLI invocations). That gate must not itself drag
- * in passthrough, remote-cmd, ssh-exec, or the device registry (RUSH-2374).
- *
- * `flagValue` lives here (not in passthrough.ts) for the same reason: the gate
- * and the function body that later reads flag values share one implementation.
- */
-/** Pull the value of `--device`/`-D`/`--remote-cwd` (any form) out of an argv. */
 export function flagValue(args, long, short) {
     for (let i = 0; i < args.length; i++) {
         const a = args[i];
@@ -25,14 +12,6 @@ export function flagValue(args, long, short) {
     }
     return undefined;
 }
-/**
- * True when argv carries any device routing flag that {@link maybeRunOnHost}
- * inspects: `--device`/`-D`, `--hosts`, `--devices` (space, `=`, or
- * glued short form).
- *
- * Presence-only — does not validate values. Used by bootstrap before loading
- * passthrough, and by `maybeRunStandaloneOnHost` before strip/route work.
- */
 export function hasHostRoutingFlag(args) {
     return (flagValue(args, 'device', 'D') !== undefined ||
         flagValue(args, 'hosts') !== undefined ||

package/dist/lib/hosts/run-target.d.ts

@@ -1,62 +1,26 @@
-/**
- * Shared host-run dispatch — the one path every surface uses to run an agent on
- * another machine: `agents run --device` (commands/exec.ts), the `host` cloud
- * provider (`agents cloud run --provider host`), and host-placed routines.
- *
- * Wraps the two steps every caller needs and previously lived inline in
- * exec.ts's `--device` branch:
- *   1. resolution — name → capability tag → error, with the same fall-through
- *      semantics as `agents run --device` (only "Multiple hosts tagged…" is a
- *      resolution verdict; "no host tagged" degrades to unknown-host), and
- *   2. headless dispatch — session-id mint (Claude only), detached SSH launch,
- *      and LOCAL session-index registration so the run shows in `agents sessions`.
- *
- * Interactive dispatch stays in exec.ts: it is inherently tied to the caller's
- * TTY and has no other consumers.
- */
 import type { Host } from './types.js';
 import type { DispatchResult } from './dispatch.js';
 import type { HostCredentials } from './credentials.js';
-/**
- * Resolution failed with a user-actionable message the caller should print
- * verbatim. Distinct from `DeviceOffloadUnsupportedError` (which propagates to
- * the top-level catch) so callers can tell "bad name" from "bad auth method".
- */
 export declare class HostResolutionError extends Error {
     constructor(message: string);
 }
-/**
- * Resolve a `--device` value the way `agents run` does: exact name (providers →
- * devices → `user@host`), then capability tag. Throws `HostResolutionError`
- * for an ambiguous tag or an unknown name; lets `DeviceOffloadUnsupportedError`
- * (password-auth device) propagate untouched for the top-level catch.
- */
 export declare function resolveHostRunTarget(name: string, opts?: {
     any?: boolean;
 }): Promise<Host>;
 export interface HostPromptRun {
     agent: string;
     prompt: string;
-    /** Explicit agent version pin, forwarded as `agent@version`. */
     version?: string;
     mode?: string;
     model?: string;
-    /** Durable `--name <slug>` handle recorded on the task. */
     name?: string;
-    /** Resume an existing session on the host by concrete id. */
     resume?: string;
-    /** Explicit id for a new Claude session. */
     sessionId?: string;
-    /** Working directory on the host, already made remote-portable by the caller. */
     remoteCwd?: string;
-    /** `remoteCwd` was derived from the local cwd — mirror it, don't fail on it. */
     mirrorCwd?: boolean;
-    /** Stream progress and block until completion (default true). */
     follow?: boolean;
     timeoutMs?: number;
-    /** Local directory to record in the session index (defaults to process.cwd()). */
     cwd?: string;
-    /** Forwarded run options — see RUN_OPTION_FORWARDING in remote-cmd.ts. */
     effort?: string;
     env?: string[];
     addDir?: string[];
@@ -76,24 +40,7 @@ export interface HostPromptRun {
     acp?: boolean;
     autoSecrets?: boolean;
     passthroughArgs?: string[];
-    /** Copy runtime credentials to the host before the run and shred them after. */
     copyCreds?: HostCredentials;
 }
-/** Resolve the id the remote host will adopt for a fresh Claude session. */
 export declare function resolveHostSessionId(agent: string, resume?: string, sessionId?: string): string | undefined;
-/**
- * Dispatch a headless prompt run onto a resolved host, then relate the run's
- * session id back to this launcher for EVERY agent — not just Claude.
- *
- * Claude is the only agent that accepts a forced `--session-id`, so we mint one
- * up front and know it immediately. For every other agent the remote run coins
- * its OWN id; we forward `--emit-session-id` so the remote prints that id as a
- * stdout sentinel (hosts/session-marker.ts), and once the follow returns we parse
- * it out of the mirrored local log and stamp it on the task before registering —
- * so `agents sessions`/resume-by-id can map the discovered session home. On
- * resume the remote session keeps its existing id (passed through, no capture).
- *
- * Returns the task record and the remote exit code (`-1` = follow window closed
- * while the run continues).
- */
 export declare function dispatchPromptToHost(host: Host, opts: HostPromptRun): Promise<DispatchResult>;

package/dist/lib/hosts/run-target.js

@@ -1,40 +1,13 @@
-/**
- * Shared host-run dispatch — the one path every surface uses to run an agent on
- * another machine: `agents run --device` (commands/exec.ts), the `host` cloud
- * provider (`agents cloud run --provider host`), and host-placed routines.
- *
- * Wraps the two steps every caller needs and previously lived inline in
- * exec.ts's `--device` branch:
- *   1. resolution — name → capability tag → error, with the same fall-through
- *      semantics as `agents run --device` (only "Multiple hosts tagged…" is a
- *      resolution verdict; "no host tagged" degrades to unknown-host), and
- *   2. headless dispatch — session-id mint (Claude only), detached SSH launch,
- *      and LOCAL session-index registration so the run shows in `agents sessions`.
- *
- * Interactive dispatch stays in exec.ts: it is inherently tied to the caller's
- * TTY and has no other consumers.
- */
 import { randomUUID } from 'crypto';
 import { resolveHost, resolveHostByCap } from './registry.js';
 import { dispatchToHost } from './dispatch.js';
 import { registerHostSession, captureRemoteSessionId } from './session-index.js';
-/**
- * Resolution failed with a user-actionable message the caller should print
- * verbatim. Distinct from `DeviceOffloadUnsupportedError` (which propagates to
- * the top-level catch) so callers can tell "bad name" from "bad auth method".
- */
 export class HostResolutionError extends Error {
     constructor(message) {
         super(message);
         this.name = 'HostResolutionError';
     }
 }
-/**
- * Resolve a `--device` value the way `agents run` does: exact name (providers →
- * devices → `user@host`), then capability tag. Throws `HostResolutionError`
- * for an ambiguous tag or an unknown name; lets `DeviceOffloadUnsupportedError`
- * (password-auth device) propagate untouched for the top-level catch.
- */
 export async function resolveHostRunTarget(name, opts = {}) {
     let host = await resolveHost(name);
     if (!host) {
@@ -43,8 +16,6 @@ export async function resolveHostRunTarget(name, opts = {}) {
         }
         catch (e) {
             const msg = e.message ?? '';
-            // Ambiguity is a verdict, not a miss — surface it. "No host tagged"
-            // falls through to the generic unknown-host error below.
             if (msg.startsWith('Multiple hosts'))
                 throw new HostResolutionError(msg);
         }
@@ -53,42 +24,17 @@ export async function resolveHostRunTarget(name, opts = {}) {
         throw new HostResolutionError(`Unknown host "${name}". List devices: agents devices list`);
     return host;
 }
-/** Resolve the id the remote host will adopt for a fresh Claude session. */
 export function resolveHostSessionId(agent, resume, sessionId) {
     if (resume)
         return undefined;
     if (agent === 'claude')
         return sessionId ?? randomUUID();
-    // `run auto`: the harness is picked on the REMOTE. Forward an explicit id so
-    // a claude pick adopts it — but never mint one: minting would suppress the
-    // --emit-session-id marker a non-claude pick needs to register its session.
     if (agent === 'auto')
         return sessionId;
     return undefined;
 }
-/**
- * Dispatch a headless prompt run onto a resolved host, then relate the run's
- * session id back to this launcher for EVERY agent — not just Claude.
- *
- * Claude is the only agent that accepts a forced `--session-id`, so we mint one
- * up front and know it immediately. For every other agent the remote run coins
- * its OWN id; we forward `--emit-session-id` so the remote prints that id as a
- * stdout sentinel (hosts/session-marker.ts), and once the follow returns we parse
- * it out of the mirrored local log and stamp it on the task before registering —
- * so `agents sessions`/resume-by-id can map the discovered session home. On
- * resume the remote session keeps its existing id (passed through, no capture).
- *
- * Returns the task record and the remote exit code (`-1` = follow window closed
- * while the run continues).
- */
 export async function dispatchPromptToHost(host, opts) {
     const forcedSessionId = resolveHostSessionId(opts.agent, opts.resume, opts.sessionId);
-    // Ask the remote to print its resolved id whenever we did NOT force one (every
-    // non-Claude agent, and Claude-on-resume where the id is already known). No-op
-    // when the run isn't followed — nothing tails the log to catch the marker.
-    // `run auto` with an explicit --session-id is the exception: the id is only
-    // ADOPTED when the remote picks claude, so a non-claude pick must still emit
-    // the marker for its own coined id.
     const emitSessionId = (!forcedSessionId || opts.agent === 'auto') && !opts.resume && opts.follow !== false;
     const result = await dispatchToHost(host, {
         agent: opts.agent,
@@ -125,8 +71,6 @@ export async function dispatchPromptToHost(host, opts) {
         passthroughArgs: opts.passthroughArgs,
         copyCreds: opts.copyCreds,
     });
-    // Capture the remote-coined id from the followed log (non-Claude); harmlessly a
-    // no-op when the task already carries a forced/resumed id or no marker landed.
     const task = emitSessionId ? captureRemoteSessionId(result.task) ?? result.task : result.task;
     registerHostSession(task, { cwd: opts.cwd ?? process.cwd(), prompt: opts.prompt });
     return { ...result, task };

package/dist/lib/hosts/session-index.d.ts

@@ -1,57 +1,11 @@
-/**
- * Register host-dispatched runs (`agents run --device <h>`) into the LOCAL session
- * index so they show up in `agents sessions` and are resolvable by id — even
- * though the transcript itself lives on the remote host.
- *
- * The transcript file is remote, so the row is registered with an EMPTY
- * `file_path`. The DB's stale-row filter keeps rows with no file_path
- * (`!file_path || existsSync(file_path)` in db.ts querySessions) precisely for
- * this "synthetic file_path" case, and the scanner never prunes session rows —
- * so the entry survives rescans. `cwd` is the LOCAL directory the dispatch was
- * issued from, so the run appears in that project's session listing like any
- * local run. The `[host/<name>]` label mirrors the cloud path's
- * `[cloud/<status>]` convention.
- *
- * `machine` is the dispatch host, not this box. Both the transcript and the
- * version-isolated harness home live there; omitting it makes the SQLite upsert
- * infer this box from the empty file path and sends recovery to the wrong home.
- */
-import type { SessionMeta } from '../session/types.js';
+import type { SessionMeta } from '@phnx-labs/sessions-cli/reader';
 import { type HostTask } from './tasks.js';
 interface HostSessionContext {
-    /** Local directory the `agents run --device` was invoked from. */
     cwd: string;
-    /** Prompt the run was launched with, used for the session topic. */
     prompt: string;
 }
-/**
- * Build the SessionMeta for a host-dispatched run. Returns null when the run has
- * no captured session id (nothing stable to key/resume on) or its agent isn't a
- * known session agent. Pure — no I/O — so the mapping is unit-testable.
- */
 export declare function hostSessionMeta(task: HostTask, ctx: HostSessionContext): SessionMeta | null;
-/**
- * Register (or refresh) a host-dispatched run in the local session index. No-op
- * when the task carries no session id. Best-effort: a failed write must never
- * break the dispatch itself, which has already been launched on the host.
- */
 export declare function registerHostSession(task: HostTask, ctx: HostSessionContext): void;
-/**
- * Relate a remote-created session id back to a followed host dispatch.
- *
- * The remote run (dispatched with `--emit-session-id`) prints its resolved id as
- * a stdout sentinel (see session-marker.ts) that rides the followed log into the
- * task's local mirror. Read that mirror, parse the id, and stamp it on the task
- * so `findTaskBySessionId` and the session-index registration work for agents
- * that never take a forced `--session-id` — closing the gap where every
- * non-Claude host run was orphaned.
- *
- * Returns the updated task when an id was captured (and differs from what's on
- * the record), else null. A task that already carries an id (Claude's forced id,
- * a resume) is left untouched — the marker only fills a genuinely empty slot, so
- * it can never overwrite an authoritative id with a stale echo. Best-effort: a
- * missing/unreadable mirror or absent marker yields null, never an exception.
- */
 export declare function captureRemoteSessionId(task: HostTask): HostTask | null;
 interface InteractiveHostSessionContext {
     cwd: string;
@@ -61,11 +15,5 @@ interface InteractiveHostSessionContext {
     name?: string;
     createdAt?: string;
 }
-/**
- * Register an interactive host run (no prompt, TTY forwarded over SSH) in the
- * local session index. Unlike detached host runs, there is no remote log/exit
- * file and no HostTask; we only need the session id so `agents sessions` can
- * surface and resume it by id.
- */
 export declare function registerInteractiveHostSession(ctx: InteractiveHostSessionContext): void;
 export {};

package/dist/lib/hosts/session-index.js

@@ -1,33 +1,10 @@
-/**
- * Register host-dispatched runs (`agents run --device <h>`) into the LOCAL session
- * index so they show up in `agents sessions` and are resolvable by id — even
- * though the transcript itself lives on the remote host.
- *
- * The transcript file is remote, so the row is registered with an EMPTY
- * `file_path`. The DB's stale-row filter keeps rows with no file_path
- * (`!file_path || existsSync(file_path)` in db.ts querySessions) precisely for
- * this "synthetic file_path" case, and the scanner never prunes session rows —
- * so the entry survives rescans. `cwd` is the LOCAL directory the dispatch was
- * issued from, so the run appears in that project's session listing like any
- * local run. The `[host/<name>]` label mirrors the cloud path's
- * `[cloud/<status>]` convention.
- *
- * `machine` is the dispatch host, not this box. Both the transcript and the
- * version-isolated harness home live there; omitting it makes the SQLite upsert
- * infer this box from the empty file path and sends recovery to the wrong home.
- */
 import * as fs from 'fs';
 import { upsertSession } from '../session/db.js';
-import { isSessionTrackedAgent } from '../session/types.js';
+import { isSessionTrackedAgent } from '@phnx-labs/sessions-cli/reader';
 import { localLogPath, updateTask } from './tasks.js';
 import { parseSessionIdMarker } from './session-marker.js';
 import { deriveShortId } from '../text/short-id.js';
 import { normalizeHost } from '../machine-id.js';
-/**
- * Build the SessionMeta for a host-dispatched run. Returns null when the run has
- * no captured session id (nothing stable to key/resume on) or its agent isn't a
- * known session agent. Pure — no I/O — so the mapping is unit-testable.
- */
 export function hostSessionMeta(task, ctx) {
     const id = task.sessionId;
     if (!id)
@@ -40,22 +17,12 @@ export function hostSessionMeta(task, ctx) {
         agent: task.agent,
         timestamp: task.createdAt,
         cwd: ctx.cwd,
-        // Remote transcript — no local file. Empty file_path is the sentinel the DB
-        // stale-filter treats as "always live" (see module doc).
         filePath: '',
         machine: normalizeHost(task.host),
         topic: ctx.prompt.split('\n')[0]?.slice(0, 120) || undefined,
-        // The run's `--name` seeds the label (resolves `agents sessions <name>` and
-        // `agents logs <name>`); an unnamed host run falls back to the
-        // `[host/<name>]` indicator, mirroring the cloud path's `[cloud/<status>]`.
         label: task.name || `[host/${task.host}]`,
     };
 }
-/**
- * Register (or refresh) a host-dispatched run in the local session index. No-op
- * when the task carries no session id. Best-effort: a failed write must never
- * break the dispatch itself, which has already been launched on the host.
- */
 export function registerHostSession(task, ctx) {
     const meta = hostSessionMeta(task, ctx);
     if (!meta)
@@ -64,25 +31,8 @@ export function registerHostSession(task, ctx) {
         upsertSession(meta, '');
     }
     catch {
-        /* index write is best-effort; the run is already live on the host */
     }
 }
-/**
- * Relate a remote-created session id back to a followed host dispatch.
- *
- * The remote run (dispatched with `--emit-session-id`) prints its resolved id as
- * a stdout sentinel (see session-marker.ts) that rides the followed log into the
- * task's local mirror. Read that mirror, parse the id, and stamp it on the task
- * so `findTaskBySessionId` and the session-index registration work for agents
- * that never take a forced `--session-id` — closing the gap where every
- * non-Claude host run was orphaned.
- *
- * Returns the updated task when an id was captured (and differs from what's on
- * the record), else null. A task that already carries an id (Claude's forced id,
- * a resume) is left untouched — the marker only fills a genuinely empty slot, so
- * it can never overwrite an authoritative id with a stale echo. Best-effort: a
- * missing/unreadable mirror or absent marker yields null, never an exception.
- */
 export function captureRemoteSessionId(task) {
     if (task.sessionId)
         return null;
@@ -91,19 +41,13 @@ export function captureRemoteSessionId(task) {
         text = fs.readFileSync(localLogPath(task.id), 'utf8');
     }
     catch {
-        return null; // no local mirror (unfollowed run, or read raced the follow)
+        return null;
     }
     const captured = parseSessionIdMarker(text);
     if (!captured)
         return null;
     return updateTask(task.id, { sessionId: captured });
 }
-/**
- * Register an interactive host run (no prompt, TTY forwarded over SSH) in the
- * local session index. Unlike detached host runs, there is no remote log/exit
- * file and no HostTask; we only need the session id so `agents sessions` can
- * surface and resume it by id.
- */
 export function registerInteractiveHostSession(ctx) {
     if (!isSessionTrackedAgent(ctx.agent))
         return;
@@ -120,6 +64,5 @@ export function registerInteractiveHostSession(ctx) {
         }, '');
     }
     catch {
-        /* index write is best-effort; the run is already live on the host */
     }
 }

package/dist/lib/hosts/session-marker.d.ts

@@ -1,33 +1,2 @@
-/**
- * Relate a remote-created session id back to the launching agent.
- *
- * A host dispatch (`agents run --device`) launches `agents run` on the remote box.
- * Only Claude accepts a forced `--session-id`, so for every OTHER agent the
- * remote run coins its OWN session id (via its SessionStart hook) and the
- * launcher never learns it — the run is orphaned in `agents sessions`.
- *
- * This module closes that gap without an extra SSH round-trip: the dispatch
- * forwards `--emit-session-id`, which makes the remote `agents run` print its
- * resolved session id as a stable one-line sentinel to stdout. That line rides
- * the same combined log the follow already mirrors locally, so the launcher
- * parses the id straight out of the streamed output and stamps it on the task.
- *
- * The marker is a fixed ASCII frame with the id on its own line. A real session
- * id (`[A-Za-z0-9._-]`) never contains the marker's own bytes, so the parser can
- * scan for the LAST occurrence and stay robust to an agent echoing the token in
- * its own output.
- */
-/**
- * The single line the remote run prints to stdout so the launcher can capture
- * the session id the remote coined. Newline-framed on both sides so it lands on
- * its own line regardless of what the agent last wrote.
- */
 export declare function sessionIdMarkerLine(sessionId: string): string;
-/**
- * Extract the session id from a chunk of followed remote output, or null when no
- * marker is present. Scans for the LAST marker (so an id echoed into the log
- * earlier can never mask the real trailing sentinel) and validates the captured
- * token against the session-id charset — a malformed frame yields null rather
- * than a bogus id that could never match a real session.
- */
 export declare function parseSessionIdMarker(text: string): string | null;

package/dist/lib/hosts/session-marker.js

@@ -1,41 +1,9 @@
-/**
- * Relate a remote-created session id back to the launching agent.
- *
- * A host dispatch (`agents run --device`) launches `agents run` on the remote box.
- * Only Claude accepts a forced `--session-id`, so for every OTHER agent the
- * remote run coins its OWN session id (via its SessionStart hook) and the
- * launcher never learns it — the run is orphaned in `agents sessions`.
- *
- * This module closes that gap without an extra SSH round-trip: the dispatch
- * forwards `--emit-session-id`, which makes the remote `agents run` print its
- * resolved session id as a stable one-line sentinel to stdout. That line rides
- * the same combined log the follow already mirrors locally, so the launcher
- * parses the id straight out of the streamed output and stamps it on the task.
- *
- * The marker is a fixed ASCII frame with the id on its own line. A real session
- * id (`[A-Za-z0-9._-]`) never contains the marker's own bytes, so the parser can
- * scan for the LAST occurrence and stay robust to an agent echoing the token in
- * its own output.
- */
 const MARKER_PREFIX = '@@AGENTS_SESSION_ID ';
 const MARKER_SUFFIX = '@@';
-/** Only characters a real agent session id can hold — no marker bytes, no spaces. */
 const SESSION_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,255}$/;
-/**
- * The single line the remote run prints to stdout so the launcher can capture
- * the session id the remote coined. Newline-framed on both sides so it lands on
- * its own line regardless of what the agent last wrote.
- */
 export function sessionIdMarkerLine(sessionId) {
     return `\n${MARKER_PREFIX}${sessionId}${MARKER_SUFFIX}\n`;
 }
-/**
- * Extract the session id from a chunk of followed remote output, or null when no
- * marker is present. Scans for the LAST marker (so an id echoed into the log
- * earlier can never mask the real trailing sentinel) and validates the captured
- * token against the session-id charset — a malformed frame yields null rather
- * than a bogus id that could never match a real session.
- */
 export function parseSessionIdMarker(text) {
     const last = text.lastIndexOf(MARKER_PREFIX);
     if (last === -1)

package/dist/lib/hosts/ssh-config.d.ts

@@ -1,36 +1,11 @@
-/**
- * Read the user's SSH config as a host directory — we never copy or rewrite it.
- *
- * `~/.ssh/config` is the source of truth for connection details; we only parse
- * `Host` stanzas to list candidate names and `ssh -G <name>` to resolve them for
- * display. `known_hosts` is a secondary candidate source for enrollment.
- */
-/**
- * Parse `Host` stanza names from ssh config text. Wildcard/negated patterns
- * (`*`, `?`, `!`) are skipped — they're match rules, not concrete hosts.
- * Pure (text in, names out) so it's unit-testable.
- */
 export declare function parseSshConfigHosts(content: string): string[];
-/**
- * Parse hostnames from known_hosts text. Hashed entries (`|1|…`) carry no
- * recoverable hostname and are skipped; `[host]:port` and comma lists are split.
- * Pure for testability.
- */
 export declare function parseKnownHosts(content: string): string[];
-/** `Host` names from ~/.ssh/config, following `Include` globs (best-effort). */
 export declare function listSshConfigHosts(): string[];
-/** True if `name` is a concrete `Host` stanza in ssh config. */
 export declare function isSshConfigHost(name: string): boolean;
 interface SshGResult {
     hostname?: string;
     user?: string;
     port?: string;
 }
-/**
- * Authoritative resolution of a host's effective ssh config via `ssh -G <name>`
- * (honors Match/Include). Returns undefined if `ssh` is unavailable. Note:
- * `ssh -G` returns defaults even for unknown names — pair with `isSshConfigHost`
- * to decide whether a name is actually configured.
- */
 export declare function sshResolve(name: string): SshGResult | undefined;
 export {};

package/dist/lib/hosts/ssh-config.js

@@ -1,10 +1,3 @@
-/**
- * Read the user's SSH config as a host directory — we never copy or rewrite it.
- *
- * `~/.ssh/config` is the source of truth for connection details; we only parse
- * `Host` stanzas to list candidate names and `ssh -G <name>` to resolve them for
- * display. `known_hosts` is a secondary candidate source for enrollment.
- */
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
@@ -12,11 +5,6 @@ import { spawnSync } from 'child_process';
 import { assertValidSshTarget } from '../ssh-exec.js';
 const SSH_DIR = path.join(os.homedir(), '.ssh');
 const SSH_CONFIG = path.join(SSH_DIR, 'config');
-/**
- * Parse `Host` stanza names from ssh config text. Wildcard/negated patterns
- * (`*`, `?`, `!`) are skipped — they're match rules, not concrete hosts.
- * Pure (text in, names out) so it's unit-testable.
- */
 export function parseSshConfigHosts(content) {
     const names = [];
     const seen = new Set();
@@ -38,11 +26,6 @@ export function parseSshConfigHosts(content) {
     }
     return names;
 }
-/**
- * Parse hostnames from known_hosts text. Hashed entries (`|1|…`) carry no
- * recoverable hostname and are skipped; `[host]:port` and comma lists are split.
- * Pure for testability.
- */
 export function parseKnownHosts(content) {
     const names = [];
     const seen = new Set();
@@ -52,9 +35,8 @@ export function parseKnownHosts(content) {
             continue;
         const first = line.split(/\s+/)[0];
         if (!first || first.startsWith('|'))
-            continue; // hashed
+            continue;
         for (const entry of first.split(',')) {
-            // strip [host]:port → host
             const host = entry.replace(/^\[/, '').replace(/\](:\d+)?$/, '');
             if (!host || /[*?]/.test(host) || seen.has(host))
                 continue;
@@ -64,7 +46,6 @@ export function parseKnownHosts(content) {
     }
     return names;
 }
-/** `Host` names from ~/.ssh/config, following `Include` globs (best-effort). */
 export function listSshConfigHosts() {
     const names = new Set();
     const visit = (file, depth) => {
@@ -79,7 +60,6 @@ export function listSshConfigHosts() {
         }
         for (const name of parseSshConfigHosts(content))
             names.add(name);
-        // Follow Include directives (best-effort, relative to ~/.ssh).
         for (const rawLine of content.split('\n')) {
             const m = /^\s*Include\s+(.+)$/i.exec(rawLine);
             if (!m)
@@ -94,7 +74,6 @@ export function listSshConfigHosts() {
     visit(SSH_CONFIG, 0);
     return [...names];
 }
-/** Minimal glob: expand a single trailing `*` in the basename, else literal. */
 function globMaybe(pattern) {
     if (!pattern.includes('*')) {
         return fs.existsSync(pattern) ? [pattern] : [];
@@ -109,20 +88,10 @@ function globMaybe(pattern) {
         return [];
     }
 }
-/** True if `name` is a concrete `Host` stanza in ssh config. */
 export function isSshConfigHost(name) {
     return listSshConfigHosts().includes(name);
 }
-/**
- * Authoritative resolution of a host's effective ssh config via `ssh -G <name>`
- * (honors Match/Include). Returns undefined if `ssh` is unavailable. Note:
- * `ssh -G` returns defaults even for unknown names — pair with `isSshConfigHost`
- * to decide whether a name is actually configured.
- */
 export function sshResolve(name) {
-    // Same target-injection guard as sshExec: a name starting with `-` (or
-    // carrying shell metacharacters) must never reach `ssh` as a bare argv where
-    // it could be parsed as a flag (e.g. `-oProxyCommand=…`).
     try {
         assertValidSshTarget(name);
     }