@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/devices/doctor-overview-cache.d.ts

@@ -1,51 +1,18 @@
-/** Serve a cached snapshot without recomputing while it is younger than this. */
 export declare const DOCTOR_OVERVIEW_FRESH_MS = 90000;
-/** Injectable IO + clock so tests exercise the real fs at a temp dir, no mocks. */
 interface DoctorOverviewCacheDeps {
-    /** Cache directory (default: the real `~/.agents/.cache`). */
     dir?: string;
-    /** Clock (default: {@link Date.now}). */
     now?: () => number;
 }
-/** Read the last snapshot (best-effort; missing/corrupt/wrong-version → null). */
 export declare function readDoctorOverviewCache(deps?: DoctorOverviewCacheDeps): {
     fetchedAt: number;
     payload: unknown;
 } | null;
-/** Persist a fresh overview payload (best-effort; tmp+rename so reads are atomic). */
 export declare function writeDoctorOverviewCache(payload: unknown, deps?: DoctorOverviewCacheDeps): void;
-/**
- * Drop the cached overview after a doctor repair attempt changes (or fails to
- * change) live health. Best-effort and deliberately narrow: it never touches
- * the singleflight lock, so an in-progress overview compute remains owned by
- * its holder and no repair can create a retry loop.
- */
 export declare function invalidateDoctorOverviewCache(deps?: DoctorOverviewCacheDeps): void;
-/**
- * Result of {@link enterDoctorOverviewGate}.
- *  - `cached` non-null → the caller MUST print this string and return; no compute.
- *  - `cached` null     → the caller holds the singleflight lock: compute the
- *    overview, call {@link writeDoctorOverviewCache}, and invoke `release()` on
- *    the way out. Call `release()` in a `finally` so a compute that throws still
- *    frees the lock promptly (idempotent).
- */
 interface OverviewGate {
     cached: string | null;
     release?: () => void;
 }
