@phnx-labs/agents-cli 1.22.120 → 1.22.121

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

@@ -1,18 +1,8 @@
-/**
- * Fleet-wide device operations — pick online targets and run a command on each.
- *
- * Used by `agents fleet update` / `agents fleet run` (aliases of the same
- * subcommands under `agents devices`). Offline devices are skipped with a
- * reason so a single dead node never blocks the rest of the rollout. Per-device
- * throws (misconfigured auth, etc.) become `failed` rows — they never abort
- * the remaining devices.
- */
 import type { DeviceProfile, DeviceRegistry } from './registry.js';
 import type { DeviceStats } from './health.js';
 export type FleetSkipReason = 'offline' | 'no-address';
 export interface FleetTarget {
     device: DeviceProfile;
-    /** When set, this device is not reached (skip with reason). */
     skip?: FleetSkipReason;
 }
 export interface FleetRunResult {
@@ -20,7 +10,6 @@ export interface FleetRunResult {
     status: 'ok' | 'failed' | 'skipped';
     code: number | null;
     reason?: FleetSkipReason | string;
-    /** Truncated combined stderr/stdout for failures. */
     detail?: string;
 }
 export interface FanOutDeviceTarget {
@@ -34,50 +23,10 @@ export interface FanOutDeviceResult<T> {
     error?: string;
     reason?: FleetSkipReason | string;
 }
-/**
- * Classify each registered device for a fleet operation.
- *
- * - Tailscale-offline → skip `offline`
- * - No address → skip `no-address`
- * - Everything else is a target (including this machine, reached over ssh when
- *   it has a registry address — same path as any other box).
- */
 export declare function planFleetTargets(reg: DeviceRegistry): FleetTarget[];
-/**
- * Remote fan-out targets for the fleet health/drift gates (`fleet status`,
- * `doctor --check --devices`): every planned device except this machine.
- * Offline / no-address devices are kept — those are genuine faults a gate should
- * surface — so their `skip` reason still flows through as an `unreachable` row.
- */
 export declare function remoteFleetTargets(planned: FleetTarget[], self: string): FleetTarget[];
-/**
- * Decide whether a fleet-health target should skip the expensive version+doctor
- * dials (`agents fleet status`). The cheap stats probe (~2.5s, same registry
- * address) has already tried this box one step earlier. If it came back
- * unreachable, dialing `agents --version` (15s) + `agents doctor --json` (30s)
- * would almost certainly fail the same way — just 45s slower — so one
- * genuinely-offline box would stall the whole matrix (the ~60s hang, RUSH-1964).
- *
- * We trust the stats verdict on the DEFAULT path, not only under
- * `--refresh`/`--live`: `probeDeviceStats` and the version/doctor dials share
- * one ssh path (`fleetDialTarget`), so reachability is not per-probe. The
- * verdict is either freshly probed this run or daemon-warmed (~3min) with the
- * live write-back from RUSH-1965, so a box that came online in the last few
- * minutes is the only false-negative window — it renders `unreachable` until the
- * next stats warm, which beats letting it hang the status glance for 45s.
- *
- * An existing skip (offline/no-address from {@link planFleetTargets})
- * always wins — those are classified before any probe.
- */
 export declare function fleetHealthSkip(currentSkip: FleetSkipReason | string | undefined, stats: DeviceStats | undefined): FleetSkipReason | string | undefined;
-/** Human label for a skip reason. */
 export declare function skipLabel(reason: FleetSkipReason): string;
-/**
- * Run `cmd` on one device via the same ssh path as `agents ssh <name> …`.
- * Captures stdout/stderr (not inherited) so the fleet table can summarize.
- * Throws from buildSshInvocation are returned as a non-zero result so a single
- * misconfigured device cannot abort the fleet loop.
- */
 export declare function runOnDevice(device: DeviceProfile, cmd: string[], opts?: {
     timeoutMs?: number;
 }): {
@@ -85,18 +34,6 @@ export declare function runOnDevice(device: DeviceProfile, cmd: string[], opts?:
     stdout: string;
     stderr: string;
 };
-/**
- * Run `cmd` on THIS machine directly — no ssh. Used by {@link runFleet} for the
- * self target: a box frequently can't ssh to itself (no self-authorized key, as
- * `agents fleet update` hit trying to reach zion from zion) and doesn't need to —
- * `agents upgrade` etc. runs identically as a local process. Mirrors
- * {@link runOnDevice}'s return shape and never throws. The argv is space-joined
- * and evaluated by a shell — matching the POSIX-shell ssh path (so PATH-resolved
- * `agents`, quoting, and `;`/`&&` behave the same). It does NOT replicate the
- * powershell-device encoding runOnDevice uses (`connect.ts` base64 path): a
- * Windows self runs under the default OS shell (cmd.exe), which still resolves
- * `agents` on PATH for the only self commands that matter (`agents upgrade …`).
- */
 export declare function runLocalCommand(cmd: string[], opts?: {
     timeoutMs?: number;
 }): {
@@ -104,47 +41,15 @@ export declare function runLocalCommand(cmd: string[], opts?: {
     stdout: string;
     stderr: string;
 };
-/**
- * Build `agents upgrade --yes` argv, optionally pinned to a version/dist-tag.
- * Rejects anything that is not a plain npm version/tag token so a version pin
- * cannot inject shell metacharacters into the remote command line.
- */
 export declare function upgradeCommand(version?: string): string[];
 interface RunFleetOptions {
-    /**
-     * Name of THIS machine. Its target runs the command **locally** (no ssh) — a
-     * box can't reliably ssh to itself and doesn't need to. Omit to ssh every
-     * target (the old behaviour). Callers pass `machineId()`.
-     */
     self?: string;
-    /** Injectable ssh runner (tests). */
     runner?: typeof runOnDevice;
-    /** Injectable local runner (tests). */
     localRunner?: typeof runLocalCommand;
 }
-/**
- * Execute a command across planned targets. Pure orchestration over
- * {@link runOnDevice} / {@link runLocalCommand}; testable by injecting either.
- * The `self` target runs locally so `agents fleet update` upgrades this machine
- * too instead of failing to ssh to itself. Per-device throws from a runner are
- * recorded as `failed` so one bad device never aborts the rest.
- */
 export declare function runFleet(targets: FleetTarget[], cmd: string[], opts?: RunFleetOptions): FleetRunResult[];
 interface FanOutDeviceOptions {
-    /**
-     * Per-device deadline in milliseconds. When set, any probe that does not
-     * settle within this window is abandoned via `Promise.race` against a
-     * rejection timer and recorded as a `failed` result with the message
-     * `'timed out'`. There is no AbortController — the underlying probe
-     * continues running in the background; cancellation of the in-flight work
-     * is the caller's responsibility. In practice `probeRemoteAuth` relies on
-     * `sshExecAsync`'s own 15 s timer to kill the ssh child independently.
-     * The per-device ssh timeout passed directly to {@link sshExecAsync} is
-     * the first line of defence; this acts as a hard backstop so one slow
-     * device can never stall the entire fan-out past its budget.
-     */
     perDeviceTimeoutMs?: number;
 }
-/** Run one async probe per device in parallel, preserving input order. */
 export declare function fanOutDevices<T, Target extends FanOutDeviceTarget = FanOutDeviceTarget>(targets: Target[], probe: (target: Target) => Promise<T>, opts?: FanOutDeviceOptions): Promise<FanOutDeviceResult<T>[]>;
 export {};

package/dist/lib/devices/fleet.js

@@ -1,25 +1,7 @@
-/**
- * Fleet-wide device operations — pick online targets and run a command on each.
- *
- * Used by `agents fleet update` / `agents fleet run` (aliases of the same
- * subcommands under `agents devices`). Offline devices are skipped with a
- * reason so a single dead node never blocks the rest of the rollout. Per-device
- * throws (misconfigured auth, etc.) become `failed` rows — they never abort
- * the remaining devices.
- */
 import { spawnSync } from 'child_process';
 import { isSelfHost } from './self-host.js';
 import { buildSshInvocation, sshTargetFor, writeAskpassShim } from './connect.js';
-/** npm dist-tags / semver pins only — rejects shell metacharacters. */
 const FLEET_VERSION_RE = /^[A-Za-z0-9._-]+$/;
-/**
- * Classify each registered device for a fleet operation.
- *
- * - Tailscale-offline → skip `offline`
- * - No address → skip `no-address`
- * - Everything else is a target (including this machine, reached over ssh when
- *   it has a registry address — same path as any other box).
- */
 export function planFleetTargets(reg) {
     const names = Object.keys(reg).sort();
     return names.map((name) => {
@@ -36,38 +18,9 @@ export function planFleetTargets(reg) {
         return { device };
     });
 }
-/**
- * Remote fan-out targets for the fleet health/drift gates (`fleet status`,
- * `doctor --check --devices`): every planned device except this machine.
- * Offline / no-address devices are kept — those are genuine faults a gate should
- * surface — so their `skip` reason still flows through as an `unreachable` row.
- */
 export function remoteFleetTargets(planned, self) {
-    // Exclude self by name AND by full identity (tailscale dnsName, loopback): a
-    // device referenced by its dnsName slipped past the bare name check and got a
-    // remote version+doctor dial back to THIS box, which orphaned on timeout and
-    // piled up (RUSH-2114). `isSelfHost` matches every alias the box answers to.
     return planned.filter((t) => t.device.name !== self && !isSelfHost(t.device.name));
 }
-/**
- * Decide whether a fleet-health target should skip the expensive version+doctor
- * dials (`agents fleet status`). The cheap stats probe (~2.5s, same registry
- * address) has already tried this box one step earlier. If it came back
- * unreachable, dialing `agents --version` (15s) + `agents doctor --json` (30s)
- * would almost certainly fail the same way — just 45s slower — so one
- * genuinely-offline box would stall the whole matrix (the ~60s hang, RUSH-1964).
- *
- * We trust the stats verdict on the DEFAULT path, not only under
- * `--refresh`/`--live`: `probeDeviceStats` and the version/doctor dials share
- * one ssh path (`fleetDialTarget`), so reachability is not per-probe. The
- * verdict is either freshly probed this run or daemon-warmed (~3min) with the
- * live write-back from RUSH-1965, so a box that came online in the last few
- * minutes is the only false-negative window — it renders `unreachable` until the
- * next stats warm, which beats letting it hang the status glance for 45s.
- *
- * An existing skip (offline/no-address from {@link planFleetTargets})
- * always wins — those are classified before any probe.
- */
 export function fleetHealthSkip(currentSkip, stats) {
     if (currentSkip)
         return currentSkip;
@@ -75,7 +28,6 @@ export function fleetHealthSkip(currentSkip, stats) {
         return 'unreachable';
     return undefined;
 }
-/** Human label for a skip reason. */
 export function skipLabel(reason) {
     switch (reason) {
         case 'offline':
@@ -84,12 +36,6 @@ export function skipLabel(reason) {
             return 'no address';
     }
 }
-/**
- * Run `cmd` on one device via the same ssh path as `agents ssh <name> …`.
- * Captures stdout/stderr (not inherited) so the fleet table can summarize.
- * Throws from buildSshInvocation are returned as a non-zero result so a single
- * misconfigured device cannot abort the fleet loop.
- */
 export function runOnDevice(device, cmd, opts = {}) {
     try {
         const shim = writeAskpassShim();
@@ -113,18 +59,6 @@ export function runOnDevice(device, cmd, opts = {}) {
         };
     }
 }
-/**
- * Run `cmd` on THIS machine directly — no ssh. Used by {@link runFleet} for the
- * self target: a box frequently can't ssh to itself (no self-authorized key, as
- * `agents fleet update` hit trying to reach zion from zion) and doesn't need to —
- * `agents upgrade` etc. runs identically as a local process. Mirrors
- * {@link runOnDevice}'s return shape and never throws. The argv is space-joined
- * and evaluated by a shell — matching the POSIX-shell ssh path (so PATH-resolved
- * `agents`, quoting, and `;`/`&&` behave the same). It does NOT replicate the
- * powershell-device encoding runOnDevice uses (`connect.ts` base64 path): a
- * Windows self runs under the default OS shell (cmd.exe), which still resolves
- * `agents` on PATH for the only self commands that matter (`agents upgrade …`).
- */
 export function runLocalCommand(cmd, opts = {}) {
     try {
         const res = spawnSync(cmd.join(' '), {
@@ -146,11 +80,6 @@ export function runLocalCommand(cmd, opts = {}) {
         };
     }
 }
-/**
- * Build `agents upgrade --yes` argv, optionally pinned to a version/dist-tag.
- * Rejects anything that is not a plain npm version/tag token so a version pin
- * cannot inject shell metacharacters into the remote command line.
- */
 export function upgradeCommand(version) {
     if (version !== undefined && version !== '') {
         if (!FLEET_VERSION_RE.test(version)) {
@@ -160,13 +89,6 @@ export function upgradeCommand(version) {
     }
     return ['agents', 'upgrade', '--yes'];
 }
-/**
- * Execute a command across planned targets. Pure orchestration over
- * {@link runOnDevice} / {@link runLocalCommand}; testable by injecting either.
- * The `self` target runs locally so `agents fleet update` upgrades this machine
- * too instead of failing to ssh to itself. Per-device throws from a runner are
- * recorded as `failed` so one bad device never aborts the rest.
- */
 export function runFleet(targets, cmd, opts = {}) {
     const runner = opts.runner ?? runOnDevice;
     const localRunner = opts.localRunner ?? runLocalCommand;
@@ -204,7 +126,6 @@ export function runFleet(targets, cmd, opts = {}) {
     }
     return results;
 }
-/** Run one async probe per device in parallel, preserving input order. */
 export async function fanOutDevices(targets, probe, opts = {}) {
     return Promise.all(targets.map(async (target) => {
         if (target.skip) {

package/dist/lib/devices/harness-inventory.d.ts

@@ -2,133 +2,63 @@ import { type AccountInfo } from '../agents.js';
 import type { AgentId } from '../types.js';
 import { type UsageSnapshot } from '../accounting/usage.js';
 import { type AccountVerdict } from '../signin-badge.js';
-/** An account's usage headroom rolled into one glanceable summary. */
 export interface QuotaSummary {
-    /**
-     * `available` / `rate_limited` from the live usage windows, or `null` when
-     * there is no snapshot at all (no data yet, or the agent has no usage source).
-     */
     status: 'available' | 'rate_limited' | 'out_of_credits' | null;
-    /** Canonical launch verdict. Kept separate from utilization for JSON clients. */
     verdict: 'available' | 'rate_limited' | 'out_of_credits' | 'unavailable';
-    /** Max utilization across blocking windows (0-100, rounded), or null when unknown. */
     usedPercent: number | null;
-    /** True when the snapshot is a cached `last_seen`, not a fresh `live` read. */
     stale: boolean;
-    /** ISO-8601 timestamp for the underlying usage observation. */
     capturedAt: string | null;
-    /** Earliest reset across blocking windows, ISO-8601. */
     resetsAt: string | null;
-    /** Why quota could not be evaluated; null when a verdict is available. */
     unavailableReason: string | null;
 }
-/** One installed (agent, version) on a host, fully resolved. */
 export interface HarnessRow {
     agent: AgentId;
     version: string;
-    /** Account display label (email / id), or null when signed out or unidentifiable. */
     account: string | null;
     signedIn: boolean;
     quota: QuotaSummary;
-    /** signed in AND not rate-limited — usable for a run right now. */
     ready: boolean;
-    /** When `!ready`, a short reason ("signed out" / "rate-limited"). */
     reason?: string;
     verdict: AccountVerdict;
     fix: string | null;
-    /** The live usage snapshot backing `quota`, or null when none was collected. */
     snapshot: UsageSnapshot | null;
-    /** Raw error string from the usage fetch, if any (headless scope, expired, etc.). */
     usageError: string | null;
 }
-/** One host's rows, or the reason it produced none. */
 export interface HostHarnessResult {
     host: string;
     rows: HarnessRow[];
-    /** Set when the host failed to probe (offline / error). */
     error?: string;
-    /** Set when the host was skipped (control / offline). */
     skipped?: string;
 }
-/** An account collapsed across the installs on one host that share it. */
 interface AccountGroup {
-    /** Account display label, or null for the signed-out bucket. */
     account: string | null;
-    /** Distinct agent ids using this account, sorted. */
     agents: AgentId[];
-    /** How many (agent, version) installs share this account. */
     installs: number;
-    /** True when at least one install under this account is signed in. */
     signedIn: boolean;
-    /** Representative quota — an account maps to one provider identity, so its usage is shared. */
     quota: QuotaSummary;
     ready: boolean;
     reason?: string;
 }
-/**
- * Roll one usage snapshot into a {@link QuotaSummary}. Mirrors the blocking-window
- * selection of {@link deriveUsageStatusFromSnapshot} (the model-specific
- * `sonnet_week` sub-limit is excluded so hitting it doesn't read as a throttled
- * account) and takes the highest utilization across those windows. Pure.
- */
 export declare function summarizeQuota(snapshot: UsageSnapshot | null | undefined, unavailableReason?: string | null, accountStatus?: AccountInfo['usageStatus']): QuotaSummary;
-/**
- * Scope/permission failures on a worker mean the usage endpoint cannot be read.
- * They are not evidence of exhausted credits, even when stale account metadata
- * previously carried that coarse status.
- */
 export declare function summarizeObservedQuota(snapshot: UsageSnapshot | null | undefined, error: string | null | undefined, accountStatus?: AccountInfo['usageStatus']): {
     quota: QuotaSummary;
     unverified: boolean;
 };
-/**
- * A scope/permission failure on the usage endpoint is not a credit claim.
- * Strip utilization and, only when auth still looks healthy, surface
- * `unverified` instead of `live`/`rate_limited`. A real auth failure
- * (expired/revoked/missing) stays the auth failure.
- */
 export declare function applyUsageHonesty(verdict: AccountVerdict, usage: QuotaSummary | null): {
     verdict: AccountVerdict;
     usage: QuotaSummary | null;
 };
-/**
- * "Ready" = signed in AND not rate-limited. A missing quota snapshot does NOT
- * block readiness: the account is signed in and usable, we just have no live
- * utilization to show. Pure.
- */
 export declare function computeReady(signedIn: boolean, quota: QuotaSummary): {
     ready: boolean;
     reason?: string;
 };
-/**
- * Enumerate every installed (agent, version) on THIS host, resolve account +
- * sign-in + quota + ready, and return the rows. Signed-out installs are kept
- * (they are the actionable ones), unlike the auth-health probe which drops
- * `unconfigured`. Quota is cache-only unless `refresh` is set.
- */
 export declare function collectLocalHarnessInventory(opts?: {
     agents?: readonly AgentId[];
     refresh?: boolean;
 }): Promise<HarnessRow[]>;
-/**
- * Collapse a host's rows into one {@link AccountGroup} per distinct account (the
- * signed-out installs fall into the `null` bucket). Because an account label maps
- * to a single provider identity, every install sharing it shares one quota, so
- * the group's quota is taken from the first row carrying real data (preferring a
- * `rate_limited` row so a throttle is never hidden). Pure.
- */
 export declare function groupByAccount(rows: HarnessRow[]): AccountGroup[];
-/** Short human quota cell: "12%", "limited", or "—" when no data. */
 export declare function formatQuota(quota: QuotaSummary): string;
-/**
- * Render the device × harness table: one block per device, one row per installed
- * (agent, version) with account / signed-in / quota / ready. Pure.
- */
 export declare function renderHarnessMatrix(results: HostHarnessResult[]): string[];
-/**
- * Render the device × account table: one block per device, one row per distinct
- * account (installs sharing it collapsed), showing which harnesses use it. Pure.
- */
 export declare function renderAccountsMatrix(results: HostHarnessResult[]): string[];
 interface AccountFleetMatrixRow {
     harness: AgentId;
@@ -139,11 +69,6 @@ interface AccountFleetMatrixRow {
         verdict: AccountVerdict;
     }>;
 }
-/**
- * Account × device matrix used by `agents accounts list --fleet`.
- * Rows are logical accounts, not installations. Columns come from the
- * daemon-state observations already joined onto each account row.
- */
 export declare function renderAccountFleetMatrix(rows: AccountFleetMatrixRow[], opts?: {
     uncoveredDevices?: string[];
 }): string[];

package/dist/lib/devices/harness-inventory.js

@@ -1,18 +1,3 @@
-/**
- * Per-device harness inventory: for every installed (agent, version) on a host,
- * resolve its account identity, sign-in state, usage quota, and a single "ready"
- * verdict — the data behind `agents devices harnesses` and `agents devices
- * accounts`.
- *
- * The collector ({@link collectLocalHarnessInventory}) runs on ONE host (the
- * `--local` worker); the command fans it out over SSH exactly like
- * `agents devices ping`. Everything else here is pure so the table/grouping/ready
- * logic is unit-tested without a shell or a network.
- *
- * Quota is read cache-only by default (the daemon warms the usage cache every few
- * minutes), so a glance never blocks on a per-account network fetch; `--refresh`
- * opts into a live read.
- */
 import chalk from 'chalk';
 import { ALL_AGENT_IDS, accountDisplayLabel, getAccountInfo, } from '../agents.js';
 import { deriveUsageStatusFromSnapshot, liveUsageWindows, classifyUsageErrorKind, getUsageInfoByIdentity, getUsageLookupKey, usageErrorForDisplay, } from '../accounting/usage.js';
@@ -23,20 +8,8 @@ import { authCacheKey, readAuthHealthCache } from '../auth-health.js';
 import { machineId } from '../machine-id.js';
 import { fixFor } from '../signin-badge.js';
 import { harnessWorkerIsPerDevice } from '../harness-auth-capabilities.js';
-/**
- * Roll one usage snapshot into a {@link QuotaSummary}. Mirrors the blocking-window
- * selection of {@link deriveUsageStatusFromSnapshot} (the model-specific
- * `sonnet_week` sub-limit is excluded so hitting it doesn't read as a throttled
- * account) and takes the highest utilization across those windows. Pure.
- */
 export function summarizeQuota(snapshot, unavailableReason = null, accountStatus = null) {
     if (!snapshot || snapshot.windows.length === 0) {
-        // An active refusal marker (persisted out_of_credits, or an unexpired
-        // session_limit) blocks even when there are no live utilization windows —
-        // which is the normal state hours/days after a run, once cached windows
-        // expire. Check it BEFORE trusting the coarse account status, which is
-        // hardcoded 'available' for a signed-in Claude; otherwise a tokens-exhausted
-        // account reads ready:true here (RUSH-3018 finding, `agents devices harnesses`).
         const marker = snapshot?.unavailable;
         let status = accountStatus;
         let reason = unavailableReason;
@@ -59,24 +32,14 @@ export function summarizeQuota(snapshot, unavailableReason = null, accountStatus
             unavailableReason: status ? null : (reason ?? 'usage unavailable'),
         };
     }
-    // Percentage and status MUST read from the SAME live windows, or a window past
-    // its reset (usedPercent from the PREVIOUS period) makes the status `available`
-    // while the displayed percentage still shows a stale ~100% (#3705). Select the
-    // live set first, then narrow to blocking exactly as
-    // `deriveUsageStatusFromSnapshot` does.
     const live = liveUsageWindows(snapshot);
     const blocking = live.filter((w) => w.key !== 'sonnet_week');
     const windows = blocking.length > 0 ? blocking : live;
     const derived = deriveUsageStatusFromSnapshot(snapshot);
     const status = accountStatus === 'out_of_credits' ? accountStatus : derived;
-    // Every window rolled over: no live utilization to show (status is `available`).
     let usedPercent = windows.length > 0
         ? Math.round(Math.max(...windows.map((w) => w.usedPercent)))
         : 0;
-    // Never show 100% for an account that isn't actually capped: a genuinely-100
-    // blocking window makes the status `rate_limited` (rendered "limited"), so a
-    // rounded 100 on an `available` account (e.g. 99.6% → 100) would read as maxed
-    // next to a "ready" verdict. Cap the display at 99 to keep the two consistent.
     if (status !== 'rate_limited' && usedPercent >= 100)
         usedPercent = 99;
     return {
@@ -92,11 +55,6 @@ export function summarizeQuota(snapshot, unavailableReason = null, accountStatus
         unavailableReason: null,
     };
 }
-/**
- * Scope/permission failures on a worker mean the usage endpoint cannot be read.
- * They are not evidence of exhausted credits, even when stale account metadata
- * previously carried that coarse status.
- */
 export function summarizeObservedQuota(snapshot, error, accountStatus = null) {
     const displayError = usageErrorForDisplay(error);
     const unverified = classifyUsageErrorKind(error) === 'headless-scope'
@@ -108,12 +66,6 @@ export function summarizeObservedQuota(snapshot, error, accountStatus = null) {
         unverified,
     };
 }
-/**
- * A scope/permission failure on the usage endpoint is not a credit claim.
- * Strip utilization and, only when auth still looks healthy, surface
- * `unverified` instead of `live`/`rate_limited`. A real auth failure
- * (expired/revoked/missing) stays the auth failure.
- */
 export function applyUsageHonesty(verdict, usage) {
     if (!usage)
         return { verdict, usage };
@@ -137,11 +89,6 @@ export function applyUsageHonesty(verdict, usage) {
     }
     return { verdict, usage };
 }
-/**
- * "Ready" = signed in AND not rate-limited. A missing quota snapshot does NOT
- * block readiness: the account is signed in and usable, we just have no live
- * utilization to show. Pure.
- */
 export function computeReady(signedIn, quota) {
     if (!signedIn)
         return { ready: false, reason: 'signed out' };
@@ -151,12 +98,6 @@ export function computeReady(signedIn, quota) {
         return { ready: false, reason: 'out of credits' };
     return { ready: true };
 }
-/**
- * Enumerate every installed (agent, version) on THIS host, resolve account +
- * sign-in + quota + ready, and return the rows. Signed-out installs are kept
- * (they are the actionable ones), unlike the auth-health probe which drops
- * `unconfigured`. Quota is cache-only unless `refresh` is set.
- */
 export async function collectLocalHarnessInventory(opts) {
     const agentIds = opts?.agents ?? ALL_AGENT_IDS;
     const pending = [];
@@ -166,8 +107,6 @@ export async function collectLocalHarnessInventory(opts) {
             const home = getVersionHomePath(agent, version);
             const info = await getAccountInfo(agent, home).catch(() => null);
             pending.push({ agent, version, info });
-            // Only signed-in installs can have usage; a signed-out one has no identity
-            // to look up (and would just widen the fetch set for nothing).
             if (info?.signedIn) {
                 usageInputs.push({ agentId: agent, info, home, cliVersion: version });
             }
@@ -183,9 +122,6 @@ export async function collectLocalHarnessInventory(opts) {
         const key = getUsageLookupKey(info);
         const usage = key ? usageByKey.get(key) : undefined;
         const snapshot = usage?.snapshot ?? null;
-        // Normalize the internal 'stale' not-collected sentinel out before it reaches
-        // the JSON `quota.unavailableReason` — same leak PHNX-3348 fixed for
-        // `agents view --json`, here for `agents devices harnesses/accounts --json`.
         const observed = summarizeObservedQuota(snapshot, usage?.error, info?.usageStatus ?? null);
         const quota = observed.quota;
         const signedIn = !!info?.signedIn;
@@ -218,20 +154,10 @@ export async function collectLocalHarnessInventory(opts) {
         };
     });
 }
-/**
- * Collapse a host's rows into one {@link AccountGroup} per distinct account (the
- * signed-out installs fall into the `null` bucket). Because an account label maps
- * to a single provider identity, every install sharing it shares one quota, so
- * the group's quota is taken from the first row carrying real data (preferring a
- * `rate_limited` row so a throttle is never hidden). Pure.
- */
 export function groupByAccount(rows) {
     const order = [];
     const groups = new Map();
     for (const row of rows) {
-        // Signed-out rows share one bucket under a sentinel key. Use the NUL-prefixed
-        // literal (a TS `\0` escape, NOT a raw NUL byte in the source) so the key can
-        // never collide with a real account label named literally "signed-out".
         const key = row.account ?? '\0signed-out';
         if (!groups.has(key)) {
             groups.set(key, []);
@@ -244,8 +170,6 @@ export function groupByAccount(rows) {
         const account = members[0].account;
         const agents = [...new Set(members.map((m) => m.agent))].sort();
         const signedIn = members.some((m) => m.signedIn);
-        // Prefer a throttled member's quota (a hidden rate-limit is the dangerous
-        // miss), else the first member with any real usage data, else the first row.
         const withData = members.filter((m) => m.quota.status !== null);
         const rep = withData.find((m) => m.quota.status === 'out_of_credits') ??
             withData.find((m) => m.quota.status === 'rate_limited') ?? withData[0] ?? members[0];
@@ -262,7 +186,6 @@ export function groupByAccount(rows) {
         };
     });
 }
-/** Short human quota cell: "12%", "limited", or "—" when no data. */
 export function formatQuota(quota) {
     if (quota.status === 'out_of_credits')
         return 'no credits';
@@ -272,16 +195,9 @@ export function formatQuota(quota) {
         return '—';
     return `${quota.usedPercent}%${quota.stale ? '*' : ''}`;
 }
-// ---------------------------------------------------------------------------
-// Rendering. Each cell is padded as PLAIN text to a computed width, then colored
-// — coloring first would let chalk's escape codes throw off the alignment.
-// chalk auto-disables color off a TTY, so the strings tests assert on are plain.
-// ---------------------------------------------------------------------------
-/** Pad plain `text` to `width`, then apply `paint`. Alignment survives coloring. */
 function cell(text, width, paint) {
     return paint(text.padEnd(width));
 }
-/** Color for a quota value: red limited, yellow ≥80%, green below, dim unknown. */
 function quotaPaint(quota) {
     if (quota.status === 'rate_limited')
         return chalk.red;
@@ -289,18 +205,15 @@ function quotaPaint(quota) {
         return chalk.dim;
     return quota.usedPercent >= 80 ? chalk.yellow : chalk.green;
 }
-/** The ready cell text + color: green "ready", else the reason. */
 function readyCell(ready, reason, width) {
     if (ready)
         return cell('ready', width, chalk.green);
     const label = reason ?? 'not ready';
     return cell(label, width, reason === 'signed out' ? chalk.gray : chalk.yellow);
 }
-/** The signed-in cell — three chars so the column stays aligned. */
 function signedCell(signedIn) {
     return signedIn ? chalk.green('yes') : chalk.gray('no ');
 }
-/** A host note (skipped / error / no installs), or '' when the host has rows. */
 function hostNote(result) {
     if (result.skipped)
         return chalk.dim(`  ${result.skipped}`);
@@ -310,15 +223,10 @@ function hostNote(result) {
         return chalk.dim('  no harnesses installed');
     return '';
 }
-/** Widest string in a list, floored at `min`. */
 function colWidth(values, min) {
     return Math.max(min, ...values.map((v) => v.length));
 }
 const QUOTA_W = 7;
-/**
- * Render the device × harness table: one block per device, one row per installed
- * (agent, version) with account / signed-in / quota / ready. Pure.
- */
 export function renderHarnessMatrix(results) {
     const lines = [chalk.bold('Fleet harnesses')];
     const allRows = results.flatMap((r) => r.rows);
@@ -338,10 +246,6 @@ export function renderHarnessMatrix(results) {
     lines.push(chalk.gray('  quota = highest window utilization (* = cached) · ready = signed in and not rate-limited'));
     return lines;
 }
-/**
- * Render the device × account table: one block per device, one row per distinct
- * account (installs sharing it collapsed), showing which harnesses use it. Pure.
- */
 export function renderAccountsMatrix(results) {
     const lines = [chalk.bold('Fleet accounts')];
     const grouped = results.map((r) => ({ ...r, groups: groupByAccount(r.rows) }));
@@ -368,11 +272,6 @@ function fleetVerdictLabel(verdict) {
         return 'LIMITED';
     return verdict.toUpperCase();
 }
-/**
- * Account × device matrix used by `agents accounts list --fleet`.
- * Rows are logical accounts, not installations. Columns come from the
- * daemon-state observations already joined onto each account row.
- */
 export function renderAccountFleetMatrix(rows, opts = {}) {
     const devices = [...new Set(rows.flatMap((row) => row.devices.map((device) => device.device)))].sort();
     const accountLabels = rows.map((row) => `${row.harness}#${row.name ?? 'unnamed'} ${row.identityLabel}`);