@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/devices/known-hosts.d.ts

@@ -1,59 +1,14 @@
 import type { DeviceProfile } from './registry.js';
-/** Path to the CLI-managed known_hosts store (created lazily, mode 0600). */
 export declare function managedKnownHostsPath(): string;
-/** Ensure the parent directory of the managed store exists (mode 0700). */
 export declare function ensureManagedKnownHostsDir(file?: string): void;
-/**
- * True if `host` has at least one pinned key line in `content`. Pure (content
- * in) so the match logic is unit-testable without touching disk. Matching is
- * case-insensitive on the hostname, as OpenSSH does.
- */
 export declare function isHostPinnedIn(content: string, host: string): boolean;
-/** True if `host` is pinned in the managed store on disk. */
 export declare function isHostPinned(host: string, file?: string): boolean;
-/**
- * True if a DEVICE's host key is pinned — checked against the SAME host string
- * the ssh connection dials (`hostNameFor(device)`: the Tailscale dnsName/IP that
- * `sshTargetFor` resolves), falling back to the bare device name.
- *
- * A device discovered over the tailnet is pinned under its FQDN
- * (`yosemite-m6.tail….ts.net`), so a caller that checks the bare `device.name`
- * misses the pin and wrongly treats a reachable, pinned peer as unpinned —
- * silently excluding it from usage/auth fan-out while ssh to it would have
- * succeeded (PHNX-3505). Accepting the bare name too keeps a device pinned only
- * under its short name working. `isPinned` is injectable for tests; it defaults
- * to the managed on-disk store.
- */
 export declare function isDevicePinned(device: DeviceProfile, isPinned?: (host: string) => boolean): boolean;
-/**
- * The host-key-checking ssh options for a connection.
- *
- * Always points `UserKnownHostsFile` at the managed store so learned and pinned
- * keys live in exactly one CLI-owned file. `StrictHostKeyChecking` is `yes` once
- * the host is pinned (a key swap is refused) and `accept-new` before that
- * (genuine first enrollment learns the key into the managed store, which pins it
- * for every subsequent connect). Pure given `pinned`, so the policy is testable.
- */
 export declare function hostKeyCheckingOpts(pinned: boolean, file?: string): string[];
-/**
- * The key lines in `scanned` (ssh-keyscan output) not already present in
- * `existing`. Comments and blank lines are dropped; whitespace is normalized so
- * a re-scan of an already-pinned key is a no-op. Pure, so the idempotent-append
- * contract is unit-testable without spawning ssh-keyscan.
- */
 export declare function newKnownHostsLines(existing: string, scanned: string): string[];
 interface PinResult {
-    /** True if the host is pinned in the managed store after this call. */
     pinned: boolean;
-    /** How many new key lines were appended. */
     added: number;
 }
-/**
- * Merge `ssh-keyscan` output for `host` into the managed store at `file`,
- * idempotently, and report whether `host` is pinned afterward. Split out from
- * {@link pinHostKey} so the store-write half — the part that decides a scanned
- * key now counts as pinned — is unit-testable with real keyscan text and no
- * network (the spawn stays in `pinHostKey`).
- */
 export declare function recordScannedKeys(host: string, scanned: string, file?: string): PinResult;
 export {};

package/dist/lib/devices/known-hosts.js

