@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/devices/registry.d.ts

@@ -1,60 +1,30 @@
 import type { Meta } from '../types.js';
 import type { IgnoredDeviceEntry } from '../fleet/types.js';
-/** Operating-system family of a device, used to pick the remote shell. */
 export type DevicePlatform = 'windows' | 'linux' | 'macos' | 'unknown';
-/** Remote shell dialect derived from the platform. */
 export type DeviceShell = 'powershell' | 'posix';
-/** How `agents ssh` authenticates to a device. Both are first-class, fully
- * non-interactive: `key` uses the ssh agent / on-disk keys, `password` pulls
- * the secret from a Keychain-backed secrets bundle via an askpass shim. */
 export type DeviceAuthMethod = 'key' | 'password';
-/** How to reach a device on the network. */
 export interface DeviceAddress {
-    /** Where the address came from: a Tailscale node, or a manual entry. */
     via: 'tailscale' | 'manual';
-    /** Fully-qualified DNS name (Tailscale MagicDNS), without a trailing dot. */
     dnsName?: string;
-    /** Raw IP address (IPv4 preferred). */
     ip?: string;
 }
-/** Authentication settings for a device. */
 export interface DeviceAuth {
     method: DeviceAuthMethod;
-    /** Explicit private-key path passed to OpenSSH for key authentication. */
     identityFile?: string;
-    /** Secrets bundle holding the password (when method === 'password'). */
     bundle?: string;
-    /** Key within the bundle whose value is the password. Defaults to 'password'. */
     bundleKey?: string;
 }
-/** Last-known Tailscale reachability snapshot for a device. */
 export interface DeviceTailscale {
     online: boolean;
-    /** True when the last handshake was a direct (non-relayed) connection. */
     direct: boolean;
-    /** DERP relay region code (e.g. 'sfo'); empty when direct. */
     relay?: string;
     lastSeen?: string;
 }
-/**
- * Verdict of the last live SSH reachability probe (RUSH-1965).
- *
- * The live `agents devices` probe already learns whether a box answered right
- * now; this persists that answer so the online/offline word is read from a
- * fresh probe instead of the potentially-stale {@link DeviceTailscale.online}
- * snapshot (which only `agents devices sync` / the daemon ever writes). A
- * `via:"manual"` device — which never gets a tailscale peer entry — gets a
- * reachability verdict this way too, so it stops rendering "offline forever".
- */
 export interface DeviceReachability {
-    /** Whether the last live probe reached the device. */
     reachable: boolean;
-    /** Transport the verdict came through — the address kind used to dial it. */
     via?: DeviceAddress['via'];
-    /** ISO-8601 timestamp of the probe that produced this verdict. */
     checkedAt: string;
 }