-/**
- * Enter the doctor-overview singleflight gate. Returns a cached string to print,
- * or a lock token telling the caller to compute (and then write + release).
- *
- * Contract:
- *  - Fresh snapshot present (and not `forceRefresh`) → `{ cached }`, no lock.
- *  - Otherwise exactly one caller holds the lock and gets `{ cached: null,
- *    release }`; everyone else blocks on the lock, then (on acquiring it)
- *    double-checks and serves the winner's fresh write — or, if the winner runs
- *    past the wait budget, serves the last snapshot — rather than recomputing.
- *  - Never throws: any IO/lock failure degrades to a compute token or a served
- *    snapshot.
- */
 export declare function enterDoctorOverviewGate(opts?: {
     forceRefresh?: boolean;
     freshMs?: number;

package/dist/lib/devices/doctor-overview-cache.js

@@ -1,31 +1,3 @@
-/**
- * Singleflight + short-TTL disk cache for the `agents doctor --json` OVERVIEW
- * payload (the bare, no-target form the menu-bar helper and other pollers read).
- *
- * Why this exists (RUSH-2153): the bare `doctor --json` overview is expensive —
- * it probes every host CLI, spawns every installed agent CLI for its sign-in,
- * and diffs every agent×version against its source. On an idle box that is a few
- * seconds; on a loaded one it is minutes. The menu-bar helper polls it on a 60s
- * timer with a per-*process* in-flight guard, so nothing coalesces ACROSS
- * processes: a helper relaunch (or any second poller) each launches its own
- * live compute, and a helper killed mid-run orphans its `doctor --json` child,
- * which keeps spinning. In steady state this stacked to dozens of concurrent
- * `doctor --json` processes pinning ~14 cores and driving load to ~300.
- *
- * The fix mirrors the {@link readStatsCache}/`writeStatsCache` mirror-file
- * convention: reads are cache-first, and when a live compute IS needed exactly
- * ONE runs at a time. The singleflight is the shared `proper-lockfile` lock (via
- * `ensureLockTarget` + `lockfile.lock`) — the SAME battle-tested lock the rest of
- * the CLI uses (fs-atomic.ts) — which owns two things a hand-rolled lock got
- * wrong: (1) it auto-refreshes the lock's mtime on a timer while held, so a live
- * computer whose compute runs for minutes is never mistaken for a crashed one
- * and stolen; (2) `release()` only ever releases the lock THIS caller acquired,
- * so a slow computer can't delete a successor's lock. Waiters block on the lock
- * up to a bounded budget, then serve the last snapshot rather than pile on.
- *
- * The cache write is tmp+rename so a concurrent reader never sees a partial file.
- * All IO is best-effort: a failure degrades to a live compute, never a throw.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import lockfile from 'proper-lockfile';
@@ -33,26 +5,12 @@ import { getCacheDir } from '../state.js';
 import { ensureLockTarget } from '../fs-atomic.js';
 const CACHE_FILE = '.doctor-overview.json';
 const LOCK_TARGET_FILE = '.doctor-overview.lock-target';
-/** Serve a cached snapshot without recomputing while it is younger than this. */
 export const DOCTOR_OVERVIEW_FRESH_MS = 90_000;
-/**
- * A held lock older than this is treated as a crashed computer and broken. The
- * lock's mtime is auto-refreshed by proper-lockfile every `stale/2` while a live
- * computer holds it (the event loop turns during the compute's `await`ed
- * subprocess spawns), so this only ever breaks a genuinely dead holder.
- */
 const LOCK_STALE_MS = 60_000;
-/**
- * How long a waiter blocks on the lock before giving up and serving the last
- * snapshot. Sized to comfortably exceed a slow (multi-second-to-minutes) compute
- * so a waiter normally gets the winner's fresh write; capped so a truly wedged
- * holder never hangs the CLI (it serves stale instead).
- */
 const LOCK_RETRIES = { retries: 240, factor: 1, minTimeout: 500, maxTimeout: 500 };
 function cachePath(dir) {
     return path.join(dir, CACHE_FILE);
 }
-/** Read the last snapshot (best-effort; missing/corrupt/wrong-version → null). */
 export function readDoctorOverviewCache(deps = {}) {
     const dir = deps.dir ?? getCacheDir();
     try {
@@ -62,11 +20,9 @@ export function readDoctorOverviewCache(deps = {}) {
         }
     }
     catch {
-        // missing or corrupt — treat as no snapshot
     }
     return null;
 }
-/** Persist a fresh overview payload (best-effort; tmp+rename so reads are atomic). */
 export function writeDoctorOverviewCache(payload, deps = {}) {
     const dir = deps.dir ?? getCacheDir();
     const now = deps.now ?? Date.now;
@@ -79,37 +35,16 @@ export function writeDoctorOverviewCache(payload, deps = {}) {
         fs.renameSync(tmp, cachePath(dir));
     }
     catch {
-        // best-effort; a failed write just means the next read falls back to live
     }
 }
-/**
- * Drop the cached overview after a doctor repair attempt changes (or fails to
- * change) live health. Best-effort and deliberately narrow: it never touches
- * the singleflight lock, so an in-progress overview compute remains owned by
- * its holder and no repair can create a retry loop.
- */
 export function invalidateDoctorOverviewCache(deps = {}) {
     const dir = deps.dir ?? getCacheDir();
     try {
         fs.unlinkSync(cachePath(dir));
     }
     catch {
-        // Missing/unlinkable cache is already equivalent to invalidated.
     }
 }
-/**
- * Enter the doctor-overview singleflight gate. Returns a cached string to print,
- * or a lock token telling the caller to compute (and then write + release).
- *
- * Contract:
- *  - Fresh snapshot present (and not `forceRefresh`) → `{ cached }`, no lock.
- *  - Otherwise exactly one caller holds the lock and gets `{ cached: null,
- *    release }`; everyone else blocks on the lock, then (on acquiring it)
- *    double-checks and serves the winner's fresh write — or, if the winner runs
- *    past the wait budget, serves the last snapshot — rather than recomputing.
- *  - Never throws: any IO/lock failure degrades to a compute token or a served
- *    snapshot.
- */
 export async function enterDoctorOverviewGate(opts = {}, deps = {}) {
     const dir = deps.dir ?? getCacheDir();
     const now = deps.now ?? Date.now;
@@ -122,7 +57,6 @@ export async function enterDoctorOverviewGate(opts = {}, deps = {}) {
             return JSON.stringify(c.payload, null, 2);
         return null;
     };
-    // 1. Fast path: a fresh snapshot serves without any compute or lock.
     const fast = serveFresh();
     if (fast !== null)
         return { cached: fast };
@@ -131,41 +65,26 @@ export async function enterDoctorOverviewGate(opts = {}, deps = {}) {
             fs.mkdirSync(dir, { recursive: true });
     }
     catch {
-        // Can't even make the cache dir — fall back to an unguarded compute.
         return { cached: null, release: () => { } };
     }
     const lockTarget = path.join(dir, LOCK_TARGET_FILE);
     ensureLockTarget(lockTarget);
-    // 2. Singleflight via proper-lockfile: one caller holds the lock and computes;
-    //    the rest block here until it releases.
     let release = null;
     try {
         release = await lockfile.lock(lockTarget, {
             stale: LOCK_STALE_MS,
             retries: LOCK_RETRIES,
-            // A peer broke our lock (only possible if we somehow went stale). Don't
-            // crash on the async callback; we re-check the cache and serve/recompute.
             onCompromised: () => { },
         });
     }
     catch {
-        // 3. Winner held the lock past our wait budget. Serve the last snapshot
-        //    (even if stale) rather than pile on; only if there is genuinely none do
-        //    we compute unguarded (rare cold-start under sustained load).
         const c = readDoctorOverviewCache({ dir });
         if (c)
             return { cached: JSON.stringify(c.payload, null, 2) };
         return { cached: null, release: () => { } };
     }
-    // 4. Acquired. The winner may have written a fresh snapshot while we waited —
-    //    serve it and release, instead of recomputing.
     const afterWait = serveFresh();
     if (afterWait !== null) {
-        // AWAIT, don't fire-and-forget: returning while the lockfile is still on
-        // disk makes the next caller retry against a lock that is logically free —
-        // the same pile-up this gate exists to prevent, just narrowed to the window
-        // between return and unlink. We are already in an async function, so the
-        // wait costs one unlink.
         await release().catch(() => { });
         return { cached: afterWait };
     }

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

@@ -1,135 +1,46 @@
-/**
- * Cross-device harness divergence for `agents doctor` (RUSH-2027).
- *
- * `agents fleet status` already fans out `agents doctor --json` per device and
- * builds a {@link FleetHealthReport} of coarse device health (reachable, CLIs
- * installed, agents-cli version skew, local sync drift). It deliberately does
- * NOT compare fine-grained *resource presence* across devices — so a plugin like
- * `swarm` installed on one box but missing on another is silent until a user
- * types `/swarm:run` on the wrong machine and gets `Unknown command`.
- *
- * This module is the missing comparison. Each device self-reports its installed
- * inventory (resource kinds, per-agent version sets, `.agents`/`.system` repo
- * state) in its `doctor --json` payload; {@link compareFleetInventories} takes
- * the collected per-device inventories and, treating the local machine as the
- * baseline, flags:
- *
- *   1. Resource presence gaps  — a resource present on one device, missing on
- *      another (either direction relative to the local baseline).
- *   2. Agent version gaps      — an agent version installed on one device but
- *      not another (e.g. `yosemite-s0 missing claude@2.1.220`).
- *   3. `.agents`/`.system` repo drift — a device whose config-repo HEAD, branch,
- *      or dirty state diverges from the local baseline.
- *
- * Pure and SSH-free: the SSH fan-out lives in the doctor command; this module
- * only consumes the already-collected payloads, so the divergence logic is
- * unit-tested against fixture inventories with no live fleet.
- */
-/** Resource kinds compared across devices. Mirrors {@link DoctorKind} plus the
- *  top-level `workflows`/`memory` inventory that `getAvailableResources` emits;
- *  `promptcuts` is a single present/absent bit surfaced as one named resource. */
 export type FleetResourceKind = 'commands' | 'skills' | 'hooks' | 'rules' | 'mcp' | 'permissions' | 'subagents' | 'plugins' | 'promptcuts' | 'workflows';
 export declare const FLEET_RESOURCE_KINDS: FleetResourceKind[];
-/** Per-repo state for the `.agents` (user) or `.system` config repo, as a device
- *  self-reports it. `null` fields mean "not a git repo / unreadable" on that box. */
 export interface RepoState {
-    /** Current branch, or null when detached / unreadable. */
     branch: string | null;
-    /** Short HEAD commit (8 chars), or null when unreadable. */
     head: string | null;
-    /** True when the working tree has uncommitted changes. */
     dirty: boolean;
 }
-/**
- * Per-version sign-in state a device self-reports, so the fleet doctor can show
- * every installed version's account (and a provable logged-out) without a second
- * SSH round-trip. `provable` is true only when the credential is absent from BOTH
- * the version home and the active/global HOME (see `credentialPresence`); an
- * unprovable absence (opaque/keychain agent) is a warning, not a critical.
- */
 export interface FleetVersionSignIn {
     version: string;
-    /** A usable local credential was found for this version (or shared globally). */
     signedIn: boolean;
-    /** Human account label (email, org badge, or opaque id), when derivable. */
     account: string | null;
-    /** True only when a logged-out state is PROVABLE (credential absent per-version
-     *  AND globally) — the caller gates a critical on this. */
     provable: boolean;
 }
-/**
- * A deliberately closed summary of one version's generated hook-wrapper
- * runtime. Fleet payloads carry only this state — never the remote wrapper
- * path, embedded source path, or detector text.
- */
 export declare const FLEET_HOOK_RUNTIME_STATES: readonly ["healthy", "broken", "not-applicable"];
 export type FleetHookRuntimeState = typeof FLEET_HOOK_RUNTIME_STATES[number];
-/**
- * The self-reported harness inventory a single device emits in `doctor --json`.
- * Comparable device-to-device with no further probing.
- */
 export interface FleetInventory {
-    /** Installed resource names per kind. `rules` here are the top-level rules
-     *  files (memory presets), not per-agent compiled AGENTS.md. */
     resources: Record<FleetResourceKind, string[]>;
-    /** Installed version ids per agent id (e.g. `{ claude: ['2.1.170','2.1.220'] }`). */
     agentVersions: Record<string, string[]>;
-    /** State of the user (`~/.agents`) and system (`~/.agents/.system`) config repos. */
     repos: {
         agents: RepoState | null;
         system: RepoState | null;
     };
-    /** Per-version sign-in state per agent id, for the fleet doctor's accounts
-     *  line and cross-fleet logged-out criticals. Optional — an older CLI that
-     *  predates this field omits it, and the caller degrades to a warning
-     *  ("older agents-cli — can't report per-version sign-in"). */
     signIn?: Record<string, FleetVersionSignIn[]>;
-    /** Generated hook-wrapper health per installed agent/version. Optional for
-     *  wire compatibility with older remotes; a present value is fully validated
-     *  before it is used by fleet doctor. */
     hookRuntime?: Record<string, Record<string, FleetHookRuntimeState>>;
 }
-/** A device's inventory paired with its name (and reachability). A device that
- *  was unreachable / failed to report carries `inventory: null` and is skipped
- *  by the comparison (its absence is a `fleet status` concern, not divergence). */
 export interface DeviceInventory {
     name: string;
     inventory: FleetInventory | null;
 }
 export type FleetDivergenceKind = 'resource-missing-remote' | 'resource-missing-local' | 'agent-version-missing-remote' | 'agent-version-missing-local' | 'repo-drift';
-/** One cross-device divergence finding, baseline = the local machine. */
 export interface FleetDivergence {
     kind: FleetDivergenceKind;
-    /** The device the finding is about (the remote box, or the local box for a
-     *  `*-missing-local` finding where a remote has something local lacks). */
     device: string;
-    /** Resource kind for a resource finding; agent id for a version finding;
-     *  `agents`/`system` for a repo finding. */
     category: string;
-    /** The specific resource name / version id / repo label that diverges. */
     name: string;
-    /** Human-readable one-liner, ready for the warnings list. */
     message: string;
 }
 interface FleetDivergenceReport {
-    /** Name of the device used as the comparison baseline (the local machine). */
     baseline: string;
     divergences: FleetDivergence[];
-    /** Devices that reported an inventory and were compared. */
     comparedDevices: string[];
-    /** Devices that could not be compared (offline / no inventory in payload). */
     skippedDevices: string[];
     hasDivergence: boolean;
 }
-/**
- * Compare a set of per-device inventories against the local baseline and emit
- * every cross-device divergence. The baseline is the device whose name equals
- * {@link baselineName} (the local machine); if that device has no inventory the
- * report is empty (nothing to compare against). Devices with no inventory are
- * recorded under `skippedDevices` and never produce false "missing" findings.
- *
- * Ordering is deterministic (device, then category, then name) so the human and
- * JSON output — and the tests — are stable.
- */
 export declare function compareFleetInventories(devices: DeviceInventory[], baselineName: string): FleetDivergenceReport;
 export {};

package/dist/lib/devices/fleet-divergence.js

@@ -1,30 +1,3 @@
-/**
- * Cross-device harness divergence for `agents doctor` (RUSH-2027).
- *
- * `agents fleet status` already fans out `agents doctor --json` per device and
- * builds a {@link FleetHealthReport} of coarse device health (reachable, CLIs
- * installed, agents-cli version skew, local sync drift). It deliberately does
- * NOT compare fine-grained *resource presence* across devices — so a plugin like
- * `swarm` installed on one box but missing on another is silent until a user
- * types `/swarm:run` on the wrong machine and gets `Unknown command`.
- *
- * This module is the missing comparison. Each device self-reports its installed
- * inventory (resource kinds, per-agent version sets, `.agents`/`.system` repo
- * state) in its `doctor --json` payload; {@link compareFleetInventories} takes
- * the collected per-device inventories and, treating the local machine as the
- * baseline, flags:
- *
- *   1. Resource presence gaps  — a resource present on one device, missing on
- *      another (either direction relative to the local baseline).
- *   2. Agent version gaps      — an agent version installed on one device but
- *      not another (e.g. `yosemite-s0 missing claude@2.1.220`).
- *   3. `.agents`/`.system` repo drift — a device whose config-repo HEAD, branch,
- *      or dirty state diverges from the local baseline.
- *
- * Pure and SSH-free: the SSH fan-out lives in the doctor command; this module
- * only consumes the already-collected payloads, so the divergence logic is
- * unit-tested against fixture inventories with no live fleet.
- */
 export const FLEET_RESOURCE_KINDS = [
     'commands',
     'skills',
@@ -37,11 +10,6 @@ export const FLEET_RESOURCE_KINDS = [
     'promptcuts',
     'workflows',
 ];
-/**
- * A deliberately closed summary of one version's generated hook-wrapper
- * runtime. Fleet payloads carry only this state — never the remote wrapper
- * path, embedded source path, or detector text.
- */
 export const FLEET_HOOK_RUNTIME_STATES = ['healthy', 'broken', 'not-applicable'];
 function sortedUnique(list) {
     return Array.from(new Set(list)).sort();
@@ -49,13 +17,6 @@ function sortedUnique(list) {
 function repoLabel(repo) {
     return repo === 'agents' ? '.agents' : '.system';
 }
-/** Describe how a remote repo state diverges from the local baseline, or null
- *  when they match. Compares HEAD first (the load-bearing difference), then
- *  branch, then a dirty tree on either side.
- *
- *  HEAD and branch differences are symmetric — by convention the remote is the
- *  one "diverged from the baseline" — but a dirty tree belongs to exactly one
- *  box, and blaming the wrong one sends the user to a clean machine. */
 function describeRepoDrift(local, remote) {
     if (local.head && remote.head && local.head !== remote.head) {
         return { detail: `repo diverged: HEAD ${remote.head} != local ${local.head}`, blame: 'remote' };
@@ -73,28 +34,14 @@ function describeRepoDrift(local, remote) {
     }
     return null;
 }
-/**
- * Compare a set of per-device inventories against the local baseline and emit
- * every cross-device divergence. The baseline is the device whose name equals
- * {@link baselineName} (the local machine); if that device has no inventory the
- * report is empty (nothing to compare against). Devices with no inventory are
- * recorded under `skippedDevices` and never produce false "missing" findings.
- *
- * Ordering is deterministic (device, then category, then name) so the human and
- * JSON output — and the tests — are stable.
- */
 export function compareFleetInventories(devices, baselineName) {
     const baseline = devices.find((d) => d.name === baselineName)?.inventory ?? null;
     const remotes = devices.filter((d) => d.name !== baselineName);
     const comparedDevices = [];
     const skippedDevices = [];
     const divergences = [];
-    /** Repos already reported as the BASELINE's problem — one dirty local tree is
-     *  one finding, not one per remote compared against. */
     const localBlamed = new Set();
     if (!baseline) {
-        // No local baseline to compare against — record every remote as skipped so
-        // the caller can say so, but emit no divergences (we can't know the truth).
         for (const d of remotes)
             skippedDevices.push(d.name);
         return {
@@ -112,7 +59,6 @@ export function compareFleetInventories(devices, baselineName) {
         }
         comparedDevices.push(remote.name);
         const inv = remote.inventory;
-        // 1) Resource presence, both directions.
         for (const kind of FLEET_RESOURCE_KINDS) {
             const localSet = new Set(baseline.resources[kind] ?? []);
             const remoteSet = new Set(inv.resources[kind] ?? []);
@@ -139,7 +85,6 @@ export function compareFleetInventories(devices, baselineName) {
                 }
             }
         }
-        // 2) Agent version parity, both directions, per agent id.
         const agentIds = sortedUnique([
             ...Object.keys(baseline.agentVersions),
             ...Object.keys(inv.agentVersions),
@@ -170,19 +115,15 @@ export function compareFleetInventories(devices, baselineName) {
                 }
             }
         }
-        // 3) `.agents` / `.system` repo drift vs the local baseline.
         for (const repo of ['agents', 'system']) {
             const localRepo = baseline.repos[repo];
             const remoteRepo = inv.repos[repo];
             if (!localRepo || !remoteRepo)
-                continue; // one side isn't a readable repo
+                continue;
             const drift = describeRepoDrift(localRepo, remoteRepo);
             if (!drift)
                 continue;
             if (drift.blame === 'local') {
-                // The BASELINE owns this one. File it against the baseline, and only
-                // once: the local tree being dirty is a single fact about this machine,
-                // not one problem per remote we happened to compare against.
                 if (localBlamed.has(repo))
                     continue;
                 localBlamed.add(repo);

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

@@ -1,30 +1,3 @@
-/**
- * Build the self-reported harness inventory a device emits in `doctor --json`
- * for cross-device divergence detection (RUSH-2027).
- *
- * Kept separate from {@link ../devices/fleet-divergence.js} — which stays a pure,
- * SSH-free comparator — because this reads the live install (resource dirs,
- * installed version homes, config repos). One call produces the {@link
- * FleetInventory} that both the local baseline and every remote box serialize
- * into their doctor payload; the comparator then diffs those payloads.
- */
 import { type FleetInventory, type FleetVersionSignIn } from './fleet-divergence.js';
-/**
- * Probe every installed version's sign-in state, per agent. For each version we
- * read its own home's account (via the shim-set config dir) and, when logged
- * out, decide whether that is PROVABLE: an agent that can't be inspected
- * (`!supportsAccountInspection`) never claims logged out, and a version that
- * merely lacks its own credential but shares the global login (`active`) is
- * signed in, not out. Pure reads (file-presence + cheap account parse), no
- * network, no keychain prompt. Only agents with at least one installed version
- * appear, so the map lines up with {@link FleetInventory.agentVersions}.
- */
 export declare function collectLocalFleetSignIn(): Promise<Record<string, FleetVersionSignIn[]>>;
-/**
- * Collect this machine's harness inventory: installed resources per kind,
- * installed version ids per agent, `.agents`/`.system` repo state, and
- * per-version sign-in. Pure reads — never mutates the install. `promptcuts` (a
- * single present/absent bit in {@link getAvailableResources}) is surfaced as a
- * one-element list so it compares like any other named resource.
- */
 export declare function collectLocalFleetInventory(cwd?: string): Promise<FleetInventory>;

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

@@ -1,13 +1,3 @@
-/**
- * Build the self-reported harness inventory a device emits in `doctor --json`
- * for cross-device divergence detection (RUSH-2027).
- *
- * Kept separate from {@link ../devices/fleet-divergence.js} — which stays a pure,
- * SSH-free comparator — because this reads the live install (resource dirs,
- * installed version homes, config repos). One call produces the {@link
- * FleetInventory} that both the local baseline and every remote box serialize
- * into their doctor payload; the comparator then diffs those payloads.
- */
 import { getAvailableResources, getVersionHomePath, isVersionIsolated, listInstalledVersions } from '../installations/versions.js';
 import { supports } from '../capabilities.js';
 import { checkVersionHookWiring } from '../hooks/install.js';
@@ -21,16 +11,6 @@ function toRepoState(snap) {
         return null;
     return { branch: snap.branch, head: snap.head, dirty: snap.dirty };
 }
-/**
- * Probe every installed version's sign-in state, per agent. For each version we
- * read its own home's account (via the shim-set config dir) and, when logged
- * out, decide whether that is PROVABLE: an agent that can't be inspected
- * (`!supportsAccountInspection`) never claims logged out, and a version that
- * merely lacks its own credential but shares the global login (`active`) is
- * signed in, not out. Pure reads (file-presence + cheap account parse), no
- * network, no keychain prompt. Only agents with at least one installed version
- * appear, so the map lines up with {@link FleetInventory.agentVersions}.
- */
 export async function collectLocalFleetSignIn() {
     const out = {};
     await Promise.all(ALL_AGENT_IDS.map(async (agent) => {
@@ -44,25 +24,15 @@ export async function collectLocalFleetSignIn() {
             try {
                 const info = await getAccountInfo(agent, home);
                 signedIn = info.signedIn;
-                // Prefix the durable account name when this identity has been named.
                 const display = accountDisplayLabel(info);
                 const saved = findNativeAccountByIdentity(readMeta(), agent, info);
                 account = (saved ? `${saved.name} · ${display || saved.identityLabel || saved.identityKey}` : display) || null;
             }
             catch {
-                /* advisory only — treat as logged out, provability decided below */
             }
-            // Provable logout: the agent is inspectable AND the credential is absent
-            // from BOTH the version home and the active/global HOME. An opaque or
-            // keychain-only agent, or one sharing the global login, is never a
-            // provable logout.
             let provable = false;
             if (!signedIn && supportsAccountInspection(agent)) {
                 const presence = credentialPresence(agent, home);
-                // `knownLocation` is load-bearing: an agent can sit in the inspection
-                // set with no credential path (cursor does), and then both probes are
-                // false only because there is nothing to look for. Treating that as a
-                // provable logout prints a CRITICAL for a version that is signed in.
                 provable = presence.knownLocation && !presence.perVersion && !presence.active;
             }
             return { version, signedIn, account, provable };
@@ -71,13 +41,6 @@ export async function collectLocalFleetSignIn() {
     }));
     return out;
 }
-/**
- * Collect this machine's harness inventory: installed resources per kind,
- * installed version ids per agent, `.agents`/`.system` repo state, and
- * per-version sign-in. Pure reads — never mutates the install. `promptcuts` (a
- * single present/absent bit in {@link getAvailableResources}) is surfaced as a
- * one-element list so it compares like any other named resource.
- */
 export async function collectLocalFleetInventory(cwd = process.cwd()) {
     const available = getAvailableResources(cwd);
     const resources = {};
@@ -86,7 +49,6 @@ export async function collectLocalFleetInventory(cwd = process.cwd()) {
             resources[kind] = available.promptcuts ? ['promptcuts.yaml'] : [];
         }
         else if (kind === 'rules') {
-            // getAvailableResources exposes top-level rules under `memory`.
             resources[kind] = [...available.memory].sort();
         }
         else {