@@ -1,21 +1,3 @@
-/**
- * Managed known_hosts pinning for the device fleet (RUSH-1767).
- *
- * The shared SSH baseline uses `StrictHostKeyChecking=accept-new`
- * (trust-on-first-use): it silently accepts whatever key answers on the FIRST
- * connect, so a machine-in-the-middle present in that window is trusted forever
- * and never re-checked. This module gives the CLI its own known_hosts store,
- * kept apart from the user's `~/.ssh/known_hosts`, so a device's host key can be
- * *pinned*: once a key is recorded here, connections verify against it with
- * `StrictHostKeyChecking=yes`, so a later key swap is refused instead of
- * silently re-accepted.
- *
- * The learn-then-pin flow: the first `agents ssh`/fleet connection to a host is
- * still `accept-new`, but it writes the learned key into THIS store, which pins
- * it for every subsequent connect. Credential copies (`run --device --copy-creds`)
- * refuse to run against a host that isn't pinned here — see
- * `commands/exec.ts` — so tokens never ride an unverified first connect.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import { spawnSync } from 'child_process';
@@ -23,15 +5,12 @@ import { getCacheDir } from '../state.js';
 import { assertValidSshTarget } from '../ssh-exec.js';
 import { parseKnownHosts } from '../hosts/ssh-config.js';
 import { hostNameFor } from './ssh-config.js';
-/** Path to the CLI-managed known_hosts store (created lazily, mode 0600). */
 export function managedKnownHostsPath() {
     return path.join(getCacheDir(), 'devices', 'known_hosts');
 }
-/** Ensure the parent directory of the managed store exists (mode 0700). */
 export function ensureManagedKnownHostsDir(file = managedKnownHostsPath()) {
     fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
 }
-/** Read the managed store, or '' when it does not exist yet. */
 function readManagedKnownHosts(file = managedKnownHostsPath()) {
     try {
         return fs.readFileSync(file, 'utf-8');
@@ -40,59 +19,25 @@ function readManagedKnownHosts(file = managedKnownHostsPath()) {
         return '';
     }
 }
-/**
- * True if `host` has at least one pinned key line in `content`. Pure (content
- * in) so the match logic is unit-testable without touching disk. Matching is
- * case-insensitive on the hostname, as OpenSSH does.
- */
 export function isHostPinnedIn(content, host) {
     const needle = host.trim().toLowerCase();
     if (!needle)
         return false;
     return parseKnownHosts(content).some((h) => h.toLowerCase() === needle);
 }
-/** True if `host` is pinned in the managed store on disk. */
 export function isHostPinned(host, file = managedKnownHostsPath()) {
     return isHostPinnedIn(readManagedKnownHosts(file), host);
 }
-/**
- * True if a DEVICE's host key is pinned — checked against the SAME host string
- * the ssh connection dials (`hostNameFor(device)`: the Tailscale dnsName/IP that
- * `sshTargetFor` resolves), falling back to the bare device name.
- *
- * A device discovered over the tailnet is pinned under its FQDN
- * (`yosemite-m6.tail….ts.net`), so a caller that checks the bare `device.name`
- * misses the pin and wrongly treats a reachable, pinned peer as unpinned —
- * silently excluding it from usage/auth fan-out while ssh to it would have
- * succeeded (PHNX-3505). Accepting the bare name too keeps a device pinned only
- * under its short name working. `isPinned` is injectable for tests; it defaults
- * to the managed on-disk store.
- */
 export function isDevicePinned(device, isPinned = (host) => isHostPinned(host)) {
     const host = device.address ? hostNameFor(device) : undefined;
     return (host != null && isPinned(host)) || isPinned(device.name);
 }
-/**
- * The host-key-checking ssh options for a connection.
- *
- * Always points `UserKnownHostsFile` at the managed store so learned and pinned
- * keys live in exactly one CLI-owned file. `StrictHostKeyChecking` is `yes` once
- * the host is pinned (a key swap is refused) and `accept-new` before that
- * (genuine first enrollment learns the key into the managed store, which pins it
- * for every subsequent connect). Pure given `pinned`, so the policy is testable.
- */
 export function hostKeyCheckingOpts(pinned, file = managedKnownHostsPath()) {
     return [
         '-o', `UserKnownHostsFile=${file}`,
         '-o', `StrictHostKeyChecking=${pinned ? 'yes' : 'accept-new'}`,
     ];
 }
-/**
- * The key lines in `scanned` (ssh-keyscan output) not already present in
- * `existing`. Comments and blank lines are dropped; whitespace is normalized so
- * a re-scan of an already-pinned key is a no-op. Pure, so the idempotent-append
- * contract is unit-testable without spawning ssh-keyscan.
- */
 export function newKnownHostsLines(existing, scanned) {
     const have = new Set(existing.split('\n').map((l) => l.trim()).filter(Boolean));
     const seen = new Set();
@@ -106,13 +51,6 @@ export function newKnownHostsLines(existing, scanned) {
     }
     return fresh;
 }
-/**
- * Merge `ssh-keyscan` output for `host` into the managed store at `file`,
- * idempotently, and report whether `host` is pinned afterward. Split out from
- * {@link pinHostKey} so the store-write half — the part that decides a scanned
- * key now counts as pinned — is unit-testable with real keyscan text and no
- * network (the spawn stays in `pinHostKey`).
- */
 export function recordScannedKeys(host, scanned, file = managedKnownHostsPath()) {
     ensureManagedKnownHostsDir(file);
     const existing = readManagedKnownHosts(file);
@@ -123,22 +61,7 @@ export function recordScannedKeys(host, scanned, file = managedKnownHostsPath())
     }
     return { pinned: isHostPinned(host, file), added: fresh.length };
 }
