@phnx-labs/agents-cli 1.20.87 → 1.20.88

package/dist/commands/exec.js

@@ -1667,7 +1667,7 @@ export function registerRunCommand(program) {
             const { pickSessionInteractive } = await import('./sessions.js');
             const { buildContinuePrompt } = await import('../lib/loop.js');
             // Freshen the index for this agent before any lookup (incremental, cached).
-            // AgentId is wider than SessionAgentId (cursor/amp/… keep no transcripts);
+            // AgentId is wider than SessionAgentId (amp/kiro/goose/copilot keep no transcripts);
             // those simply yield no matches and fall through to the not-found error.
             const sessionAgent = agent;
             await discoverSessions({ agent: sessionAgent, version });
@@ -1899,8 +1899,8 @@ export function registerRunCommand(program) {
         // safest native mode (modes[0], typically edit). That covers both the
         // implicit default and an explicit `--mode plan`, so multi-agent
         // scripts can pass a uniform plan flag without per-agent branching.
-        // Elevation is never silent: we warn on stderr (yellow when the user
-        // explicitly asked for plan; gray for the implicit default / auto).
+        // Mode degradation is never silent: buildExecCommand emits one stderr
+        // warning for the requested-to-resolved transition unless --quiet is set.
         // `skip` still hard-fails when unsupported — pretending we bypassed
         // permissions would be unsafe.
         const modeIsDefault = modeSource === 'default';
@@ -1913,20 +1913,7 @@ export function registerRunCommand(program) {
             console.error(chalk.red(err.message));
             process.exit(1);
         }
-        if (resolvedMode !== requestedMode) {
-            mode = resolvedMode;
-            if (!options.quiet) {
-                if (requestedMode === 'plan' && !modeIsDefault) {
-                    process.stderr.write(chalk.yellow(`[agents] ${agent} has no read-only 'plan' mode; using '${mode}' (writable) instead. Pass --mode ${mode} to silence this.\n`));
-                }
-                else {
-                    process.stderr.write(chalk.gray(`[agents] ${agent} has no '${requestedMode}' mode; using '${mode}'\n`));
-                }
-            }
-        }
-        else {
-            mode = resolvedMode;
-        }
+        mode = resolvedMode;
         // Fail fast on the headless-plan stall footgun: a slash command run
         // headless under the implicit default 'plan' mode hangs forever at
         // ExitPlanMode (no TTY to approve the plan). Tell the user how to fix it
@@ -1935,7 +1922,7 @@ export function registerRunCommand(program) {
         const stallCmd = headlessPlanStallCommand({
             prompt,
             interactive: options.interactive,
-            mode,
+            mode: resolvedMode,
             modeIsDefault,
         });
         if (stallCmd) {
@@ -2029,7 +2016,7 @@ export function registerRunCommand(program) {
             version,
             prompt,
             interactive: options.interactive || forceInteractive,
-            mode,
+            mode: requestedMode,
             effort,
             cwd: options.cwd,
             model,
@@ -2040,6 +2027,7 @@ export function registerRunCommand(program) {
             name: options.name,
             resume: resumeNative,
             verbose: options.verbose,
+            modeWarningState: { quiet: options.quiet },
             // --raw, --no-tmux (commander negation → options.tmux === false), and
             // --disable-tmux all bypass the interactive tmux wrapper. AGENTS_NO_TMUX=1
             // does the same via the env check in exec.ts.

package/dist/commands/inspect.js

@@ -32,6 +32,7 @@ import { listMcpServerConfigs, discoverMcpConfigsFromRepo } from '../lib/mcp.js'
 import { discoverPlugins, discoverPluginsInDir, pluginResourceGroups } from '../lib/plugins.js';
 import { PLUGIN_GROUP_COLORS } from './plugins.js';
 import { countSessionsInScope } from '../lib/session/discover.js';
+import { isSessionTrackedAgent } from '../lib/session/types.js';
 import { damerauLevenshtein } from '../lib/fuzzy.js';
 import { terminalWidth, truncateToWidth, stringWidth, stripAnsi } from '../lib/session/width.js';
 /** Resource kinds the inspect command can drill into. */
@@ -1256,14 +1257,11 @@ function safeStat(p) {
         return null;
     }
 }
-const SESSION_AGENTS = new Set([
-    'claude', 'codex', 'gemini', 'opencode', 'openclaw', 'rush', 'hermes', 'grok', 'kimi', 'droid',
-]);
 function safeCountSessions(agent) {
-    if (!SESSION_AGENTS.has(agent))
+    if (!isSessionTrackedAgent(agent))
         return 0;
     try {
-        return countSessionsInScope({ agent: agent });
+        return countSessionsInScope({ agent });
     }
     catch {
         return 0;

package/dist/commands/routines.js

@@ -19,7 +19,7 @@ import { fireWebhookJobs, matchJobsToWebhook } from '../lib/triggers/webhook.js'
 import { getRoutinesDir } from '../lib/state.js';
 import { IS_WINDOWS } from '../lib/platform/index.js';
 import { safeJoin } from '../lib/paths.js';
-import { executeJob, executeJobDetached, monitorRunningJobs } from '../lib/runner.js';
+import { executeJob, executeJobDetached, monitorRunningJobs, ROUTINE_AGENT_IDS } from '../lib/runner.js';
 import { JobScheduler } from '../lib/scheduler.js';
 import { detectOverdueJobs } from '../lib/overdue.js';
 import { isInteractiveTerminal, requireInteractiveSelection } from './utils.js';
@@ -572,7 +572,7 @@ export function registerRoutinesCommands(program) {
         .command('add [nameOrPath]')
         .description('Create a new routine from a YAML file or inline flags. Starts the scheduler automatically if it is not already running.')
         .option('-s, --schedule <cron>', 'Cron schedule in standard format (5 fields: minute hour day month weekday)')
-        .option('-a, --agent <agent>', 'Which agent runs this routine: claude, codex, antigravity, cursor, or opencode')
+        .option('-a, --agent <agent>', `Which agent runs this routine: ${ROUTINE_AGENT_IDS.join(', ')}`)
         .option('--workflow <name>', 'Run an installed workflow (~/.agents/workflows/<name>) via `agents run`. Mutually exclusive with --agent.')
         .option('--command <sh>', 'Run a plain shell command directly (no agent, no auth, no sandbox) — for deterministic housekeeping routines. Mutually exclusive with --agent and --workflow; --prompt is not used.')
         .option('-p, --prompt <prompt>', 'Task instruction for the agent')

package/dist/commands/sessions.js

@@ -2368,6 +2368,7 @@ export function buildResumeCommand(session) {
         case 'grok':
         case 'kimi':
         case 'droid':
+        case 'cursor':
             // Grok (and some others) sessions are captured artifacts, not resumable the same way.
             return null;
     }

package/dist/commands/ssh.js

@@ -313,7 +313,7 @@ function printFleetResults(results) {
     if (failed > 0)
         process.exitCode = 1;
 }
-function localHealthRow(self, stats) {
+async function localHealthRow(self, stats) {
     return {
         name: self,
         platform: process.platform === 'darwin' ? 'macos' : process.platform,
@@ -324,7 +324,7 @@ function localHealthRow(self, stats) {
         orphans: countOrphans(),
         // Local baseline inventory for cross-device divergence (RUSH-2027) — the
         // yardstick every remote box is compared against.
-        inventory: collectLocalFleetInventory(process.cwd()),
+        inventory: await collectLocalFleetInventory(process.cwd()),
     };
 }
 async function probeRemoteHealth(target) {
@@ -369,7 +369,7 @@ async function runFleetStatus(opts) {
     // read from a fresh probe, not a stale tailscale snapshot (RUSH-1965).
     // Best-effort: a registry write must never break the status render.
     await writeReachability(collectReachabilityWriteBacks(reg, statsMap)).catch(() => { });
-    const rows = [localHealthRow(self, statsMap.get(self))];
+    const rows = [await localHealthRow(self, statsMap.get(self))];
     const remoteTargets = remoteFleetTargets(planned, self)
         .map((t) => ({
         name: t.device.name,

package/dist/commands/usage.d.ts

@@ -6,8 +6,9 @@
  *   - codex:  parsed from latest session log's rate_limits event
  *   - kimi:   live Kimi Code /usages API call (cached for 2 minutes)
  *   - droid:  live Factory billing/limits API call (cached for 2 minutes)
- *   - others: marked as "not exposed by CLI" (Gemini, OpenCode, Cursor, etc.
- *     don't publish per-account usage today)
+ *   - grok:   parsed from the latest local usage event
+ *   - cursor: live Cursor usage API call (cached for 2 minutes)
+ *   - others: marked as "not exposed by CLI"
  */
 import type { Command } from 'commander';
 import type { AgentId } from '../lib/types.js';

package/dist/commands/usage.js

@@ -2,14 +2,7 @@ import { addHostOption } from '../lib/hosts/option.js';
 import chalk from 'chalk';
 import { ALL_AGENT_IDS, AGENTS, getAccountInfo, agentLabel, resolveAgentName, formatAgentError, } from '../lib/agents.js';
 import { listInstalledVersions, getGlobalDefault, getVersionHomePath } from '../lib/versions.js';
-import { formatUsageSection, getUsageInfoForIdentity } from '../lib/usage.js';
-/**
- * Agents whose CLI surfaces usage data we can read today. Kept in sync with the
- * live/last-seen sources `getUsageInfo` dispatches on in `../lib/usage.js`
- * (claude, codex, kimi, droid) — an agent with a usage source but missing here
- * would wrongly print "does not publish usage data" for a signed-in account.
- */
-const USAGE_SUPPORTED = new Set(['claude', 'codex', 'kimi', 'droid']);
+import { agentReportsUsage, formatUsageSection, getUsageInfoForIdentity } from '../lib/usage.js';
 export function registerUsageCommand(program) {
     addHostOption(program.command('usage [agent]'))
         .description('Show rate-limit / quota usage per agent')
@@ -55,7 +48,7 @@ async function collectAgentUsage(agentId) {
     // Plain name — color is applied only at text-render time (formatAgentUsage), so
     // `--json` never emits ANSI escapes in `label` (e.g. under FORCE_COLOR=1).
     const label = AGENTS[agentId].name;
-    if (!USAGE_SUPPORTED.has(agentId)) {
+    if (!agentReportsUsage(agentId)) {
         return { agent: agentId, label, status: 'unsupported' };
     }
     const versions = listInstalledVersions(agentId);

package/dist/lib/agents.d.ts

@@ -165,7 +165,7 @@ export declare function formatClaudeOrgLabel(orgType: string | null | undefined)
  */
 export declare function accountOrgBadge(info?: Pick<AccountInfo, 'organizationType' | 'organizationName'> | null): string | null;
 /** Agents whose local credential formats expose enough state for account selection. */
-export declare const ACCOUNT_INSPECTION_AGENT_IDS: readonly ["claude", "codex", "gemini", "grok", "antigravity", "kimi", "droid", "opencode"];
+export declare const ACCOUNT_INSPECTION_AGENT_IDS: readonly ["claude", "codex", "gemini", "cursor", "grok", "antigravity", "kimi", "droid", "opencode"];
 /** Whether agents-cli can determine this agent's per-version sign-in state. */
 export declare function supportsAccountInspection(agentId: AgentId): boolean;
 /**
@@ -176,6 +176,36 @@ export declare function supportsAccountInspection(agentId: AgentId): boolean;
 export declare function accountDisplayLabel(info?: Pick<AccountInfo, 'email' | 'accountId' | 'signedIn' | 'organizationType' | 'organizationName'> | null): string;
 /** Return the email address associated with the agent's auth config, or null. */
 export declare function getAccountEmail(agentId: AgentId, home?: string): Promise<string | null>;
+/** Where an agent's credential file lives, split into the per-version copy and
+ *  the active/global copy under the real HOME. */
+export interface CredentialPresence {
+    /** The credential file exists inside the passed version home. */
+    perVersion: boolean;
+    /** The credential file exists under the active/global HOME (the one the login
+     *  symlink actually targets), independent of the version home. */
+    active: boolean;
+    /** Whether agents-cli knows WHERE this agent's credential lives at all — i.e.
+     *  the agent has an entry in {@link CREDENTIAL_FILE_SEGMENTS}. When false both
+     *  probes are trivially false because there is nothing to look for, so absence
+     *  is NOT evidence of a logout and no caller may treat it as provable.
+     *
+     *  This is deliberately separate from `supportsAccountInspection`: the two
+     *  registries move independently, and an agent has already been added to the
+     *  inspection set without a credential path (cursor), which without this flag
+     *  produced a false "logged out" critical for every installed version. */
+    knownLocation: boolean;
+}
+/**
+ * File-presence probe for an agent's credential, split by location: whether it
+ * exists in a SPECIFIC version home (`perVersion`) and whether it exists under
+ * the active/global HOME (`active`). A logged-out claim is only *provable* when
+ * BOTH are absent — a version that merely lacks its own copy but shares the
+ * global login is signed in, not logged out. Pure file existence; no decrypt,
+ * no network, no keychain prompt. Agents with no inspectable identity return
+ * `{ perVersion: false, active: false }` and must NEVER yield a provable-logout
+ * claim (the caller gates on {@link supportsAccountInspection}).
+ */
+export declare function credentialPresence(agentId: AgentId, versionHome: string): CredentialPresence;
 /** Decrypted contents of Droid's auth.v2.file (subset we consume). */
 export interface DroidAuthPayload {
     access_token?: string;

package/dist/lib/agents.js

@@ -1014,6 +1014,7 @@ export const ACCOUNT_INSPECTION_AGENT_IDS = [
     'claude',
     'codex',
     'gemini',
+    'cursor',
     'grok',
     'antigravity',
     'kimi',
@@ -1077,6 +1078,60 @@ function resolveAccountCredentialPath(base, ...segments) {
     }
     return null;
 }
+/**
+ * The on-disk credential file(s) each account-inspectable agent authenticates
+ * from, expressed as path segments under a home. Mirrors the exact files
+ * {@link getAccountInfo} reads, so a presence check here matches what a real
+ * launch would find. Each entry is a list of alternatives — the FIRST that
+ * exists counts as present (claude writes either `.claude/.claude.json` under
+ * the shimmed config dir or a home-level `.claude.json`). Agents whose login is
+ * stored only in the OS keychain on some platforms (antigravity, and claude's
+ * token) still expose a credential FILE — the presence of that file is the
+ * signal we key off; its absence on BOTH the per-version home and the active
+ * home is what makes a logged-out claim provable.
+ */
+const CREDENTIAL_FILE_SEGMENTS = {
+    claude: [['.claude', '.claude.json'], ['.claude.json']],
+    codex: [['.codex', 'auth.json']],
+    gemini: [['.gemini', 'google_accounts.json']],
+    grok: [['.grok', 'auth.json']],
+    kimi: [['.kimi-code', 'credentials', 'kimi-code.json']],
+    droid: [['.factory', 'auth.v2.file']],
+    antigravity: [['.gemini', 'antigravity-cli', 'antigravity-oauth-token']],
+    opencode: [['.local', 'share', 'opencode', 'auth.json']],
+};
+/** Whether an agent's credential file exists under a given home. */
+function credentialFileExistsUnder(agentId, home) {
+    const alternatives = CREDENTIAL_FILE_SEGMENTS[agentId];
+    if (!alternatives)
+        return false;
+    for (const segments of alternatives) {
+        const p = path.join(home, ...segments);
+        try {
+            if (fs.existsSync(p))
+                return true;
+        }
+        catch { /* unreadable */ }
+    }
+    return false;
+}
+/**
+ * File-presence probe for an agent's credential, split by location: whether it
+ * exists in a SPECIFIC version home (`perVersion`) and whether it exists under
+ * the active/global HOME (`active`). A logged-out claim is only *provable* when
+ * BOTH are absent — a version that merely lacks its own copy but shares the
+ * global login is signed in, not logged out. Pure file existence; no decrypt,
+ * no network, no keychain prompt. Agents with no inspectable identity return
+ * `{ perVersion: false, active: false }` and must NEVER yield a provable-logout
+ * claim (the caller gates on {@link supportsAccountInspection}).
+ */
+export function credentialPresence(agentId, versionHome) {
+    const realHome = process.env.AGENTS_REAL_HOME || os.homedir();
+    const perVersion = credentialFileExistsUnder(agentId, versionHome);
+    const active = credentialFileExistsUnder(agentId, realHome);
+    const knownLocation = (CREDENTIAL_FILE_SEGMENTS[agentId]?.length ?? 0) > 0;
+    return { perVersion, active, knownLocation };
+}
 /**
  * Factory Droid stores its OAuth credential encrypted at ~/.factory/auth.v2.file
  * (AES-256-GCM, format `ivB64:tagB64:ctB64`) with the 32-byte key base64-stored

package/dist/lib/command-skills.d.ts

@@ -4,6 +4,16 @@
  */
 import type { AgentId } from './types.js';
 export declare function shouldInstallCommandAsSkill(agent: AgentId, version: string): boolean;
+/**
+ * Agents whose native command files serve a separate surface while their CLI
+ * consumes the generated skill form. Keep this registry distinct from
+ * `shouldInstallCommandAsSkill`: these targets need both writes, not a format
+ * replacement.
+ */
+export declare const COMMAND_SKILL_DUAL_WRITE_TARGETS: {
+    cursor: true;
+};
+export declare function shouldAlsoInstallCommandAsSkill(agent: AgentId, version: string): boolean;
 export declare function commandSkillName(commandName: string): string;
 export declare function buildCommandSkillContent(commandName: string, sourcePath: string): string;
 export declare function skillSourceExists(skillName: string, skillSourceDirs: Array<string | null | undefined>): boolean;

package/dist/lib/command-skills.js

@@ -52,6 +52,20 @@ function readSkillCommandMarker(skillMdPath) {
 export function shouldInstallCommandAsSkill(agent, version) {
     return !supports(agent, 'commands', version).ok && supports(agent, 'skills', version).ok;
 }
+/**
+ * Agents whose native command files serve a separate surface while their CLI
+ * consumes the generated skill form. Keep this registry distinct from
+ * `shouldInstallCommandAsSkill`: these targets need both writes, not a format
+ * replacement.
+ */
+export const COMMAND_SKILL_DUAL_WRITE_TARGETS = {
+    cursor: true,
+};
+export function shouldAlsoInstallCommandAsSkill(agent, version) {
+    return COMMAND_SKILL_DUAL_WRITE_TARGETS[agent] === true
+        && supports(agent, 'commands', version).ok
+        && supports(agent, 'skills', version).ok;
+}
 export function commandSkillName(commandName) {
     return commandName;
 }

package/dist/lib/commands.js

@@ -15,7 +15,7 @@ import { markdownToToml } from './convert.js';
 import { getCommandsDir, getUserCommandsDir, getEnabledExtraRepos, getProjectAgentsDir, getSkillsDir, getTrashCommandsDir } from './state.js';
 import { getEffectiveHome, getVersionHomePath, listInstalledVersions, resolveVersion } from './versions.js';
 import { discoverPlugins } from './plugins.js';
-import { commandSkillMatches, installCommandSkillToVersion, listCommandSkillsInVersion, removeCommandSkillFromVersion, shouldInstallCommandAsSkill, } from './command-skills.js';
+import { commandSkillMatches, installCommandSkillToVersion, listCommandSkillsInVersion, removeCommandSkillFromVersion, shouldAlsoInstallCommandAsSkill, shouldInstallCommandAsSkill, } from './command-skills.js';
 import { installGooseCommandToVersion, listGooseCommandsInVersion, gooseCommandMatches, removeGooseCommandFromVersion, } from './goose-commands.js';
 function compareVersions(a, b) {
     const aParts = a.split('.').map((n) => parseInt(n, 10) || 0);
@@ -211,6 +211,14 @@ export function installCommand(sourcePath, agentId, commandName, method = 'symli
     const agent = AGENTS[agentId];
     ensureCommandsDir(agentId);
     const home = getEffectiveHome(agentId);
+    const installVersion = pinnedVersion ?? listInstalledVersions(agentId)[0] ?? '';
+    const alsoInstallAsSkill = shouldAlsoInstallCommandAsSkill(agentId, installVersion);
+    if (alsoInstallAsSkill) {
+        const installed = installCommandSkillToVersion(path.join(home, agentConfigDirName(agentId)), commandName, sourcePath, [getSkillsDir(), ...getEnabledExtraRepos().map((repo) => path.join(repo.dir, 'skills'))]);
+        if (!installed.success) {
+            return { path: '', method: 'copy', error: installed.error, warnings: validation.warnings };
+        }
+    }
     // Goose: a slash command is a recipe YAML registered in config.yaml, not a
     // native command file under commandsSubdir.
     if (agentId === 'goose') {
@@ -401,6 +409,11 @@ export function installCommandToVersion(agent, version, commandName, method = 'c
             ...getEnabledExtraRepos().map((repo) => path.join(repo.dir, 'skills')),
         ]);
     }
+    if (shouldAlsoInstallCommandAsSkill(agent, version)) {
+        const installed = installCommandSkillToVersion(agentDir, commandName, sourcePath, [getSkillsDir(), ...getEnabledExtraRepos().map((repo) => path.join(repo.dir, 'skills'))]);
+        if (!installed.success)
+            return installed;
+    }
     // Goose: a slash command is a recipe YAML registered in config.yaml, not a
     // native command file. Write the recipe + slash_commands entry.
     if (agent === 'goose') {
@@ -441,6 +454,11 @@ export function removeCommandFromVersion(agent, version, commandName) {
     if (shouldInstallCommandAsSkill(agent, version)) {
         return removeCommandSkillFromVersion(agentDir, commandName);
     }
+    if (shouldAlsoInstallCommandAsSkill(agent, version)) {
+        const removed = removeCommandSkillFromVersion(agentDir, commandName);
+        if (!removed.success)
+            return removed;
+    }
     if (agent === 'goose') {
         const trashDir = path.join(getTrashCommandsDir(), agent, version, commandName);
         return removeGooseCommandFromVersion(versionHome, commandName, trashDir);

package/dist/lib/daemon.js

@@ -880,7 +880,7 @@ ${[launch.command, ...launch.args].map((arg) => `    <string>${xmlEscape(arg)}</
   <key>EnvironmentVariables</key>
   <dict>
     <key>PATH</key>
-    <string>${daemonNodeBinDir()}:/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin:${os.homedir()}/.bun/bin</string>
+    <string>${daemonPathValue(agentsBin, ['/usr/local/bin', '/usr/bin', '/bin', '/opt/homebrew/bin', `${os.homedir()}/.bun/bin`])}</string>
   </dict>
 </dict>
 </plist>`;
@@ -909,7 +909,7 @@ Type=simple
 ExecStart=${execStart}
 Restart=always
 RestartSec=10
-Environment=PATH=${daemonNodeBinDir()}:/usr/local/bin:/usr/bin:/bin
+Environment=PATH=${daemonPathValue(agentsBin, ['/usr/local/bin', '/usr/bin', '/bin'])}
 
 [Install]
 WantedBy=default.target`;
@@ -1074,6 +1074,21 @@ export function getDaemonLaunch(agentsBin = getAgentsBinPath()) {
 function daemonNodeBinDir() {
     return path.dirname(process.execPath);
 }
+/**
+ * The full PATH value the daemon service manifest pins, in order: the Node runtime
+ * dir (so the shim's shebang and any child resolve the exact installing Node — see
+ * {@link daemonNodeBinDir}), then the directory of the `agents` shim itself, then
+ * the platform's system dirs. The shim's own dir matters because a scheduled
+ * `command` routine shells out to the bare name `agents`
+ * (`/bin/sh -c 'agents watchdog --nudge'`): when the shim lives outside the Node
+ * bin dir — a `~/.local/bin` global install, a separate npm prefix — a PATH
+ * carrying only the Node dir resolves `agents` to nothing and every routine dies
+ * with `exit 127`. Deduped across the whole list, so a Node/shim dir that already
+ * appears among the system dirs (e.g. a `/usr/local/bin` install) never doubles.
+ */
+function daemonPathValue(agentsBin, systemDirs) {
+    return [...new Set([daemonNodeBinDir(), path.dirname(agentsBin), ...systemDirs])].join(':');
+}
 /**
  * Build the argv to relaunch the `agents` CLI with the given subcommand args.
  *

package/dist/lib/devices/doctor-findings.d.ts

@@ -0,0 +1,167 @@
+import type { AgentId } from '../types.js';
+import type { DuplicateVersionHook } from '../hooks.js';
+import type { RcSecretFinding } from '../secrets/rc-hygiene.js';
+import type { SyncStatusRow, OrphanRow } from '../drift.js';
+import type { FetchStatusMarker } from '../auto-pull.js';
+import type { VersionResourceReport } from '../doctor-diff.js';
+import type { FleetDivergence, FleetVersionSignIn } from './fleet-divergence.js';
+export type FindingSeverity = 'critical' | 'warning';
+/** A machine-stable class for a finding — drives {@link remediationFor} and lets
+ *  the JSON consumer group by kind. */
+export declare const ALL_FINDING_KINDS: readonly ["logged-out", "logout-unprovable", "missing-hook", "missing-plugin", "unwired-hook", "cli-missing", "missing-resource", "content-drift", "never-synced", "stale", "repo-behind", "repo-drift", "fleet-resource-gap", "host-cli-missing", "host-cli-invalid", "version-skew", "orphan", "duplicate-hook", "duplicate-hook-drift", "rc-secret-export", "exec-policy", "stale-cli"];
+/** A machine-stable class for a finding. Derived from the runtime list above so
+ *  the rubric test can enumerate every kind. */
+export type FindingKind = typeof ALL_FINDING_KINDS[number];
+/** One prioritized finding, attributed to a device (and, when relevant, an agent
+ *  version + account). `remediation` is the exact command/hint to fix it. */
+export interface DoctorFinding {
+    severity: FindingSeverity;
+    kind: FindingKind;
+    /** The device this finding is about. */
+    device: string;
+    /** Agent id, when the finding is about a specific agent (else undefined). */
+    agent?: AgentId;
+    /** Version id, when about a specific installed version. Absent on a finding
+     *  collapsed across versions — read {@link DoctorFinding.versions} instead. */
+    version?: string;
+    /** Set only on a finding collapsed across several versions of one agent (the
+     *  same problem on each). The row renders `<agent> (N versions)` and the
+     *  remediation widens to the agent-wide sweep. */
+    versions?: string[];
+    /** Human account label (email/org/opaque id), when known. */
+    account?: string | null;
+    /** One-line plain-English description of the problem. */
+    message: string;
+    /** Exact remediation command / hint. */
+    remediation: string;
+}
+/**
+ * The exact remediation for a finding. Login fixes are harness-native
+ * (`loginHint`); a per-version login is offered ONLY for agents that isolate the
+ * credential per home (`agents run <agent>@<version>` then log in) — for
+ * gemini/antigravity/droid/cursor the login is shared, so we say so instead of
+ * faking a per-version fix. Every other kind maps to its canonical command.
+ */
+export declare function remediationFor(finding: DoctorFinding): string;
+export interface LocalFindingInputs {
+    device: string;
+    syncRows: SyncStatusRow[];
+    orphanRows: OrphanRow[];
+    repoBehind: FetchStatusMarker[];
+    /** Per-version resource reports (one per installed version) — the source of the
+     *  missing-hook / missing-plugin / missing-resource / content-drift / unwired
+     *  criticals+warnings. */
+    reports: VersionResourceReport[];
+    /** Per-version sign-in per agent id. */
+    signIn: Record<string, FleetVersionSignIn[]>;
+    /** Managed agents (installed versions) whose binary won't resolve. */
+    cliMissing?: AgentId[];
+    /** Host CLIs declared in a DotAgents repo's `cli/`: their install state on this
+     *  box, plus any manifest the loader could not parse. Host-global (installed to
+     *  PATH, never synced into a version home), so they are a machine-level
+     *  finding, not a per-version one. */
+    hostClis?: {
+        statuses: Array<{
+            name: string;
+            installed: boolean;
+        }>;
+        errors: Array<{
+            file: string;
+            reason: string;
+        }>;
+    };
+    /** Hooks materialized into several version homes at once — identical copies are
+     *  installation noise, differing ones are drift a stale gate can act on. */
+    duplicateHooks?: DuplicateVersionHook[];
+    /** Credential-shaped exports found in the user's shell rc files (RUSH-1968). */
+    rcSecrets?: RcSecretFinding[];
+    /** The effective PowerShell execution policy and the platform it was read on.
+     *  Only `win32` yields a finding — the `agents.ps1` launcher is Windows-only. */
+    execPolicy?: {
+        platform: NodeJS.Platform;
+        policy: string | null;
+    };
+    /** `<agent>@<version>` keys whose home is an isolated copy. Their findings are
+     *  never collapsed across versions: the agent-wide `agents doctor <agent> --fix`
+     *  sweep deliberately skips isolated copies, so a collapsed row would print a
+     *  remediation that does not fix them. */
+    isolatedVersions?: string[];
+}
+/**
+ * Fold this machine's signals into findings. Missing hooks/plugins and unwired
+ * hooks are CRITICAL; provable logouts are CRITICAL and unprovable ones WARNING;
+ * everything else (other missing kinds, drift, stale/never-synced, repo-behind,
+ * orphans) is a WARNING. Pure.
+ */
+export declare function buildLocalFindings(input: LocalFindingInputs): DoctorFinding[];
+/**
+ * Fold findings that say the SAME thing about several versions of one agent into
+ * a single row carrying `versions`, and widen its remediation to the agent-wide
+ * sweep (`agents doctor claude --fix` heals every non-isolated version in one
+ * go). Five identical `plugin 'code' — mirror missing` rows, one per installed
+ * claude, is the same fact five times.
+ *
+ * Three things never merge, because for each of them the widened remediation
+ * would be wrong:
+ *  - **Isolated copies** — the agent-wide sweep deliberately skips them
+ *    (`runFix`), so a folded row would print a command that leaves one broken.
+ *  - **Findings with no agent** (repo-behind, rc-secret-export, …) — their
+ *    `version` field is an alias, not a version.
+ *  - **Logouts** ({@link NEVER_COLLAPSED}) — a login is inherently per-version:
+ *    the fix is `agents run <agent>@<version> -- login`, and there is no `@all`
+ *    equivalent. Dropping `version` would fall back to the bare native hint,
+ *    which the shim resolves to the DEFAULT version — logging into the wrong one
+ *    and leaving the finding to reappear.
+ *
+ * Pure; input order is kept.
+ */
+export declare function collapseAcrossVersions(findings: DoctorFinding[], isolated: Set<string>): DoctorFinding[];
+/**
+ * Map a device's per-version sign-in into logout findings: a PROVABLE logout is
+ * CRITICAL, an unprovable one is a hedged WARNING ("could not verify sign-in"),
+ * and a signed-in version yields nothing.
+ *
+ * An agent with no inspectable identity never appears at all — not even as the
+ * hedged warning: agents-cli knows no credential file for it, so "logged out" is
+ * unknowable and silence beats a false claim. Membership is
+ * `supportsAccountInspection` (`lib/agents.ts`) and is deliberately NOT listed
+ * here — agents move between the sets, and a copy of the list in prose becomes a
+ * lie the next time one does. Note the caller also requires
+ * `CredentialPresence.knownLocation`: the inspection set and the credential-path
+ * map move independently, so being inspectable is not on its own enough to call a
+ * logout provable. Pure.
+ */
+export declare function signInToFindings(device: string, signIn: Record<string, FleetVersionSignIn[]>): DoctorFinding[];
+/**
+ * Map cross-device divergence (from {@link compareFleetInventories}) into
+ * warnings: an agent version present elsewhere but absent on a device is a
+ * version-skew warning; a diverged config repo is a repo-drift warning; a
+ * missing resource is a missing-resource warning. Baseline = the local machine.
+ * Only the *lagging* box is attributed (a `*-missing-local` finding is the
+ * baseline's gap). Pure.
+ */
+export declare function fleetDivergenceToFindings(divergences: FleetDivergence[], baseline: string): DoctorFinding[];
+export interface RenderOptions {
+    /** Fleet mode (`--devices`): render the `─── by computer ───` header + one
+     *  block per device. Single-machine mode collapses to one `▸ <machine>` block
+     *  with no fleet header. */
+    fleet: boolean;
+    /** The baseline (local) machine name — tagged `· this machine`. */
+    baseline?: string;
+    /** Header line context: device count (fleet) or the local version string. */
+    header?: string;
+}
+/**
+ * Render the two-part hybrid layout from a flat findings list. Pure — returns the
+ * lines so the exact output is snapshot-tested. Criticals across ALL devices go
+ * to the top section, worst-first; the per-computer section lists each device's
+ * warnings + a `✗ N critical (above)` marker, worst device first.
+ */
+export declare function renderFindings(findings: DoctorFinding[], accounts: Record<string, Record<string, FleetVersionSignIn[]>>, opts: RenderOptions): string[];
+/**
+ * The compact accounts/versions line for one device: every installed version and
+ * its account, grouped by agent — green ✓ signed in, red ✗ provably logged out,
+ * gray ? unknown (see {@link badge}). e.g.
+ *   `claude 2.1.170 ✓muqsit@gmail(Max) 2.1.999 ✓team(Team) · codex ✗ · grok ✓`
+ */
+export declare function renderAccountsLine(signIn: Record<string, FleetVersionSignIn[]>): string;