@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/hosts/progress.d.ts

@@ -1,40 +1,4 @@
-/**
- * Follow a dispatched host run by streaming its remote log.
- *
- * The run writes combined output to a log file on the host and its exit code to
- * a sibling `.exit` file. The primary path opens one long-lived
- * `ssh ... tail -f` stream (durable, offset-tracked — a dropped connection
- * reconnects from the saved offset) and finishes when the remote-side watcher
- * emits the exit sentinel. Rich transcript-parser rendering is a fast-follow.
- *
- * Efficiency: a healthy follow holds exactly one ssh process/socket for the
- * whole run instead of spawning once per poll cycle. If the connection drops,
- * the next stream resumes at the byte offset already flushed locally.
- */
-/**
- * Cap for the LOCAL mirror of a distributed teammate's remote log. `followHostTask`
- * appends remote bytes into the local mirror forever; a team can spin 10+ chatty
- * remote teammates, so the orchestrator must keep a bounded window (the full log
- * always lives on the host). The teams remote path (agents.ts readNewEvents) writes
- * its own append into each teammate's `stdout.log`, then truncates that file to its
- * trailing `REMOTE_MIRROR_MAX_BYTES` — the parser has already consumed the bytes
- * (status/digest updated via lastReadPos), so trailing-tail history is dead weight.
- */
 export declare const REMOTE_MIRROR_MAX_BYTES: number;