-/**
- * `ssh-keyscan` a host at a trusted moment and append any new key lines to the
- * managed store, idempotently. This is the explicit pin path; the implicit one
- * is a normal `accept-new` connection whose learned key lands in the same store.
- * Returns whether the host is pinned afterward.
- *
- * Host-name-agnostic: it scans whatever address it is handed, so it also pins a
- * host `agents ssh` can't reach — notably a bare `~/.ssh/config` `Host` alias,
- * which is not a registered device. The `--copy-creds` gate (commands/exec.ts)
- * calls this for exactly that case so the credential copy is usable for
- * ssh-config-alias hosts (RUSH-1767).
- */
 function pinHostKey(host, opts = {}) {
-    // Same injection guard as sshExec: a host starting with `-` (or carrying shell
-    // metacharacters) must never reach ssh-keyscan as a bare argv where it could
-    // be parsed as a flag.
     assertValidSshTarget(host);
     const file = opts.file ?? managedKnownHostsPath();
     const timeoutMs = opts.timeoutMs ?? 8000;

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

@@ -2,38 +2,7 @@ export interface PendingDevice {
     name: string;
     platform: string;
 }
-/**
- * Drop pending sentinels for devices that are already registered or ignored.
- * Safe without a live tailscale probe — only removes names we know are no
- * longer "new". Used when soft-fail discovery cannot recompute the full
- * pending set, so a test leak or race cannot leave registered fleet boxes in
- * the menu bar's NEW DEVICES section forever.
- */
 export declare function pruneDismissedPendingSentinels(): Promise<void>;
-/**
- * Make the sentinel dir exactly match `pending`: create a file per pending
- * device (content = platform), and delete any leftover sentinel whose device is
- * no longer pending (it got registered, ignored, or left the tailnet). Best-
- * effort — a filesystem error here must never crash the daemon, so callers pass
- * this through their existing try/catch.
- *
- * The sentinel writer is the single authoritative choke point every discovery
- * path flows through (the daemon device-probe timer and `agents sync`), so it
- * re-subtracts the persisted ignore-list AND the registered roster rather than
- * trusting the caller's `pending` set. That closes two races:
- *   - probe/ignore (RUSH-2495): a probe that computed `pending` BEFORE the user
- *     pressed "Ignore" would otherwise re-create the just-dismissed device's
- *     sentinel and the menu bar would re-surface it.
- *   - registry-empty pollution: a process that had AGENTS_DEVICES_DIR redirected
- *     (tests / hermetic runs) but still wrote the live devices-pending dir
- *     treated every tailnet node as new — including already-registered fleet
- *     boxes. Re-subtracting the live registry means those phantoms are never
- *     written and are removed if they already exist.
- */
 export declare function reconcilePendingSentinels(pending: PendingDevice[]): Promise<void>;
-/** Remove one device's pending sentinel (after the user registers or ignores it).
- * No-op if it doesn't exist. */
 export declare function clearPendingSentinel(name: string): void;
-/** Read the current pending sentinels (name + platform). Used by tests and any
- * TS-side consumer; the menu-bar helper reads the dir directly in Swift. */
 export declare function readPendingSentinels(): PendingDevice[];

package/dist/lib/devices/pending.js

@@ -1,54 +1,24 @@
-/**
- * "Pending device" sentinels.
- *
- * When the daemon's tailscale probe finds a node that is neither registered nor
- * ignored, it drops a sentinel file under ~/.agents/.cache/state/devices-pending/
- * — the same filesystem-signal pattern the attention hook uses for the menu bar.
- * The Swift helper polls that dir every 10s and renders a "NEW DEVICES" section
- * with Register / Ignore. The file NAME is the device name; the file CONTENT is
- * the platform (one line), so the tray can show "zion (macos)" without opening
- * the registry.
- *
- * The daemon owns writes (reconcile to match the current pending set); the CLI
- * `agents devices register|ignore` clears a single sentinel the moment the user
- * acts, so the badge updates immediately instead of waiting for the next probe.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import { getDevicesPendingDir } from '../state.js';
 import { loadDevices, loadIgnored } from './registry.js';
-/** Device-name sentinels must be safe filenames (no path traversal). The device
- * name charset is already the ssh-alias set, but guard defensively. */
 function isSafeName(name) {
     return /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(name);
 }
-/**
- * Best-effort load of names that must never appear as "NEW DEVICES": the
- * ignore-list and the registered roster. A corrupted registry/ignore file
- * (both throw by design) must not crash the daemon loop — treat it as empty
- * and let the next probe recover once the file is fixed.
- */
 async function loadDismissedNames() {
     const out = new Set();
     try {
         for (const name of await loadIgnored())
             out.add(name);
     }
-    catch { /* treat as nothing ignored */ }
+    catch { }
     try {
         for (const name of Object.keys(await loadDevices()))
             out.add(name);
     }
-    catch { /* treat as nothing registered */ }
+    catch { }
     return out;
 }
-/**
- * Drop pending sentinels for devices that are already registered or ignored.
- * Safe without a live tailscale probe — only removes names we know are no
- * longer "new". Used when soft-fail discovery cannot recompute the full
- * pending set, so a test leak or race cannot leave registered fleet boxes in
- * the menu bar's NEW DEVICES section forever.
- */
 export async function pruneDismissedPendingSentinels() {
     const dir = getDevicesPendingDir();
     const dismissed = await loadDismissedNames();
@@ -67,38 +37,15 @@ export async function pruneDismissedPendingSentinels() {
         try {
             fs.unlinkSync(path.join(dir, name));
         }
-        catch { /* already gone */ }
+        catch { }
     }
 }
-/**
- * Make the sentinel dir exactly match `pending`: create a file per pending
- * device (content = platform), and delete any leftover sentinel whose device is
- * no longer pending (it got registered, ignored, or left the tailnet). Best-
- * effort — a filesystem error here must never crash the daemon, so callers pass
- * this through their existing try/catch.
- *
- * The sentinel writer is the single authoritative choke point every discovery
- * path flows through (the daemon device-probe timer and `agents sync`), so it
- * re-subtracts the persisted ignore-list AND the registered roster rather than
- * trusting the caller's `pending` set. That closes two races:
- *   - probe/ignore (RUSH-2495): a probe that computed `pending` BEFORE the user
- *     pressed "Ignore" would otherwise re-create the just-dismissed device's
- *     sentinel and the menu bar would re-surface it.
- *   - registry-empty pollution: a process that had AGENTS_DEVICES_DIR redirected
- *     (tests / hermetic runs) but still wrote the live devices-pending dir
- *     treated every tailnet node as new — including already-registered fleet
- *     boxes. Re-subtracting the live registry means those phantoms are never
- *     written and are removed if they already exist.
- */
 export async function reconcilePendingSentinels(pending) {
     const dir = getDevicesPendingDir();
     const dismissed = await loadDismissedNames();
     const want = new Map(pending
         .filter((p) => isSafeName(p.name) && !dismissed.has(p.name))
         .map((p) => [p.name, p.platform]));
-    // Whole body is best-effort: a filesystem error here must never propagate into
-    // the daemon loop or `agents sync`. The top-level mkdir/readdir are guarded
-    // too, so no caller needs its own try/catch.
     let existing;
     try {
         fs.mkdirSync(dir, { recursive: true });
@@ -107,20 +54,17 @@ export async function reconcilePendingSentinels(pending) {
     catch {
         return;
     }
-    // Remove sentinels that are no longer pending.
     for (const name of existing) {
         if (!want.has(name)) {
             try {
                 fs.unlinkSync(path.join(dir, name));
             }
-            catch { /* already gone */ }
+            catch { }
         }
     }
-    // Write/refresh the sentinels that should exist.
     for (const [name, platform] of want) {
         const p = path.join(dir, name);
         const body = `${platform}\n`;
-        // Only write when missing or changed, to avoid needless mtime churn.
         let current = null;
         try {
             current = fs.readFileSync(p, 'utf-8');
@@ -132,22 +76,18 @@ export async function reconcilePendingSentinels(pending) {
             try {
                 fs.writeFileSync(p, body);
             }
-            catch { /* best-effort */ }
+            catch { }
         }
     }
 }
-/** Remove one device's pending sentinel (after the user registers or ignores it).
- * No-op if it doesn't exist. */
 export function clearPendingSentinel(name) {
     if (!isSafeName(name))
         return;
     try {
         fs.unlinkSync(path.join(getDevicesPendingDir(), name));
     }
-    catch { /* already gone */ }
+    catch { }
 }
-/** Read the current pending sentinels (name + platform). Used by tests and any
- * TS-side consumer; the menu-bar helper reads the dir directly in Swift. */
 export function readPendingSentinels() {
     const dir = getDevicesPendingDir();
     let names;
@@ -162,7 +102,7 @@ export function readPendingSentinels() {
         try {
             platform = fs.readFileSync(path.join(dir, name), 'utf-8').trim() || 'unknown';
         }
-        catch { /* keep default */ }
+        catch { }
         return { name, platform };
     });
 }

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

@@ -31,50 +31,14 @@
  */
 import { type AutoLaunchPreference, type AutoPoolMode, type ConfiguredDeviceRole } from '../device-config.js';
 interface AutoPoolOptions {
-    /** Pool mode; defaults to the configured `auto.pool`. */
     mode?: AutoPoolMode;
-    /** Configured roles by device name; defaults to the fleet-shared block. */
     roles?: Record<string, ConfiguredDeviceRole>;
-    /**
-     * Device names to resolve roles for when `roles` is not given directly —
-     * so a fleet-wide role default reaches a device with no per-device doc of
-     * its own. Ignored once `roles` is supplied. See
-     * {@link listConfiguredDeviceRoles}.
-     */
     roster?: string[];
-    /**
-     * Auto-launch flags by device name; defaults to the fleet-shared block for
-     * the roster (or the pool). A device whose `enabled` is `false` is dropped
-     * from the pool. Inject `{}` in a pure unit test to keep the rule off disk,
-     * exactly as `roles: {}` does for the role rule. See
-     * {@link loadAutoLaunchPreferences}.
-     */
     autoLaunch?: Record<string, AutoLaunchPreference>;
 }
-/**
- * Narrow a candidate host list to the devices automatic placement may pick.
- *
- * Returns the input order, minus the excluded devices. An empty result is a
- * real answer — "you marked workers and none of them is a candidate right now"
- * — and callers surface it as their own no-healthy-device error rather than
- * quietly widening back to the full fleet.
- */
 export declare function filterAutoPool(pool: string[], opts?: AutoPoolOptions): string[];
-/**
- * Normalized hosts the operator boosted with `auto-launch.preferred` = true —
- * the set `pickBestDevice` ranks ahead of its peers. Unlike the disable drop,
- * a preference never removes a device: an eligible non-preferred box is still
- * picked when no preferred one is available.
- */
 export declare function autoLaunchPreferredSet(pool: string[], opts?: AutoPoolOptions): Set<string>;
-/** True when this host is one automatic placement may pick. */
 export declare function isAutoPoolMember(host: string, opts?: AutoPoolOptions): boolean;
-/** Device names explicitly marked `worker`, in registry order. */
 export declare function listWorkerDevices(opts?: Pick<AutoPoolOptions, 'roles'>): string[];
-/**
- * One line naming why the pool is what it is, for the `--device auto` banner and
- * the no-healthy-device error. Empty string when no role narrows anything, so
- * callers can append it unconditionally.
- */
 export declare function describeAutoPool(opts?: AutoPoolOptions): string;
 export {};

package/dist/lib/devices/pool.js

@@ -31,23 +31,7 @@
  */
 import { autoPoolMode, listConfiguredDeviceRoles, loadAutoLaunchPreferences, } from '../device-config.js';
 import { normalizeHost } from '../machine-id.js';
-/**
- * Roles that automatic placement never picks, whatever the pool mode.
- *
- * `personal` (a box you sit at) and `desktop` (a headed always-on box — the
- * release/credential home, e.g. a Mac mini) are both off-limits to `--device
- * auto`: neither is headless fan-out capacity, and landing agent work on them
- * is the outcome the mark exists to prevent. Only `worker` is auto-eligible.
- */
 const NEVER_AUTO = new Set(['personal', 'desktop']);
-/**
- * Narrow a candidate host list to the devices automatic placement may pick.
- *
- * Returns the input order, minus the excluded devices. An empty result is a
- * real answer — "you marked workers and none of them is a candidate right now"
- * — and callers surface it as their own no-healthy-device error rather than
- * quietly widening back to the full fleet.
- */
 export function filterAutoPool(pool, opts = {}) {
     const roles = opts.roles ?? listConfiguredDeviceRoles(opts.roster ?? pool);
     const byHost = new Map(Object.entries(roles).map(([name, role]) => [normalizeHost(name), role]));
@@ -67,41 +51,27 @@ export function filterAutoPool(pool, opts = {}) {
         return eligible;
     return eligible.filter((host) => roleOf(host) === 'worker');
 }
-/** Normalized hosts the operator turned off with `auto-launch.enabled` = false. */
 function disabledAutoLaunchSet(pool, opts) {
     const prefs = opts.autoLaunch ?? loadAutoLaunchPreferences(opts.roster ?? pool);
     return new Set(Object.entries(prefs)
         .filter(([, pref]) => pref.enabled === false)
         .map(([name]) => normalizeHost(name)));
 }
-/**
- * Normalized hosts the operator boosted with `auto-launch.preferred` = true —
- * the set `pickBestDevice` ranks ahead of its peers. Unlike the disable drop,
- * a preference never removes a device: an eligible non-preferred box is still
- * picked when no preferred one is available.
- */
 export function autoLaunchPreferredSet(pool, opts = {}) {
     const prefs = opts.autoLaunch ?? loadAutoLaunchPreferences(opts.roster ?? pool);
     return new Set(Object.entries(prefs)
         .filter(([, pref]) => pref.preferred === true)
         .map(([name]) => normalizeHost(name)));
 }
-/** True when this host is one automatic placement may pick. */
 export function isAutoPoolMember(host, opts = {}) {
     return filterAutoPool([host], opts).length > 0;
 }
-/** Device names explicitly marked `worker`, in registry order. */
 export function listWorkerDevices(opts = {}) {
     const roles = opts.roles ?? listConfiguredDeviceRoles();
     return Object.entries(roles)
         .filter(([, role]) => role === 'worker')
         .map(([name]) => name);
 }
-/**
- * One line naming why the pool is what it is, for the `--device auto` banner and
- * the no-healthy-device error. Empty string when no role narrows anything, so
- * callers can append it unconditionally.
- */
 export function describeAutoPool(opts = {}) {
     const roles = opts.roles ?? listConfiguredDeviceRoles(opts.roster);
     const mode = opts.mode ?? autoPoolMode();

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

@@ -1,31 +1,6 @@
-/**
- * One reachability resolver for the fleet render (RUSH-1965).
- *
- * "Is this device online?" had three disagreeing answers: the live SSH probe
- * (`DeviceStats.reachable`, display-only), the persisted registry verdict, and
- * the cached `tailscale.online` snapshot that the online/offline word actually
- * read. A box reachable every day but whose tailscale snapshot was stale (or a
- * `via:"manual"` device that never got a tailscale field at all) rendered
- * "offline forever". This module is the single ordering the render + the
- * write-back both go through, so the word and the persisted truth agree.
- */
 import type { DeviceProfile, DeviceReachability, DeviceRegistry } from './registry.js';
 import type { DeviceStats } from './health.js';
 export type OnlineState = 'online' | 'offline' | 'unknown';
-/**
- * Resolve a device's online/offline state, preferring the freshest signal.
- *
- * Precedence: a live stat from THIS run (the probe that just ran) > the
- * persisted reachability verdict written back by a prior probe > the cached
- * `tailscale.online` snapshot. 'unknown' only when nothing at all is known.
- */
 export declare function deviceOnlineState(d: DeviceProfile, stats?: DeviceStats): OnlineState;
-/** Build the reachability verdict to persist from a fresh probe stat. Pure. */
 export declare function reachabilityFromStats(d: DeviceProfile, stats: DeviceStats): DeviceReachability;
-/**
- * Collect the reachability verdicts to write back for a fleet's freshly-read
- * stats map. Only devices present in the registry are included (a stat for a
- * name we don't track is dropped rather than resurrected). Pure — the caller
- * hands the result to {@link writeReachability}.
- */
 export declare function collectReachabilityWriteBacks(reg: DeviceRegistry, statsMap: Map<string, DeviceStats>): Record<string, DeviceReachability>;

package/dist/lib/devices/reachability.js

@@ -1,10 +1,3 @@
-/**
- * Resolve a device's online/offline state, preferring the freshest signal.
- *
- * Precedence: a live stat from THIS run (the probe that just ran) > the
- * persisted reachability verdict written back by a prior probe > the cached
- * `tailscale.online` snapshot. 'unknown' only when nothing at all is known.
- */
 export function deviceOnlineState(d, stats) {
     if (stats)
         return stats.reachable ? 'online' : 'offline';
@@ -14,7 +7,6 @@ export function deviceOnlineState(d, stats) {
         return d.tailscale.online ? 'online' : 'offline';
     return 'unknown';
 }
-/** Build the reachability verdict to persist from a fresh probe stat. Pure. */
 export function reachabilityFromStats(d, stats) {
     return {
         reachable: stats.reachable,
@@ -22,12 +14,6 @@ export function reachabilityFromStats(d, stats) {
         checkedAt: new Date(stats.fetchedAt).toISOString(),
     };
 }
-/**
- * Collect the reachability verdicts to write back for a fleet's freshly-read
- * stats map. Only devices present in the registry are included (a stat for a
- * name we don't track is dropped rather than resurrected). Pure — the caller
- * hands the result to {@link writeReachability}.
- */
 export function collectReachabilityWriteBacks(reg, statsMap) {
     const out = {};
     for (const [name, stats] of statsMap) {