-/** A single registered device. */
 export interface DeviceProfile {
     name: string;
     platform: DevicePlatform;
@@ -63,79 +33,20 @@ export interface DeviceProfile {
     address: DeviceAddress;
     auth: DeviceAuth;
     tailscale?: DeviceTailscale;
-    /** Last live SSH-probe reachability verdict (RUSH-1965). Preferred over the
-     * cached {@link DeviceTailscale.online} snapshot when rendering online/offline,
-     * because the live probe reflects whether the box answered right now. */
     reachability?: DeviceReachability;
     createdAt: string;
     updatedAt: string;
 }
-/**
- * Whether a fan-out should dial this device, honouring the preference stated on
- * {@link DeviceProfile.reachability}: the live SSH probe wins over the cached
- * {@link DeviceTailscale.online} snapshot.
- *
- * Reading only `tailscale.online` is wrong in both directions, and both were
- * live on a real fleet. A `via:"manual"` device never gets a tailscale peer
- * entry at all, so its `online` is permanently `undefined` and a strict
- * `=== true` test skipped it forever — every session on that box was invisible
- * to the cross-fleet sweep. Conversely a box that has since gone to sleep keeps
- * a stale `online:true` and gets dialed, burning a full ConnectTimeout and
- * reporting a false "unreachable" that callers treat as doubt.
- */
 export declare function isDialableDevice(d: DeviceProfile): boolean;
-/** Map of device name to profile. */
 export type DeviceRegistry = Record<string, DeviceProfile>;
-/**
- * `--device` values that mean "resolve me", not "connect to a box with this
- * name". A real device registered under one of these would be unreachable,
- * and pinning `interactive.host` to one is a misconfiguration that has to fail
- * at WRITE time — otherwise the read side can only report "none is set", which
- * tells the user to run the command they just ran.
- */
 export declare const RESERVED_DEVICE_NAMES: Set<string>;
-/**
- * Throw if `name` is not usable as an ssh alias (no spaces, quotes, etc.).
- *
- * SHAPE ONLY. Safe on read paths, which must keep working for a name that is
- * already registered — including one this version would refuse to create.
- */
 export declare function assertValidDeviceName(name: string): void;
-/**
- * Throw if `name` cannot be used for a NEW device: bad shape, or a reserved
- * routing sentinel.
- *
- * Deliberately separate from {@link assertValidDeviceName}, and called from
- * exactly two kinds of place: `agents devices add <name>`, and the config keys
- * that point AT a device (`interactive.host`).
- *
- * Not from `upsertDevice`, `addIgnored` or the discovery writers. Those all
- * receive tailnet node names the user never typed — `devices sync` upserts every
- * observed node in a loop with no per-node catch, so one node named `auto` would
- * abort the entire sync and register nothing after it. A name the fleet OBSERVES
- * is not a name anyone CHOSE; only the second kind is policy's business.
- */
 export declare function assertRegistrableDeviceName(name: string): void;
-/** Map a Tailscale `OS` field to our platform enum. */
 export declare function platformFromOs(os: string | undefined): DevicePlatform;
-/** The remote shell a platform speaks. */
 export declare function shellForPlatform(platform: DevicePlatform): DeviceShell;
-/**
- * Load all devices from the registry file. Returns an empty object only when
- * the file does not exist. A malformed file is a hard error — silently
- * returning {} would let the next write wipe the user's device list.
- */
 export declare function loadDevices(): Promise<DeviceRegistry>;
-/**
- * Synchronous {@link loadDevices} for callers already on a sync path (e.g. the
- * `agents sessions --device` fan-out builds its ssh command strings synchronously
- * and only needs the target's platform to pick POSIX vs PowerShell). Same
- * missing-file/corruption contract as {@link loadDevices}.
- */
 export declare function loadDevicesSync(): DeviceRegistry;
-/** Get a single device profile, or null if it is not registered. */
 export declare function getDevice(name: string): Promise<DeviceProfile | null>;
-/** Fields a caller may supply when creating or updating a device. */
 export interface DeviceInput {
     platform?: DevicePlatform;
     user?: string;
@@ -144,65 +55,13 @@ export interface DeviceInput {
     tailscale?: DeviceTailscale;
     reachability?: DeviceReachability;
 }
-/**
- * Create the device if absent, otherwise merge the supplied fields into the
- * existing profile. `shell` is always re-derived from the (possibly new)
- * platform so the two can never drift. Returns the resulting profile.
- */
 export declare function upsertDevice(name: string, input: DeviceInput): Promise<DeviceProfile>;
-/**
- * Persist live reachability verdicts for many devices in one locked pass
- * (RUSH-1965). A no-op verdict (same `reachable` and not newer than what's
- * stored) is skipped, so a cache-served `agents devices` render doesn't churn
- * the registry every call; only a flip or a fresher probe writes. Unlike
- * {@link upsertDevice} this does NOT bump `updatedAt` — reachability is
- * transient liveness (like the tailscale snapshot), not a profile edit. Unknown
- * device names are ignored. Returns the names actually updated.
- */
 export declare function writeReachability(updates: Record<string, DeviceReachability>): Promise<string[]>;
-/** Remove a device. Returns false if it was not registered. */
 export declare function removeDevice(name: string): Promise<boolean>;
-/**
- * The ignore-list: tailscale node names the user explicitly dismissed from
- * auto-discovery. A dismissed node is deliberately NOT a device (it never
- * enters the registry), so it has no per-device doc — its home is the central,
- * TRACKED `~/.agents/agents.yaml` under a `fleet.ignored` list, which syncs
- * fleet-wide via `agents repo push/pull`: a dismissal on one box stops the
- * suggestion on every box (RUSH-3062). Auto-discovery (`runDeviceSync`'s
- * pending diff) subtracts this set, so an ignored node never re-surfaces as a
- * suggestion. Writes go through `updateMeta` — the central-config write path
- * (withMetaLock + atomic write) — so two agents writing concurrently cannot
- * corrupt it, and no second lock is hand-rolled here.
- */
 export type { IgnoredDeviceEntry } from '../fleet/types.js';
-/**
- * The EFFECTIVE ignore-list: the union of every box's device doc
- * `fleet.ignored` (deduped by node name, newest `ignoredAt` winning) plus any
- * lingering central-legacy `fleet.ignored` block (drained by the migration).
- * Deterministic and order-independent. A malformed block is a hard error for the
- * same reason the registry is: silently returning [] would let the next write
- * wipe the user's dismissals.
- */
 export declare function loadIgnoredEntries(meta?: Meta): IgnoredDeviceEntry[];
-/** Load the set of ignored node names. Same corruption contract as
- * {@link loadIgnoredEntries}. */
 export declare function loadIgnored(): Promise<Set<string>>;
-/** True if `name` is on the ignore-list. */
 export declare function isIgnored(name: string): Promise<boolean>;
-/**
- * Union `names` into the meta's ignore-list, stamping new entries with
- * `ignoredAt` and THIS machine's id. Existing entries keep their original
- * who/when, so re-adding a name is a true no-op. Returns the input unchanged
- * when no name is new. Exported for the one-shot legacy-store migration in
- * lib/devices/config-migration.ts.
- */
 export declare function withIgnoredAdded(meta: Meta, names: string[], ignoredAt: string): Meta;
-/** Add a node name to THIS box's ignore-list (device doc). Idempotent. Returns
- * the resulting cross-box union of dismissed names. Reads only the device docs
- * for the return value — a corrupt central-legacy block surfaces loudly on the
- * effective read path ({@link loadIgnoredEntries}), never blocks a per-box
- * write that does not touch central at all. */
 export declare function addIgnored(name: string): Promise<Set<string>>;
-/** Remove a node name from the ignore-list (un-ignore). Returns false if it was
- * not ignored. */
 export declare function removeIgnored(name: string): Promise<boolean>;

package/dist/lib/devices/registry.js

@@ -1,18 +1,3 @@
-/**
- * Device registry.
- *
- * Manages the persistent registry of SSH device profiles stored at
- * ~/.agents/.history/devices/registry.json. Each profile records what we had
- * to re-derive by hand the first time we reached a host: its platform (so we
- * know PowerShell vs POSIX), the login user, how to address it (Tailscale
- * DNS name / IP), and how to authenticate (pubkey, or a password pulled from
- * a secrets bundle).
- *
- * Like the team registry this is per-machine runtime state (it embeds a host
- * list + addresses) and lives under .history/ so it is NOT pulled in by
- * `agents repo push`. The load/save/lock plumbing is a deliberate clone of
- * src/lib/teams/registry.ts so the data-loss guarantees match exactly.
- */
 import * as fs from 'fs/promises';
 import * as fsSync from 'fs';
 import * as path from 'path';
@@ -23,39 +8,7 @@ import { machineId } from '../machine-id.js';
 import { addIgnoredEntry, unionDeviceIgnored } from './device-docs.js';
 import { logAndContinueOnLockCompromised } from '../lock-compromise.js';
 import { removeStatsCacheEntry } from './stats-cache.js';
-/**
- * Whether a fan-out should dial this device, honouring the preference stated on
- * {@link DeviceProfile.reachability}: the live SSH probe wins over the cached
- * {@link DeviceTailscale.online} snapshot.
- *
- * Reading only `tailscale.online` is wrong in both directions, and both were
- * live on a real fleet. A `via:"manual"` device never gets a tailscale peer
- * entry at all, so its `online` is permanently `undefined` and a strict
- * `=== true` test skipped it forever — every session on that box was invisible
- * to the cross-fleet sweep. Conversely a box that has since gone to sleep keeps
- * a stale `online:true` and gets dialed, burning a full ConnectTimeout and
- * reporting a false "unreachable" that callers treat as doubt.
- */
 export function isDialableDevice(d) {
-    // Union, deliberately: either signal saying "go" is enough. A probe may only
-    // ADD a peer to the sweep, never remove one.
-    //
-    // The probe is not trustworthy enough to exclude on. It runs with a short SSH
-    // budget, so on a congested tailnet it returns false negatives — observed
-    // marking the LOCAL machine unreachable, and flipping a live worker box from
-    // reachable to unreachable nine minutes apart. Letting that shrink the sweep
-    // would hide sessions on healthy boxes, a worse failure than the one below.
-    //
-    // The snapshot alone is not enough either: a device registered with
-    // `address.via: "manual"` never gets a tailscale peer entry, so `online`
-    // stays undefined and a strict `=== true` test skipped it forever, making
-    // every session on that box unresolvable from any other machine.
-    //
-    // So: no tailscale block at all is unknown-not-offline (the rule `ssh.ts`
-    // renderDeviceTable and the ext's `isDeviceOnline` already use, so the picker
-    // and the sweep agree on who exists), and a positive probe rescues a device
-    // whose snapshot says offline. The cost of dialing a box that is actually
-    // asleep is one ConnectTimeout — the pre-existing behaviour, not a regression.
     if (d.reachability?.reachable)
         return true;
     return !d.tailscale || d.tailscale.online === true;
@@ -63,42 +16,13 @@ export function isDialableDevice(d) {
 function registryPath() {
     return getDevicesRegistryPath();
 }
-/** Valid logical device name: the ssh-alias charset, so it renders into an
- * unambiguous `Host` stanza and is safe as an ssh target. */
 const DEVICE_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
-/**
- * `--device` values that mean "resolve me", not "connect to a box with this
- * name". A real device registered under one of these would be unreachable,
- * and pinning `interactive.host` to one is a misconfiguration that has to fail
- * at WRITE time — otherwise the read side can only report "none is set", which
- * tells the user to run the command they just ran.
- */
 export const RESERVED_DEVICE_NAMES = new Set(['auto', 'interactive', 'all']);
-/**
- * Throw if `name` is not usable as an ssh alias (no spaces, quotes, etc.).
- *
- * SHAPE ONLY. Safe on read paths, which must keep working for a name that is
- * already registered — including one this version would refuse to create.
- */
 export function assertValidDeviceName(name) {
     if (!DEVICE_NAME_RE.test(name)) {
         throw new Error(`Invalid device name ${JSON.stringify(name)}. Use letters, digits, '.', '_', '-' (no spaces) — e.g. 'win-mini'.`);
     }
 }
-/**
- * Throw if `name` cannot be used for a NEW device: bad shape, or a reserved
- * routing sentinel.
- *
- * Deliberately separate from {@link assertValidDeviceName}, and called from
- * exactly two kinds of place: `agents devices add <name>`, and the config keys
- * that point AT a device (`interactive.host`).
- *
- * Not from `upsertDevice`, `addIgnored` or the discovery writers. Those all
- * receive tailnet node names the user never typed — `devices sync` upserts every
- * observed node in a loop with no per-node catch, so one node named `auto` would
- * abort the entire sync and register nothing after it. A name the fleet OBSERVES
- * is not a name anyone CHOSE; only the second kind is policy's business.
- */
 export function assertRegistrableDeviceName(name) {
     assertValidDeviceName(name);
     if (RESERVED_DEVICE_NAMES.has(name.trim().toLowerCase())) {
@@ -106,7 +30,6 @@ export function assertRegistrableDeviceName(name) {
             `Reserved: ${[...RESERVED_DEVICE_NAMES].join(', ')}.`);
     }
 }
-/** Map a Tailscale `OS` field to our platform enum. */
 export function platformFromOs(os) {
     switch ((os ?? '').toLowerCase()) {
         case 'windows':
@@ -120,15 +43,9 @@ export function platformFromOs(os) {
             return 'unknown';
     }
 }
-/** The remote shell a platform speaks. */
 export function shellForPlatform(platform) {
     return platform === 'windows' ? 'powershell' : 'posix';
 }
-/**
- * Run `fn` while holding an exclusive cross-process lock on the registry file.
- * proper-lockfile requires the target to exist, so we touch it first. Stale
- * locks (from crashed callers) auto-expire after `stale` ms.
- */
 async function withRegistryLock(p, fn) {
     await fs.mkdir(path.dirname(p), { recursive: true });
     if (!fsSync.existsSync(p)) {
@@ -152,11 +69,6 @@ async function withRegistryLock(p, fn) {
         await release();
     }
 }
-/**
- * Load all devices from the registry file. Returns an empty object only when
- * the file does not exist. A malformed file is a hard error — silently
- * returning {} would let the next write wipe the user's device list.
- */
 export async function loadDevices() {
     const p = registryPath();
     let raw;
@@ -175,12 +87,6 @@ export async function loadDevices() {
         throw new Error(`Device registry corrupted at ${p}: ${err?.message ?? err}. Inspect and restore from backup.`);
     }
 }
-/**
- * Synchronous {@link loadDevices} for callers already on a sync path (e.g. the
- * `agents sessions --device` fan-out builds its ssh command strings synchronously
- * and only needs the target's platform to pick POSIX vs PowerShell). Same
- * missing-file/corruption contract as {@link loadDevices}.
- */
 export function loadDevicesSync() {
     const p = registryPath();
     let raw;
@@ -202,16 +108,10 @@ export function loadDevicesSync() {
 async function saveDevices(reg) {
     atomicWriteJsonSync(registryPath(), reg);
 }
-/** Get a single device profile, or null if it is not registered. */
 export async function getDevice(name) {
     const reg = await loadDevices();
     return reg[name] ?? null;
 }
-/**
- * Create the device if absent, otherwise merge the supplied fields into the
- * existing profile. `shell` is always re-derived from the (possibly new)
- * platform so the two can never drift. Returns the resulting profile.
- */
 export async function upsertDevice(name, input) {
     assertValidDeviceName(name);
     const p = registryPath();
@@ -237,15 +137,6 @@ export async function upsertDevice(name, input) {
         return merged;
     });
 }
-/**
- * Persist live reachability verdicts for many devices in one locked pass
- * (RUSH-1965). A no-op verdict (same `reachable` and not newer than what's
- * stored) is skipped, so a cache-served `agents devices` render doesn't churn
- * the registry every call; only a flip or a fresher probe writes. Unlike
- * {@link upsertDevice} this does NOT bump `updatedAt` — reachability is
- * transient liveness (like the tailscale snapshot), not a profile edit. Unknown
- * device names are ignored. Returns the names actually updated.
- */
 export async function writeReachability(updates) {
     const names = Object.keys(updates);
     if (names.length === 0)
@@ -257,13 +148,13 @@ export async function writeReachability(updates) {
         for (const name of names) {
             const prev = reg[name];
             if (!prev)
-                continue; // never resurrect a device the user removed
+                continue;
             const next = updates[name];
             const cur = prev.reachability;
             if (cur &&
                 cur.reachable === next.reachable &&
                 Date.parse(cur.checkedAt) >= Date.parse(next.checkedAt)) {
-                continue; // unchanged verdict, no fresher timestamp — skip the write
+                continue;
             }
             reg[name] = { ...prev, reachability: next };
             changed.push(name);
@@ -273,7 +164,6 @@ export async function writeReachability(updates) {
         return changed;
     });
 }
-/** Remove a device. Returns false if it was not registered. */
 export async function removeDevice(name) {
     const p = registryPath();
     return withRegistryLock(p, async () => {
@@ -286,13 +176,6 @@ export async function removeDevice(name) {
         return true;
     });
 }
-/**
- * The full ignore-list entries — who dismissed a node, when, and on which box —
- * the typed read side for `agents devices ignored`. Absent `fleet.ignored` =>
- * []. A malformed block is a hard error for the same reason the registry is:
- * silently returning [] would let the next write wipe the user's dismissals.
- */
-/** Validate a raw ignore-list block, or throw with `where` naming the file. */
 function assertIgnoredShape(raw, where) {
     if (!Array.isArray(raw) ||
         raw.some((e) => !e ||
@@ -302,11 +185,6 @@ function assertIgnoredShape(raw, where) {
         throw new Error(`Device ignore-list corrupted in ${where}: expected a list of { name, ignoredAt, ignoredOn } entries. Inspect and repair it.`);
     }
 }
-/**
- * THIS box's OWN dismissals — the writable slice in `meta.deviceFleet.ignored`
- * (the device doc). `withIgnoredAdded`/`removeIgnored` operate on this so a box
- * only ever edits its own folder (PHNX-3315). Absent => [].
- */
 function loadOwnIgnoredEntries(meta) {
     const raw = meta.deviceFleet?.ignored;
     if (raw === undefined)
@@ -314,14 +192,6 @@ function loadOwnIgnoredEntries(meta) {
     assertIgnoredShape(raw, `devices/<machine>/agents.yaml (fleet.ignored)`);
     return raw;
 }
-/**
- * The EFFECTIVE ignore-list: the union of every box's device doc
- * `fleet.ignored` (deduped by node name, newest `ignoredAt` winning) plus any
- * lingering central-legacy `fleet.ignored` block (drained by the migration).
- * Deterministic and order-independent. A malformed block is a hard error for the
- * same reason the registry is: silently returning [] would let the next write
- * wipe the user's dismissals.
- */
 export function loadIgnoredEntries(meta = readMeta()) {
     const byName = new Map();
     const central = meta.fleet?.ignored;
@@ -334,24 +204,14 @@ export function loadIgnoredEntries(meta = readMeta()) {
         addIgnoredEntry(byName, e);
     return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
 }
-/** Load the set of ignored node names. Same corruption contract as
- * {@link loadIgnoredEntries}. */
 export async function loadIgnored() {
     return new Set(loadIgnoredEntries().map((e) => e.name));
 }
-/** True if `name` is on the ignore-list. */
 export async function isIgnored(name) {
     return (await loadIgnored()).has(name);
 }
-/**
- * Union `names` into the meta's ignore-list, stamping new entries with
- * `ignoredAt` and THIS machine's id. Existing entries keep their original
- * who/when, so re-adding a name is a true no-op. Returns the input unchanged
- * when no name is new. Exported for the one-shot legacy-store migration in
- * lib/devices/config-migration.ts.
- */
 export function withIgnoredAdded(meta, names, ignoredAt) {
-    const entries = loadOwnIgnoredEntries(meta); // throws on a corrupted block — never wipe it
+    const entries = loadOwnIgnoredEntries(meta);
     const have = new Set(entries.map((e) => e.name));
     const fresh = names.filter((n) => !have.has(n));
     if (fresh.length === 0)
@@ -362,22 +222,15 @@ export function withIgnoredAdded(meta, names, ignoredAt) {
     ].sort((a, b) => a.name.localeCompare(b.name));
     return { ...meta, deviceFleet: { ...meta.deviceFleet, ignored } };
 }
-/** Add a node name to THIS box's ignore-list (device doc). Idempotent. Returns
- * the resulting cross-box union of dismissed names. Reads only the device docs
- * for the return value — a corrupt central-legacy block surfaces loudly on the
- * effective read path ({@link loadIgnoredEntries}), never blocks a per-box
- * write that does not touch central at all. */
 export async function addIgnored(name) {
     assertValidDeviceName(name);
     updateMeta((m) => withIgnoredAdded(m, [name], new Date().toISOString()));
     return new Set(unionDeviceIgnored().map((e) => e.name));
 }
-/** Remove a node name from the ignore-list (un-ignore). Returns false if it was
- * not ignored. */
 export async function removeIgnored(name) {
     let removed = false;
     updateMeta((m) => {
-        const entries = loadOwnIgnoredEntries(m); // only this box's own dismissals are ours to drop
+        const entries = loadOwnIgnoredEntries(m);
         const next = entries.filter((e) => e.name !== name);
         if (next.length === entries.length)
             return m;

package/dist/lib/devices/resolve-profile.d.ts

@@ -1,20 +1,2 @@
-/**
- * The effective device profile: the registry's discovery record overlaid with
- * the operator's config (the per-device doc `devices/<name>/agents.yaml`
- * `config:` block over central `fleet.defaults.config`).
- *
- * The registry (`~/.agents/.history/devices/registry.json`) stays the
- * discovery cache — address, Tailscale snapshot, reachability, createdAt. The
- * central config owns the operator-set profile fields: `ssh.user`, `ssh.auth`,
- * `ssh.bundle`, `ssh.bundle-key`, `ssh.identity-file`, and `platform`. A config
- * value WINS over the registry field so `agents devices config <name>` takes
- * effect from any box without re-discovery; an unset key falls back to the
- * registry value.
- *
- * Sync and cheap (readMeta is cached), so dial/render call sites apply it at
- * their entry point rather than threading a resolved profile through every
- * signature. Resolving an already-resolved profile is idempotent.
- */
 import { type DeviceProfile } from './registry.js';
-/** Overlay the central config's ssh.* / platform / user keys onto a registry profile. */
 export declare function resolveDeviceProfile(device: DeviceProfile): DeviceProfile;

package/dist/lib/devices/resolve-profile.js

@@ -1,23 +1,5 @@
-/**
- * The effective device profile: the registry's discovery record overlaid with
- * the operator's config (the per-device doc `devices/<name>/agents.yaml`
- * `config:` block over central `fleet.defaults.config`).
- *
- * The registry (`~/.agents/.history/devices/registry.json`) stays the
- * discovery cache — address, Tailscale snapshot, reachability, createdAt. The
- * central config owns the operator-set profile fields: `ssh.user`, `ssh.auth`,
- * `ssh.bundle`, `ssh.bundle-key`, `ssh.identity-file`, and `platform`. A config
- * value WINS over the registry field so `agents devices config <name>` takes
- * effect from any box without re-discovery; an unset key falls back to the
- * registry value.
- *
- * Sync and cheap (readMeta is cached), so dial/render call sites apply it at
- * their entry point rather than threading a resolved profile through every
- * signature. Resolving an already-resolved profile is idempotent.
- */
 import { shellForPlatform, } from './registry.js';
 import { readDeviceConfigValues } from '../device-config.js';
-/** Overlay the central config's ssh.* / platform / user keys onto a registry profile. */
 export function resolveDeviceProfile(device) {
     const config = readDeviceConfigValues(device.name);
     const platform = config.platform ?? device.platform;

package/dist/lib/devices/resolve-target.d.ts

@@ -1,8 +1,6 @@
 import { splitUserHost, type MatchHostOptions } from '../hosts/registry.js';
 import { type DeviceProfile } from './registry.js';
 export { splitUserHost };
-/** A dialable peer: the ssh target, the machine id used to tag its rows, a
- * display name, and the OS family that picks the remote shell dialect. */
 interface ResolvedSshTarget {
     target: string;
     machine: string;
@@ -14,24 +12,6 @@ interface ResolvedExplicitTargetSet {
     targets: ResolvedSshTarget[];
     unresolved: string[];
 }
-/**
- * Resolve a target token to a full {@link DeviceProfile} for `agents ssh`. Same
- * grammar as the fan-out, but returns the whole profile (auth, shell, tailscale
- * metadata) `buildSshInvocation` needs. A registered `name` / `user@device`
- * yields that profile (login user overridden by any `user@`); an ad-hoc
- * `user@host` / IP / FQDN literal yields a synthesized key-auth profile. A bare
- * unregistered alias (no `@`/dot) — or an ssh_config-only alias, which `agents
- * ssh` has never dialed — returns undefined so the caller reports "Unknown
- * device" rather than dialing a literal. `token` may also be the `auto`
- * affinity sentinel (RUSH-2185); `opts.resolveAuto` overrides the pick (tests).
- */
 export declare function resolveDeviceTarget(token: string, opts?: Pick<MatchHostOptions, 'resolveAuto'>): Promise<DeviceProfile | undefined>;
-/**
- * Resolve an explicit `--device`/`--device` list to dialable targets. A token that
- * fails the injection guard or names nothing reachable is skipped with a stderr
- * note (never fatal — one bad token must not blank the fan-out). Shared by every
- * cross-machine fan-out so they can never diverge onto two routes.
- */
 export declare function resolveExplicitTargets(hosts: string[]): Promise<ResolvedSshTarget[]>;
-/** Resolve explicit tokens while retaining failures for coverage-sensitive callers. */
 export declare function resolveExplicitTargetSet(hosts: string[]): Promise<ResolvedExplicitTargetSet>;