-/**
- * Pull the new bytes of a remote log since `offset` in ONE ssh round-trip.
- *
- * The teams remote-teammate monitor calls this each poll to advance its offset-tail
- * cursor into the host's log, mirroring only the delta into the local `stdout.log`
- * the stream-json parser consumes. Byte-exact (raw Buffer, no UTF-8 decode) so a
- * multibyte character split at the `tail -c` boundary neither drifts the offset nor
- * renders as U+FFFD — the same discipline `fetchProgress` uses. `bytes.length` is
- * the exact wire count; `newOffset` is `offset + bytes.length`.
- *
- * Returns null on a transient ssh failure (the caller retries next poll without
- * advancing). `remoteLog` is a $HOME-prefixed path with a safe basename; it's
- * shell-quoted defensively even so.
- */
 export declare function pullRemoteLogDelta(target: string, opts: {
     remoteLog: string;
     offset: number;
@@ -46,54 +10,20 @@ export declare function pullRemoteLogDelta(target: string, opts: {
 export interface FollowOptions {
     remoteLog: string;
     remoteExit: string;
-    /** Mirror remote output into this task's local log too. */
     taskId: string;
-    /** Print streamed output to stdout. */
     echo?: boolean;
-    /** Overall wall-clock cap; returns -1 on timeout. */
     timeoutMs?: number;
-    /** Fast poll interval while output is flowing (default 1500ms). */
     pollMs?: number;
-    /** Idle-backoff ceiling (default 4× the fast interval, min 4000ms). */
     maxPollMs?: number;
     extraSshArgs?: string[];
     remoteShell?: 'posix' | 'powershell';
 }
-/**
- * Build the per-task sentinel that separates the log tail from the exit-file
- * contents in one combined fetch. The task id (8 hex chars) makes collision with
- * the agent's own output effectively impossible; callers still split on the LAST
- * occurrence so a token echoed into the log can never be mistaken for the real
- * trailing marker.
- */
 export declare function exitMarker(taskId: string): string;
-/**
- * Split a combined fetch (`<log bytes><marker><exit>`) back into its parts at the
- * BYTE level. Splits on the LAST marker occurrence, so even if the agent's own
- * output happened to echo the token, the real trailing sentinel still wins.
- * Returns null when the marker is absent (a transient fetch miss — the remote
- * shell never ran our printf), telling the caller to retry without advancing.
- *
- * Byte-level (not string) is load-bearing: `logChunk.length` is the EXACT number
- * of log bytes consumed on the wire, which the follow loop adds to its offset. A
- * string split would first UTF-8-decode, turning any multibyte char split at the
- * `tail -c` boundary into a U+FFFD whose re-encoded length ≠ the wire bytes,
- * drifting the offset (see followHostTask). `consumed` is returned explicitly for
- * clarity; it always equals `logChunk.length`.
- */
 export declare function splitProgressBytes(buf: Buffer, taskId: string): {
     logChunk: Buffer;
     exit: Buffer;
     consumed: number;
 } | null;
-/**
- * One round-trip: new log bytes since `offset`, the sentinel, then the exit
- * file. Returns null on a transient fetch miss (ssh error / marker absent) so
- * the caller simply retries next cycle without advancing the offset.
- *
- * `remoteLog`/`remoteExit` are $HOME-prefixed paths with safe (hex) basenames —
- * intentionally unquoted so the remote shell expands $HOME.
- */
 export declare function fetchProgress(target: string, opts: {
     remoteLog: string;
     remoteExit: string;
@@ -111,32 +41,12 @@ export declare function buildWindowsProgressCommand(opts: {
     taskId: string;
     offset: number;
 }): string;
-/**
- * Remote shell for the persistent follow stream.
- *
- * Protocol: stream `tail -c +<offset+1> -f <log>` as raw stdout until `.exit`
- * becomes non-empty, give tail one more polling interval to flush final bytes,
- * stop it, then print the same per-task sentinel and `cat` the exit file on
- * stderr. Keeping the terminal frame off stdout lets log bytes pass through
- * live without buffering and without confusing agent output for our marker.
- * `remoteLog`/`remoteExit` are dispatch-generated `$HOME` paths with safe hex
- * basenames (or absolute paths in localhost integration tests), so they stay
- * unquoted to preserve `$HOME` expansion just like `fetchProgress`.
- */
 export declare function buildStreamingFollowCommand(opts: {
     remoteLog: string;
     remoteExit: string;
     taskId: string;
     offset: number;
 }): string;
-/** Extract the remote watcher frame from stderr, if the stream ended normally. */
 export declare function parseStreamingExitFrame(stderr: Buffer, taskId: string): Buffer | null;
-/**
- * True when the local mirror file IS the very file we're tailing — the
- * localhost-as-host case, where `remoteLog` ($HOME-expanded) and `localLogPath`
- * resolve to the same inode. Appending our read bytes back into it would feed the
- * tail and multiply the log, so the caller must skip the mirror write.
- */
 export declare function mirrorAliasesSource(localId: string | null, remoteId: string | null): boolean;
-/** Tail the remote log to stdout until the run finishes; return its exit code. */
 export declare function followHostTask(target: string, opts: FollowOptions): Promise<number>;

package/dist/lib/hosts/progress.js

@@ -1,16 +1,3 @@
-/**
- * Follow a dispatched host run by streaming its remote log.
- *
- * The run writes combined output to a log file on the host and its exit code to
- * a sibling `.exit` file. The primary path opens one long-lived
- * `ssh ... tail -f` stream (durable, offset-tracked — a dropped connection
- * reconnects from the saved offset) and finishes when the remote-side watcher
- * emits the exit sentinel. Rich transcript-parser rendering is a fast-follow.
- *
- * Efficiency: a healthy follow holds exactly one ssh process/socket for the
- * whole run instead of spawning once per poll cycle. If the connection drops,
- * the next stream resumes at the byte offset already flushed locally.
- */
 import * as fs from 'fs';
 import { sshExec, sshExecRaw, sshExecRawStream } from '../ssh-exec.js';
 import { encodePowershell } from './remote-cmd.js';
@@ -18,68 +5,20 @@ import { localLogPath } from './tasks.js';
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
-/**
- * Cap for the LOCAL mirror of a distributed teammate's remote log. `followHostTask`
- * appends remote bytes into the local mirror forever; a team can spin 10+ chatty
- * remote teammates, so the orchestrator must keep a bounded window (the full log
- * always lives on the host). The teams remote path (agents.ts readNewEvents) writes
- * its own append into each teammate's `stdout.log`, then truncates that file to its
- * trailing `REMOTE_MIRROR_MAX_BYTES` — the parser has already consumed the bytes
- * (status/digest updated via lastReadPos), so trailing-tail history is dead weight.
- */
 export const REMOTE_MIRROR_MAX_BYTES = 512 * 1024;
-/**
- * Pull the new bytes of a remote log since `offset` in ONE ssh round-trip.
- *
- * The teams remote-teammate monitor calls this each poll to advance its offset-tail
- * cursor into the host's log, mirroring only the delta into the local `stdout.log`
- * the stream-json parser consumes. Byte-exact (raw Buffer, no UTF-8 decode) so a
- * multibyte character split at the `tail -c` boundary neither drifts the offset nor
- * renders as U+FFFD — the same discipline `fetchProgress` uses. `bytes.length` is
- * the exact wire count; `newOffset` is `offset + bytes.length`.
- *
- * Returns null on a transient ssh failure (the caller retries next poll without
- * advancing). `remoteLog` is a $HOME-prefixed path with a safe basename; it's
- * shell-quoted defensively even so.
- */
 export function pullRemoteLogDelta(target, opts) {
-    // remoteLog is a dispatch-generated `$HOME/.agents/.cache/hosts/<hex>.log` path —
-    // interpolate UNQUOTED so the remote shell expands `$HOME` (shellQuote would
-    // single-quote it into a literal `$HOME`, and the tail would find nothing). The
-    // hex basename is injection-safe, matching fetchProgress below.
     const remote = `tail -c +${opts.offset + 1} ${opts.remoteLog} 2>/dev/null`;
     const res = sshExecRaw(target, remote, { timeoutMs: 20000, multiplex: true, extraSshArgs: opts.extraSshArgs });
     if (res.code === null)
-        return null; // ssh itself failed / timed out
+        return null;
     return { bytes: res.stdout, newOffset: opts.offset + res.stdout.length };
 }
 const STREAM_EXIT_POLL_SECONDS = 1;
-/**
- * Build the per-task sentinel that separates the log tail from the exit-file
- * contents in one combined fetch. The task id (8 hex chars) makes collision with
- * the agent's own output effectively impossible; callers still split on the LAST
- * occurrence so a token echoed into the log can never be mistaken for the real
- * trailing marker.
- */
 export function exitMarker(taskId) {
     return `\n@@AGENTS_HOST_EXIT_${taskId}@@\n`;
 }
-/**
- * Split a combined fetch (`<log bytes><marker><exit>`) back into its parts at the
- * BYTE level. Splits on the LAST marker occurrence, so even if the agent's own
- * output happened to echo the token, the real trailing sentinel still wins.
- * Returns null when the marker is absent (a transient fetch miss — the remote
- * shell never ran our printf), telling the caller to retry without advancing.
- *
- * Byte-level (not string) is load-bearing: `logChunk.length` is the EXACT number
- * of log bytes consumed on the wire, which the follow loop adds to its offset. A
- * string split would first UTF-8-decode, turning any multibyte char split at the
- * `tail -c` boundary into a U+FFFD whose re-encoded length ≠ the wire bytes,
- * drifting the offset (see followHostTask). `consumed` is returned explicitly for
- * clarity; it always equals `logChunk.length`.
- */
 export function splitProgressBytes(buf, taskId) {
-    const marker = Buffer.from(exitMarker(taskId), 'utf8'); // ASCII-only, unambiguous
+    const marker = Buffer.from(exitMarker(taskId), 'utf8');
     const idx = buf.lastIndexOf(marker);
     if (idx === -1)
         return null;
@@ -89,27 +28,11 @@ export function splitProgressBytes(buf, taskId) {
         consumed: idx,
     };
 }
-/**
- * One round-trip: new log bytes since `offset`, the sentinel, then the exit
- * file. Returns null on a transient fetch miss (ssh error / marker absent) so
- * the caller simply retries next cycle without advancing the offset.
- *
- * `remoteLog`/`remoteExit` are $HOME-prefixed paths with safe (hex) basenames —
- * intentionally unquoted so the remote shell expands $HOME.
- */
 export function fetchProgress(target, opts) {
-    // Derive the printf format from the SAME exitMarker the parser splits on, so
-    // the emitted sentinel and the one we look for can never desync. The marker's
-    // only escape-sensitive bytes are its newlines (→ `\n`); it carries no `%`,
-    // single-quote, or other printf/shell-special chars (task id is hex).
     const printfArg = exitMarker(opts.taskId).replace(/\n/g, '\\n');
     const remote = opts.remoteShell === 'powershell'
         ? buildWindowsProgressCommand(opts)
         : `tail -c +${opts.offset + 1} ${opts.remoteLog} 2>/dev/null; printf '${printfArg}'; cat ${opts.remoteExit} 2>/dev/null`;
-    // Raw bytes (no UTF-8 decode): the log tail must be counted and re-emitted
-    // byte-for-byte so a multibyte char split at the `tail -c` boundary neither
-    // drifts the offset nor renders as U+FFFD. The exit code is pure ASCII → safe
-    // to decode to a string for the caller's `.trim()`.
     const res = sshExecRaw(target, remote, { timeoutMs: 20000, extraSshArgs: opts.extraSshArgs });
     const parts = splitProgressBytes(res.stdout, opts.taskId);
     if (!parts)
@@ -132,18 +55,6 @@ export function buildWindowsProgressCommand(opts) {
     ].join('; ');
     return `powershell -NoProfile -EncodedCommand ${encodePowershell(script)}`;
 }
-/**
- * Remote shell for the persistent follow stream.
- *
- * Protocol: stream `tail -c +<offset+1> -f <log>` as raw stdout until `.exit`
- * becomes non-empty, give tail one more polling interval to flush final bytes,
- * stop it, then print the same per-task sentinel and `cat` the exit file on
- * stderr. Keeping the terminal frame off stdout lets log bytes pass through
- * live without buffering and without confusing agent output for our marker.
- * `remoteLog`/`remoteExit` are dispatch-generated `$HOME` paths with safe hex
- * basenames (or absolute paths in localhost integration tests), so they stay
- * unquoted to preserve `$HOME` expansion just like `fetchProgress`.
- */
 export function buildStreamingFollowCommand(opts) {
     const printfArg = exitMarker(opts.taskId).replace(/\n/g, '\\n');
     return [
@@ -165,7 +76,6 @@ export function buildStreamingFollowCommand(opts) {
         `cat ${opts.remoteExit} >&2 2>/dev/null`,
     ].join('\n');
 }
-/** Extract the remote watcher frame from stderr, if the stream ended normally. */
 export function parseStreamingExitFrame(stderr, taskId) {
     const marker = Buffer.from(exitMarker(taskId), 'utf8');
     const idx = stderr.lastIndexOf(marker);
@@ -173,25 +83,14 @@ export function parseStreamingExitFrame(stderr, taskId) {
         return null;
     return stderr.subarray(idx + marker.length);
 }
-/**
- * File identity (`dev:ino`) of a path on the remote host, or null if it can't be
- * stat'd. GNU (`-c`) then BSD (`-f`) format, so it works on Linux and macOS hosts.
- */
 function readRemoteFileId(target, remotePath, extraSshArgs) {
     const res = sshExec(target, `stat -c '%d:%i' ${remotePath} 2>/dev/null || stat -f '%d:%i' ${remotePath} 2>/dev/null`, { timeoutMs: 8000, extraSshArgs });
     const id = res.stdout.trim();
     return id || null;
 }
-/**
- * True when the local mirror file IS the very file we're tailing — the
- * localhost-as-host case, where `remoteLog` ($HOME-expanded) and `localLogPath`
- * resolve to the same inode. Appending our read bytes back into it would feed the
- * tail and multiply the log, so the caller must skip the mirror write.
- */
 export function mirrorAliasesSource(localId, remoteId) {
     return localId !== null && remoteId !== null && localId === remoteId;
 }
-/** Tail the remote log to stdout until the run finishes; return its exit code. */
 export async function followHostTask(target, opts) {
     const fastMs = opts.pollMs ?? 1500;
     const maxMs = Math.max(opts.maxPollMs ?? fastMs * 4, 4000);
@@ -199,10 +98,6 @@ export async function followHostTask(target, opts) {
     const local = localLogPath(opts.taskId);
     let offset = 0;
     let waitMs = fastMs;
-    // localhost-as-host guard: when the local mirror and the remote log are the
-    // same physical file, appending our read bytes back would feed the tail and
-    // multiply the log (a plain `--host localhost` follow otherwise tripled it).
-    // Detect via file identity and echo-only in that case.
     let mirror = true;
     try {
         const s = fs.statSync(local);
@@ -210,7 +105,7 @@ export async function followHostTask(target, opts) {
             mirror = false;
         }
     }
-    catch { /* mirror absent or unstattable → distinct file, keep mirroring */ }
+    catch { }
     const flush = (logChunk) => {
         if (logChunk.length === 0)
             return false;
@@ -220,9 +115,9 @@ export async function followHostTask(target, opts) {
             try {
                 fs.appendFileSync(local, logChunk);
             }
-            catch { /* best-effort */ }
+            catch { }
         }
-        offset += logChunk.length; // exact wire bytes — no re-encode drift
+        offset += logChunk.length;
         return true;
     };
     if (opts.remoteShell === 'powershell') {
@@ -267,15 +162,10 @@ export async function followHostTask(target, opts) {
             const code = parseInt(exitFrame.toString('utf8').trim(), 10);
             return Number.isFinite(code) ? code : 0;
         }
-        // SSH dropped before the remote watcher emitted the exit sentinel. Stdout
-        // chunks were flushed as they arrived, so reconnect from the advanced offset.
-        // If no bytes arrived, back off like the old idle poll.
         if (Date.now() > deadline) {
             process.stderr.write('\n[hosts] follow timed out; the run continues on the host. Reattach with: agents logs ' + opts.taskId + ' -f\n');
             return -1;
         }
-        // Reconnect quickly while output flows; ease toward maxMs when the stream
-        // drops without bytes so a flapping idle host does not spin ssh processes.
         waitMs = gotOutput ? fastMs : Math.min(maxMs, Math.round(waitMs * 1.5));
         await sleep(waitMs);
     }

package/dist/lib/hosts/providers/devices.d.ts

@@ -1,22 +1,3 @@
-/**
- * Devices host provider: the Tailscale fleet as dispatch targets.
- *
- * Bridges the devices registry (`agents devices`, ~/.agents/.history/devices/
- * registry.json) into the host pool behind the same `HostProvider` seam as
- * `local` — the Tailscale-backed device provider described in docs/fleet.md. With
- * it, a machine registered once via `agents devices sync` becomes a resolvable
- * `--device`/`--device` dispatch target, participates in capability routing, and
- * is enumerable by target pickers — not just resolvable by exact name.
- *
- * Password-auth devices are listed (the pool stays honest about what exists)
- * but marked `dispatchable: false`; resolving one for dispatch throws the same
- * typed `DeviceOffloadUnsupportedError` as before — offload rides `sshExec`,
- * whose SSH_OPTS force `BatchMode=yes`.
- *
- * Precedence is unchanged: this provider registers AFTER `local`, so an
- * enrolled host shadows a same-name device in both list dedup and resolve
- * order, exactly like the old tier-2 devices fall-through in resolveHost.
- */
 import type { Host, HostProvider, HostProviderCapabilities, HostStatus } from '../types.js';
 export declare class DevicesHostProvider implements HostProvider {
     readonly id: "devices";

package/dist/lib/hosts/providers/devices.js

@@ -1,44 +1,16 @@
-/**
- * Devices host provider: the Tailscale fleet as dispatch targets.
- *
- * Bridges the devices registry (`agents devices`, ~/.agents/.history/devices/
- * registry.json) into the host pool behind the same `HostProvider` seam as
- * `local` — the Tailscale-backed device provider described in docs/fleet.md. With
- * it, a machine registered once via `agents devices sync` becomes a resolvable
- * `--device`/`--device` dispatch target, participates in capability routing, and
- * is enumerable by target pickers — not just resolvable by exact name.
- *
- * Password-auth devices are listed (the pool stays honest about what exists)
- * but marked `dispatchable: false`; resolving one for dispatch throws the same
- * typed `DeviceOffloadUnsupportedError` as before — offload rides `sshExec`,
- * whose SSH_OPTS force `BatchMode=yes`.
- *
- * Precedence is unchanged: this provider registers AFTER `local`, so an
- * enrolled host shadows a same-name device in both list dedup and resolve
- * order, exactly like the old tier-2 devices fall-through in resolveHost.
- */
 import { loadDevices, getDevice } from '../../devices/registry.js';
 import { resolveDeviceProfile } from '../../devices/resolve-profile.js';
 import { DeviceOffloadUnsupportedError } from '../types.js';
-/** Tailscale's own presence bit, when the sync captured one. */
 function statusOf(device) {
     if (!device.tailscale)
         return 'unknown';
     return device.tailscale.online ? 'online' : 'offline';
 }
-/**
- * Bridge a device profile into a `Host`. dnsName (stable across IP churn) is
- * preferred over ip; `source: 'inline'` makes `sshTargetFor` emit `user@address`.
- * Capability tags come from an enrolled overlay entry for the device in
- * agents.yaml (`Meta.hosts`) — that entry shadows this row by provider
- * precedence, carrying the caps.
- */
 function deviceToPoolHost(rawDevice) {
-    // Effective profile: central config (ssh.*/platform) overlays discovery.
     const device = resolveDeviceProfile(rawDevice);
     const address = device.address.dnsName ?? device.address.ip;
     if (!address)
-        return null; // unreachable profile — nothing to dispatch to
+        return null;
     return {
         name: device.name,
         provider: 'devices',
@@ -55,7 +27,6 @@ function deviceToPoolHost(rawDevice) {
 export class DevicesHostProvider {
     id = 'devices';
     capabilities() {
-        // mutate stays false: `agents devices sync/add/set` own the registry.
         return { directory: true, mutate: false, presence: true, relay: false, lease: false };
     }
     async list() {
@@ -72,11 +43,7 @@ export class DevicesHostProvider {
         const raw = await getDevice(name);
         if (!raw)
             return null;
-        // Effective profile: central config (ssh.*/platform) overlays discovery —
-        // the password-auth refusal and the dial shape both follow the config.
         const device = resolveDeviceProfile(raw);
-        // Keep the long-standing typed refusal for password auth (BatchMode=yes
-        // can't answer a prompt).
         if (device.auth.method === 'password') {
             throw new DeviceOffloadUnsupportedError(device.name);
         }

package/dist/lib/hosts/providers/local.d.ts

@@ -1,17 +1,3 @@
-/**
- * Local host provider: the v1 directory.
- *
- * `list()` is the union of ssh-config `Host` stanzas (read-only, connection
- * details owned by ssh) and inline entries the user registered. The host
- * overlay (caps/os, keyed by name) is merged onto both. We never copy or
- * rewrite ssh config.
- *
- * PHNX-3315: registrations are DEVICE-SCOPED — each box writes only its own
- * `hosts:` block in `devices/<machine>/agents.yaml` (via `Meta.deviceHosts`),
- * so N boxes no longer rewrite one shared `hosts:` map (the pull conflict).
- * Reads are the cross-box UNION of every device doc, plus any lingering central
- * legacy entries drained by the migration.
- */
 import type { Host, HostProvider, HostProviderCapabilities } from '../types.js';
 export declare class LocalHostProvider implements HostProvider {
     readonly id: "local";

package/dist/lib/hosts/providers/local.js

@@ -1,27 +1,9 @@
-/**
- * Local host provider: the v1 directory.
- *
- * `list()` is the union of ssh-config `Host` stanzas (read-only, connection
- * details owned by ssh) and inline entries the user registered. The host
- * overlay (caps/os, keyed by name) is merged onto both. We never copy or
- * rewrite ssh config.
- *
- * PHNX-3315: registrations are DEVICE-SCOPED — each box writes only its own
- * `hosts:` block in `devices/<machine>/agents.yaml` (via `Meta.deviceHosts`),
- * so N boxes no longer rewrite one shared `hosts:` map (the pull conflict).
- * Reads are the cross-box UNION of every device doc, plus any lingering central
- * legacy entries drained by the migration.
- */
 import { readMeta, updateMeta } from '../../state.js';
 import { unionDeviceHosts } from '../../devices/device-docs.js';
 import { listSshConfigHosts, isSshConfigHost } from '../ssh-config.js';
-/** The EFFECTIVE host overlay: the cross-box union of every device doc's
- * `hosts:` block, with any lingering central-legacy `hosts:` entries as a base
- * (a device doc wins on a name collision). Newest `addedAt` wins across boxes. */
 function entries() {
     return { ...readMeta().hosts, ...unionDeviceHosts() };
 }
-/** THIS box's OWN host registrations (the writable slice in the device doc). */
 function ownEntries(meta = readMeta()) {
     return meta.deviceHosts ?? {};
 }
@@ -47,12 +29,10 @@ export class LocalHostProvider {
         const overlay = entries();
         const out = [];
         const seen = new Set();
-        // Inline + overlaid hosts from the registry.
         for (const [name, entry] of Object.entries(overlay)) {
             out.push(toHost(name, entry, true));
             seen.add(name);
         }
-        // ssh-config hosts not already carrying an overlay → available, not enrolled.
         for (const name of listSshConfigHosts()) {
             if (seen.has(name))
                 continue;
@@ -77,12 +57,10 @@ export class LocalHostProvider {
             ...(spec.caps && spec.caps.length ? { caps: spec.caps } : {}),
             addedAt: spec.addedAt ?? new Date().toISOString(),
         };
-        // Device-scoped: land in THIS box's device doc, never the shared central map.
         updateMeta((meta) => ({ ...meta, deviceHosts: { ...ownEntries(meta), [spec.name]: entry } }));
         return toHost(spec.name, entry, true);
     }
     async remove(name) {
-        // A box only owns the registrations in its own device doc; drop from there.
         updateMeta((meta) => {
             const hosts = { ...ownEntries(meta) };
             delete hosts[name];

package/dist/lib/hosts/ready.d.ts

@@ -1,113 +1,35 @@
-/**
- * Host readiness + bootstrap.
- *
- * Before a dispatch we ensure the box is reachable and has agents-cli. Enrollment
- * can additionally install/upgrade agents-cli to match the local version (version
- * parity) using the same shape as scripts/sandbox.sh. We never copy `.history`.
- */
 import type { Host } from './types.js';
-/** Resolve this CLI's own version by walking up to the nearest package.json. */
 export declare function localCliVersion(): string | null;
-/** ssh command that confirms reachability and echoes the OS. POSIX boxes answer
- * `uname -s`; a Windows target has no `uname` (ssh lands in cmd.exe/PowerShell),
- * so it runs a tiny PowerShell probe. Pure/exported so both branches are
- * unit-testable without ssh. */
 export declare function buildProbeCommand(os?: string): string;
-/**
- * Reachability + OS probe over ssh. `os` is the caller's hint (device-registry
- * platform / enrolled `HostEntry.os`); when it marks the host Windows we take
- * the PowerShell path and report that known platform, otherwise POSIX + uname.
- */
 export declare function probeHost(target: string, os?: string, extraSshArgs?: string[]): {
     reachable: boolean;
     os?: string;
 };
-/** ssh command that prints the remote agents-cli version. Pure/exported. */
 export declare function buildRemoteVersionCommand(os?: string): string;
-/** ssh command that installs/upgrades agents-cli to `spec` then `agents setup`.
- * PowerShell has no `tail`/`[ -d ]`/`||`, so the Windows branch uses native
- * equivalents (`Select-Object -Last`, `Test-Path`). Pure/exported. */
 export declare function buildBootstrapCommand(spec: string, os?: string): string;
-/** Install (or upgrade to) a specific agents-cli version on the remote, then `agents setup`. */
 export declare function bootstrapAgentsCli(target: string, version: string | null, os?: string, extraSshArgs?: string[]): {
     ok: boolean;
     output: string;
 };
 export interface ReadyProbe {
-    /** ssh connected and the remote login shell ran (our sentinel came back). */
     reachable: boolean;
-    /** Remote agents-cli version (no leading `v`), or null if not installed. */
     version: string | null;
-    /** Raw `agents view`/`list` output, for installed-agent checks. */
     view: string;
-    /** True when the ssh probe timed out before the sentinel arrived. */
     timedOut?: boolean;
 }
-/**
- * Answer every readiness question in ONE ssh round-trip: reachable? (the login
- * shell ran and echoed our sentinel), agents-cli version, and the installed-agent
- * listing. This replaces three sequential probes (`true` + `agents --version` +
- * `agents view`) — 3 handshakes collapse to 1. Reachability keys off the sentinel
- * rather than the exit code, so a command that ran-but-failed is never mistaken
- * for a dead connection (only ssh's own failure drops the sentinel).
- */
-/**
- * The one-shot readiness command (version + sentinel + agent listing). The
- * Windows branch emits the sentinel with `Write-Output` and branches on
- * `$LASTEXITCODE` (no `printf`/`||`); `parseReadyProbe` keys off the sentinel
- * substring, so the missing leading newline vs the POSIX `printf '\n…'` form is
- * absorbed by its `.trim()`. Pure/exported so both branches are unit-testable.
- *
- * With `ingestUsage`, the probe first runs `agents __usage-ingest` on the
- * dispatcher's daemon-state envelope, which the caller pipes to stdin
- * (PHNX-4116): the chosen worker then holds the dispatcher's current usage
- * numbers at dispatch instead of waiting for the next 15-minute usage-sync
- * tick. The ingest writes nothing to stdout (only `--reply` does), so the
- * version/sentinel/listing shape `parseReadyProbe` reads is unchanged. On
- * Windows the `agents.ps1` shim drops ssh-piped stdin, so PowerShell reads it
- * into a temp file and hands the verb `--from <path>`.
- */
 export declare function buildReadyProbeCommand(os?: string, opts?: {
     ingestUsage?: boolean;
 }): string;
 export declare function readyProbe(target: string, os?: string, extraSshArgs?: string[]): ReadyProbe;
-/** Pure parser for `readyProbe` output (unit-tested without ssh). */
 export declare function parseReadyProbe(stdout: string): ReadyProbe;
-/** True if `view` output lists the named agent (word-boundary, case-insensitive). */
 export declare function viewHasAgent(view: string, agent: string): boolean;
-/**
- * True when `version` is a concrete pin the remote must already have installed
- * (e.g. `0.145.0`, `2.1.207`). Aliases (`latest` / `oldest` / `pinned` /
- * `default` / `all` / `any`) resolve against the remote's own install set and
- * are not preflight-checked here.
- */
 export declare function isConcreteVersionPin(version?: string | null): boolean;
-/**
- * Installed version strings for `agent` from `agents view --json` output.
- * Returns `[]` when the agent row is absent, `undefined` when `view` is not
- * JSON (text `agents list` fallback) so callers can degrade.
- */
 export declare function viewAgentVersions(view: string, agent: string): string[] | undefined;
-/**
- * Whether a concrete `agent@version` is installed according to remote view
- * output. JSON path is authoritative; text listing falls back to a whole-token
- * version match. `undefined` only when the text path has the agent but no
- * version token to confirm against (callers treat that as unverified).
- */
 export declare function viewHasAgentVersion(view: string, agent: string, version: string): boolean | undefined;
-/** Actionable fail-loud message for a missing remote pin (RUSH-2313). */
 export declare function missingPinnedVersionMessage(hostName: string, agent: string, version: string, installed?: string[]): string;
-/** Account eligibility extracted from one device's `agents view --json`. */
 interface ViewAgentAccountEligibility {
-    /** At least one account can launch immediately. */
     signedIn: boolean | undefined;
-    /** At least one account can launch immediately or enter the harness login flow. */
     pickerEligible: boolean | undefined;
-    /**
-     * The remote box's own aggregate exclusion reason when it is not signed in
-     * (`runReady.reason` — e.g. `all signed_out`), for the operator-facing
-     * placement error. Undefined when ready, absent, or on an older remote CLI.
-     */
     reason?: string;
 }
 /**
@@ -141,33 +63,12 @@ export declare function viewAgentAccountEligibility(view: string, agent: string,
 export declare function viewAgentSignedIn(view: string, agent: string): boolean | undefined;
 interface EnsureReadyOptions {
     agent: string;
-    /**
-     * Explicit version pin (e.g. `"0.145.0"`). Concrete pins fail loud when the
-     * remote does not have that version installed so a detached `--no-follow`
-     * dispatch never reports "Dispatched" for a pin the box cannot run
-     * (RUSH-2313). Aliases (`latest` / …) are left for the remote CLI to resolve.
-     */
     version?: string;
-    /** Throw instead of warn when the agent isn't installed remotely. */
     requireAgent?: boolean;
 }
-/**
- * Pure readiness verdict for the agent/version half of {@link ensureHostReady}
- * (unit-tested without SSH). Returns warnings for soft agent-missing cases, or
- * throws (via the caller's `throw new Error`) when a concrete pin is missing.
- */
 export declare function evaluateHostAgentInstall(view: string, opts: EnsureReadyOptions, hostName: string): {
     warnings: string[];
 };
-/**
- * Verify a host can run the agent: reachable + agents-cli present. Throws with an
- * actionable message otherwise. Agent-not-installed is a warning by default (the
- * remote `agents run` will surface it); pass requireAgent to make it fatal.
- * A concrete `version` pin always fails loud when that version is absent
- * (RUSH-2313) — never a silent "Dispatched" for a pin the box cannot run.
- *
- * One ssh round-trip (`readyProbe`) covers all three checks.
- */
 export declare function ensureHostReady(host: Host, opts: EnsureReadyOptions): {
     warnings: string[];
 };