@phnx-labs/agents-cli 1.22.98 → 1.22.100

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 1.22.100
+
+- **The daemon's 20-minute auth-probe reuse works again on a box that has uninstalled a version (PHNX-4051).** `isCachedFleetAuthProbeFresh` required EVERY cached auth row to be under 20 minutes old, including rows left behind for versions that are no longer installed. Nothing re-probes those — the probe only walks homes that exist — so their timestamp froze and the check was permanently false: the 3-minute tick live-probed the rate-limited `/api/oauth/usage` for every account on every tick, re-arming the per-account 429 backoff and keeping the usage refresher parked (the RUSH-2998 failure the reuse window exists to prevent; observed on a worker holding rows dated Sep 2 / Sep 6 for uninstalled Claude versions). Freshness now considers only rows for currently installed `(agent, version)` homes and account slots, and the tick prunes the orphan rows when it writes the cache, so `agents view` and fleet status stop reporting a verdict for a version that is gone. `agents devices ping [--strict]` still forces a genuinely live probe. Source: `cli/src/lib/daemon-ticks.ts` (`installedAuthRows`, `isCachedFleetAuthProbeFresh`, `refreshLocalFleetAuthState`), `cli/src/lib/auth-health.ts` (`authTargetKey`, `enumerateLocalAuthInstalls`, `localAuthTargetKeys`, `writeFleetAuthRows`).
+
+- **Fleet usage-sync transport no longer starves `--device auto` (PHNX-4051).** The daemon's shared-state git exchange failed on every tick two ways, so workers never received a fresh Claude usage snapshot and the 40-min placement gate turned every worker into "no ready device". Fixed both at the source: (1) the usage-sync tick is now the single committer — it also publishes the reserved-auth verdict, and auth-sync no longer runs its own `syncFleetSharedStateRepo`, so the two ticks can't contend for the one shared-repo lock ("Lock file is already being held"); (2) the untracked-collision scan is scoped to the tracked roots origin carries (`git ls-tree origin/<branch>`) — every path origin tracks stays in scope, so no path the rebase can overwrite is missed, while an untracked-only tree origin never tracks (like artifacts-cli's `~/.agents/artifact-history/`) can never push `git ls-files --others` past the 1 MiB output cap. auth-sync's credential pushes are also gated on the exchange's freshness marker, so they never push off peer state older than one tick interval. Source: `cli/src/lib/fleet-shared-repo-sync.ts`, `cli/src/lib/daemon/usage-sync-service.ts`, `cli/src/lib/daemon/auth-sync-service.ts`.
+
+- **An untitled Arc Space no longer hides every Arc Space from `agents browser`.** `parseSidebarSpaces` treated the display-only Space title as part of a Space's identity and rejected the whole sidebar when one Space had none, so `agents browser start` warned that a configured `arc-gmail` "can't launch on this machine" while `agents browser profiles doctor arc-gmail` saw Arc and the Space. Identity is the stable Space id and its profile binding; a Space Arc stored without a title (key absent or `null`) is now listed as `arc-space` (two or more get their Space-id prefix appended, as same-titled Spaces already do). A mismatched id, a duplicate id, an unknown or malformed profile mapping, and a title that is present but not text still fail discovery closed. Source: `cli/src/lib/browser/arc-discovery.ts`, `cli/src/lib/browser/arc-discovery.test.ts`, `cli/src/lib/browser/testdata/arc/`.
+
+## 1.22.99
+
+- **`agents setup secrets` installs the published secrets CLI instead of only printing a hint (PHNX-3989).** A missing `secrets` binary tries `agents clis install secrets` then a pinned `npm i -g @phnx-labs/secrets-cli@0.1.2`, then hands off to `secrets migrate`. Docs point at the standalone engine; the broker is `secrets _agent-run` on macOS, not the agents daemon. Source: `cli/src/commands/setup-secrets.ts`, `cli/docs/secrets.md`.
+
+- `agents accounts list` / `agents view` no longer report a signed-in account slot as `MISSING`. A slot's STATE now comes from a live read of the slot's own credential and from the daemon's auth probe, which now covers account slots (`slot:<accountId>` rows) as well as version homes. Before, a slot's verdict was written only by `accounts add/login`, the daemon never re-derived it, and `signedIn` was read from an unrelated version home — so a slot re-materialized as `unconfigured` while the device doc was unreadable (a duplicate YAML key from a shared-repo autostash merge) stayed `MISSING` forever even though `agents run` used its login fine.
+
 ## 1.22.98
 
 - `agents run codex#<account>` on macOS now runs as that account. The SUN_LEN short-home relocation keyed `CODEX_HOME` by version alone, so an account slot (long enough to overflow too) was silently redirected to the default version's `~/.agents/.codex-homes/<version>/.codex` and its login — `agents run codex#getrush` opened the gmail session while the banner still said `getrush`. The short home is now keyed by the origin (`a-<account id>` for a slot). A version/account reinstall that recreates a fresh `.codex` adopts its existing short home (which holds the login) instead of failing, and a slot mis-linked onto a foreign home by the old layout is repointed to its own home rather than run as the wrong account.

package/README.md

@@ -1228,19 +1228,28 @@ replacement (`add` / `login` / `default` / `run <harness>#<name>`).
 
 ## Secrets
 
-> **Platform:** `agents secrets` requires macOS Keychain or Linux libsecret.
-> On Windows (non-WSL), use environment variables or a `.env` file instead.
+Secrets are the standalone **`secrets` CLI** (`@phnx-labs/secrets-cli`). agi-cli does not ship the engine. `agents secrets` is a passthrough to the same binary.
 
 ```bash
-# API keys in Keychain, not in .env files.
-agents secrets create prod-stripe
-agents secrets add prod-stripe STRIPE_SECRET_KEY     # Prompts, stores in Keychain
-agents secrets add prod-stripe TEST_CARD --value "4242..."
+# Install (pick one — no extra env vars)
+agents clis install secrets
+# or
+npm i -g @phnx-labs/secrets-cli@0.1.2
+# or, after agents is installed:
+agents setup secrets
+```
 
-# Injected at run time. Bundle definitions live in the Keychain, not on disk.
+```bash
+# API keys in Keychain, not in .env files.
+secrets create prod-stripe
+secrets add prod-stripe STRIPE_SECRET_KEY     # Prompts, stores in Keychain
 agents run claude "charge a test card" --secrets prod-stripe
 ```
 
+> **Platform:** macOS Keychain, Linux libsecret / file store. On Windows (non-WSL), use environment variables or a `.env` file instead.
+
+The macOS broker is **not** the agents daemon. It is `secrets _agent-run` (started by `secrets start` or on first unlock), socket under `$SECRETS_HOME/.cache/helpers/secrets-agent/` (`~/.agents` when you go through `agents secrets`). Linux has no broker. `agents daemon` never hosts it.
+
 <p align="center">
   <img src="assets/secrets.svg" alt="How agi-cli secrets work: bundle definitions live in the macOS Keychain alongside their values, agi-cli resolves at runtime and injects the env into the child process" width="100%" />
 </p>

package/dist/commands/setup-secrets.d.ts

@@ -1,22 +1,29 @@
 /**
- * `agents setup secrets` — install guidance for the standalone `secrets` CLI,
- * then a pass-through to its own `secrets migrate` onboarding (PHNX-3989).
+ * `agents setup secrets` — install the standalone `secrets` CLI if missing,
+ * then hand off to its own `secrets migrate` onboarding (PHNX-3989).
  *
- * The wizard that used to pick a default backend/policy and delegate imports
- * lived entirely against the in-repo secrets engine. That engine is extracted
- * to `@phnx-labs/secrets-cli`, which owns its own interactive onboarding
- * (`secrets migrate`) — agents-cli never rebundles it (DIST-1), so there is no
- * in-process fallback when it isn't installed: this command names the install
- * command and stops.
+ * The engine lives in `@phnx-labs/secrets-cli`. agents-cli never rebundles it
+ * (DIST-1). A missing binary is a routine install, not a fatal gap: try
+ * `agents clis install secrets` (system `clis/secrets.yaml`) then a pinned
+ * `npm i -g`. Users do not set extra env vars.
  */
 import type { Command } from 'commander';
+export declare const SECRETS_CLI_PACKAGE = "@phnx-labs/secrets-cli@0.1.2";
+export declare const INSTALL_HINT = "agents clis install secrets   # or: npm i -g @phnx-labs/secrets-cli@0.1.2";
 export declare function setupSecretsPrefsPath(): string;
 /** True when the standalone `secrets` executable resolves ($SECRETS_BIN or PATH). */
 export declare function isSecretsCliInstalled(): boolean;
 /**
- * Print install guidance when the standalone is missing, else hand off to its
- * own interactive `secrets migrate`. Returns whether setup is now complete
- * (installed, and — when it ran — `migrate` exited 0).
+ * Install the published secrets CLI. Prefers the host-CLI manifest
+ * (`clis/secrets.yaml` in the system repo) so doctor/clis stay one path.
+ * Falls back to a pinned npm global install. Returns whether `secrets` is
+ * on PATH afterwards. Never writes an `agents secrets` shim.
+ */
+export declare function installSecretsCli(): boolean;
+/**
+ * Install the standalone if missing, then hand off to `secrets migrate`.
+ * Returns whether setup is now complete (installed, and migrate exited 0
+ * when it ran).
  */
 export declare function runSecretsSetupWizard(): Promise<boolean>;
 /** Register `agents setup secrets` under the parent `setup` command. */

package/dist/commands/setup-secrets.js

@@ -1,21 +1,21 @@
 /**
- * `agents setup secrets` — install guidance for the standalone `secrets` CLI,
- * then a pass-through to its own `secrets migrate` onboarding (PHNX-3989).
+ * `agents setup secrets` — install the standalone `secrets` CLI if missing,
+ * then hand off to its own `secrets migrate` onboarding (PHNX-3989).
  *
- * The wizard that used to pick a default backend/policy and delegate imports
- * lived entirely against the in-repo secrets engine. That engine is extracted
- * to `@phnx-labs/secrets-cli`, which owns its own interactive onboarding
- * (`secrets migrate`) — agents-cli never rebundles it (DIST-1), so there is no
- * in-process fallback when it isn't installed: this command names the install
- * command and stops.
+ * The engine lives in `@phnx-labs/secrets-cli`. agents-cli never rebundles it
+ * (DIST-1). A missing binary is a routine install, not a fatal gap: try
+ * `agents clis install secrets` (system `clis/secrets.yaml`) then a pinned
+ * `npm i -g`. Users do not set extra env vars.
  */
 import chalk from 'chalk';
 import * as fs from 'fs';
 import * as path from 'path';
 import { spawnSync } from 'node:child_process';
 import { getHistoryDir } from '../lib/state.js';
-import { resolveSecretsBin, invocation, SecretsClientError } from '../lib/secrets-client.js';
-const INSTALL_HINT = 'npm i -g @phnx-labs/secrets-cli';
+import { resolveSecretsBin, invocation, SecretsClientError, _resetSecretsClientForTest } from '../lib/secrets-client.js';
+import { installCli, resolveCliManifest } from '../lib/cli-resources.js';
+export const SECRETS_CLI_PACKAGE = '@phnx-labs/secrets-cli@0.1.2';
+export const INSTALL_HINT = `agents clis install secrets   # or: npm i -g ${SECRETS_CLI_PACKAGE}`;
 export function setupSecretsPrefsPath() {
     return path.join(getHistoryDir(), 'setup', 'secrets.json');
 }
@@ -37,16 +37,48 @@ function recordSetupComplete() {
     fs.writeFileSync(file, JSON.stringify({ updatedAt: new Date().toISOString() }, null, 2) + '\n', { mode: 0o600 });
 }
 /**
- * Print install guidance when the standalone is missing, else hand off to its
- * own interactive `secrets migrate`. Returns whether setup is now complete
- * (installed, and — when it ran — `migrate` exited 0).
+ * Install the published secrets CLI. Prefers the host-CLI manifest
+ * (`clis/secrets.yaml` in the system repo) so doctor/clis stay one path.
+ * Falls back to a pinned npm global install. Returns whether `secrets` is
+ * on PATH afterwards. Never writes an `agents secrets` shim.
+ */
+export function installSecretsCli() {
+    if (isSecretsCliInstalled())
+        return true;
+    const manifest = resolveCliManifest('secrets');
+    if (manifest) {
+        console.log(chalk.gray(`Installing ${manifest.name} via agents clis…`));
+        const result = installCli(manifest);
+        _resetSecretsClientForTest();
+        if (result.installed)
+            return true;
+        if (result.error)
+            console.error(chalk.gray(result.error));
+    }
+    console.log(chalk.gray(`Installing ${SECRETS_CLI_PACKAGE}…`));
+    const r = spawnSync('npm', ['install', '-g', SECRETS_CLI_PACKAGE], { stdio: 'inherit' });
+    _resetSecretsClientForTest();
+    if (r.error) {
+        console.error(chalk.red(`npm install failed: ${r.error.message}`));
+        return false;
+    }
+    if ((r.status ?? 1) !== 0)
+        return false;
+    return isSecretsCliInstalled();
+}
+/**
+ * Install the standalone if missing, then hand off to `secrets migrate`.
+ * Returns whether setup is now complete (installed, and migrate exited 0
+ * when it ran).
  */
 export async function runSecretsSetupWizard() {
     if (!isSecretsCliInstalled()) {
-        console.log(chalk.yellow('The standalone `secrets` CLI is not installed.'));
-        console.log(chalk.gray('Install it, then re-run `agents setup secrets`:'));
-        console.log(chalk.cyan(`  ${INSTALL_HINT}`));
-        return false;
+        if (!installSecretsCli()) {
+            console.log(chalk.yellow('The standalone `secrets` CLI is not installed.'));
+            console.log(chalk.gray('Install it, then re-run `agents setup secrets`:'));
+            console.log(chalk.cyan(`  ${INSTALL_HINT}`));
+            return false;
+        }
     }
     const bin = resolveSecretsBin();
     const { command, prefix } = invocation(bin);
@@ -60,7 +92,7 @@ export async function runSecretsSetupWizard() {
 export function registerSetupSecretsCommand(setupCmd) {
     setupCmd
         .command('secrets')
-        .description('Install guidance for the standalone `secrets` CLI, then run its own `secrets migrate` onboarding.')
+        .description('Install the standalone `secrets` CLI if missing, then run its `secrets migrate` onboarding.')
         .action(async () => {
         if (!(await runSecretsSetupWizard()))
             process.exitCode = 1;

package/dist/lib/account-catalog.js

@@ -8,7 +8,7 @@ import { readSlots } from './accounts/slots.js';
 import { harnessWorkerIsPerDevice } from './harness-auth-capabilities.js';
 import { hasKeychainTokenSync, isSecretsTransportError } from './secrets-client.js';
 import { isLaunchableSignedIn as isCredentialLaunchable } from './accounting/rotate.js';
-import { authCacheKey, readAuthHealthCache } from './auth-health.js';
+import { authCacheKey, readAuthHealthCache, slotAuthVersionKey } from './auth-health.js';
 import { readFleetSharedDeviceStates } from './fleet-shared-state.js';
 import { machineId } from './machine-id.js';
 import { isHeadedDeviceRole, selfConfiguredDeviceRole } from './device-config.js';
@@ -245,9 +245,21 @@ export async function loadAccountCatalog() {
         const localHome = row.installations.find((home) => home.label === row.home)
             ?? row.installations.find((home) => home.signedIn)
             ?? row.installations[0];
-        const cached = localHome ? auth[authCacheKey(host, row.agent, localHome.label)] : undefined;
         const slot = row.id ? localSlots[row.id] : undefined;
-        const observation = resolveLocalAccountObservation(slot, cached, localHome?.signedIn === true);
+        // A slot account's local truth is the SLOT — its own credential file and its
+        // own daemon probe row (keyed `slot:<id>`) — never the version home its label
+        // happens to match. Reading the version home here is what rendered a
+        // signed-in slot MISSING: the slot record held ensureSlot's `unconfigured`
+        // default, the daemon never probed the slot, and `signedIn` came from an
+        // unrelated home.
+        const slotSignedIn = slot
+            ? await getAccountInfo(row.agent, slot.slotDir)
+                .then((info) => isLaunchableSignedIn(row.agent, slot.slotDir, info))
+                .catch(() => false)
+            : false;
+        const cached = (slot && row.id ? auth[authCacheKey(host, row.agent, slotAuthVersionKey(row.id))] : undefined)
+            ?? (localHome ? auth[authCacheKey(host, row.agent, localHome.label)] : undefined);
+        const observation = resolveLocalAccountObservation(slot, cached, slot ? slotSignedIn : localHome?.signedIn === true);
         const local = {
             device: host,
             authMode: observation.authMode
@@ -529,8 +541,12 @@ export function listDevicesWithoutAccountVerdicts(userAgentsDir) {
     return out.sort((a, b) => a.localeCompare(b));
 }
 function normalizeAuthVerdict(verdict, signedIn) {
+    // `unconfigured` is the slot record's DEFAULT (ensureSlot), not a probe
+    // result — the daemon never publishes it (probeLocalFleetAuth drops those
+    // rows). So it says nothing about the credential on disk; the live signedIn
+    // read of the slot decides, exactly as it does when no verdict exists at all.
     if (verdict === 'unconfigured')
-        return 'missing';
+        return signedIn ? 'unverified' : 'missing';
     if (verdict === 'error')
         return signedIn ? 'unverified' : 'missing';
     return verdict ?? (signedIn ? 'unverified' : 'missing');

package/dist/lib/accounts/slots.d.ts

@@ -3,6 +3,25 @@ export type { DeviceAccountSlot };
 export declare function slotDir(harness: AgentId, accountId: string): string;
 export declare function readSlots(meta: Pick<Meta, 'deviceAccounts'>): Record<string, DeviceAccountSlot>;
 export declare function recordSlot(accountId: string, slot: DeviceAccountSlot): void;
+export interface SlotProjection {
+    accountId: string;
+    /** Account name as registered (`agents accounts list`). */
+    name: string;
+    slotDir: string;
+    /** The version home the slot was projected from. */
+    from: string;
+    /** `<kind>/<name>` artifacts removed because the source no longer has them. */
+    pruned: string[];
+}
+/**
+ * Re-project settings and resources into every account slot this device holds
+ * for `harness`, from the harness's default version home. `ensureSlot` does
+ * this once at `agents accounts add`; every reconcile calls this so a slot
+ * never lags the version home it was cloned from (PHNX-3940). Credentials are
+ * never touched: `carryForwardSettings` and the resource writers exclude them.
+ * A slot whose directory is gone is skipped, not recreated.
+ */
+export declare function projectAccountSlots(harness: AgentId): SlotProjection[];
 /**
  * Create the HOME-shaped slot dir and project settings/resources from the
  * managed install. Does not copy credentials (carryForwardSettings excludes

package/dist/lib/accounts/slots.js

@@ -17,7 +17,7 @@ import { agentConfigDirName } from '../agents.js';
 import { harnessAuth, harnessWorkerIsPerDevice } from '../harness-auth-capabilities.js';
 import { getGlobalDefault, getVersionHomePath, listInstalledVersions } from '../installations/store.js';
 import { carryForwardSettings } from '../settings-manifest.js';
-import { getHistoryDir, updateMeta } from '../state.js';
+import { getHistoryDir, readMeta, updateMeta } from '../state.js';
 import { ALL_RESOURCE_KINDS, getDetector, getWriter, kindToCapability } from '../staleness/registry.js';
 import { supports } from '../capabilities.js';
 import { isAgentId } from '../types.js';
@@ -72,6 +72,66 @@ function projectResources(harness, version, destHome, fromHome) {
         writer.write({ version, versionHome: destHome, selection: names, cwd });
     }
 }
+/**
+ * Remove slot artifacts whose source name is gone. Only the name-keyed kinds
+ * that implement `remove` (commands, skills, hooks) are pruned; wholesale kinds
+ * (rules, permissions) are rewritten by the projection itself.
+ */
+function pruneSlotResources(harness, version, slotHome, fromHome) {
+    const cwd = process.cwd();
+    const pruned = [];
+    for (const kind of ALL_RESOURCE_KINDS) {
+        if (!supports(harness, kindToCapability(kind), version).ok)
+            continue;
+        const writer = getWriter(kind, harness);
+        const detector = getDetector(kind, harness);
+        if (!writer?.remove || !detector)
+            continue;
+        const source = new Set(detector.list({ version, versionHome: fromHome, cwd }));
+        for (const name of detector.list({ version, versionHome: slotHome, cwd })) {
+            if (source.has(name))
+                continue;
+            if (writer.remove({ version, versionHome: slotHome, name, cwd }).removed)
+                pruned.push(`${kind}/${name}`);
+        }
+    }
+    return pruned;
+}
+/**
+ * Re-project settings and resources into every account slot this device holds
+ * for `harness`, from the harness's default version home. `ensureSlot` does
+ * this once at `agents accounts add`; every reconcile calls this so a slot
+ * never lags the version home it was cloned from (PHNX-3940). Credentials are
+ * never touched: `carryForwardSettings` and the resource writers exclude them.
+ * A slot whose directory is gone is skipped, not recreated.
+ */
+export function projectAccountSlots(harness) {
+    const version = sourceVersion(harness);
+    if (!version)
+        return [];
+    const fromHome = getVersionHomePath(harness, version);
+    if (!fs.existsSync(fromHome))
+        return [];
+    const meta = readMeta();
+    const slots = readSlots(meta);
+    const native = { ...meta.accounts?.native, ...meta.deviceAccounts?.native };
+    const projected = [];
+    for (const account of Object.values(native)) {
+        if (account.agent !== harness)
+            continue;
+        // The slot record is device-local and written after identity capture; a
+        // slot dir minted by an earlier build, or an add that stopped short of
+        // recording, is still the HOME an account run uses — project it too.
+        const dir = slots[account.id]?.slotDir ?? slotDir(harness, account.id);
+        if (!fs.existsSync(path.join(dir, agentConfigDirName(harness))))
+            continue;
+        carryForwardSettings(harness, fromHome, dir);
+        const pruned = pruneSlotResources(harness, version, dir, fromHome);
+        projectResources(harness, version, dir, fromHome);
+        projected.push({ accountId: account.id, name: account.name, slotDir: dir, from: version, pruned });
+    }
+    return projected;
+}
 /**
  * Create the HOME-shaped slot dir and project settings/resources from the
  * managed install. Does not copy credentials (carryForwardSettings excludes

package/dist/lib/auth-health.d.ts

@@ -1,5 +1,5 @@
 import { type AccountInfo } from './agents.js';
-import type { AgentId } from './types.js';
+import type { AgentId, Meta } from './types.js';
 import { type ProviderProbe } from './accounting/usage.js';
 /**
  * - `live`        — completed an authenticated request (200).
@@ -134,10 +134,66 @@ export declare function formatCheckedAge(checkedAt: number, now?: number): strin
 export declare function authAccountLabel(info: Pick<AccountInfo, 'email' | 'accountId' | 'userId'> | null | undefined): string | undefined;
 /** Cache key: one entry per install — (host, agent, version). Unique per token. */
 export declare function authCacheKey(host: string, agent: AgentId | string, version: string): string;
+/**
+ * Host-independent identity of one probe target — the (agent, version) pair
+ * {@link authCacheKey} is keyed by. The separator cannot appear in either half,
+ * so an agent id can never run into a version the way a `:` join allows.
+ */
+export declare function authTargetKey(agent: AgentId | string, version: string): string;
+/**
+ * The `version` slot an account SLOT occupies in the auth cache and the probe
+ * rows: `slot:<accountId>`. A slot is a HOME-shaped dir, not an installed
+ * version, so it needs its own key or its verdict would collide with (or be
+ * silently dropped in favor of) whichever version home the account's label
+ * happened to match.
+ */
+export declare function slotAuthVersionKey(accountId: string): string;
+/** One account slot on this device that the auth probe must cover. */
+export interface SlotAuthInstall extends FleetAuthInstall {
+    home: string;
+    accountId: string;
+}
+/**
+ * Every registered account's slot on this device (PHNX-3940 T1), as probe
+ * targets. Before this the probe walked `listInstalledVersions` only, so a
+ * slot's verdict was never re-derived after `accounts add/login` wrote it —
+ * a slot re-materialized as `unconfigured` while the device doc was unreadable
+ * stayed MISSING forever even though its login was live. A slot whose dir is
+ * gone is skipped: there is nothing to probe and the row would only say so.
+ */
+export declare function enumerateSlotInstalls(meta: Pick<Meta, 'accounts' | 'deviceAccounts'>, agentIds: readonly AgentId[]): SlotAuthInstall[];
+/** One probe target on this device: an installed version home, or an account slot. */
+export interface LocalAuthInstall extends FleetAuthInstall {
+    home: string;
+    accountId?: string;
+}
+/**
+ * Every (agent, version) home the local auth probe covers on this device —
+ * installed version homes plus account slots. {@link probeLocalFleetAuth} probes
+ * exactly this set, so it is also the answer to "which cached rows are still
+ * backed by something on disk" (PHNX-4051).
+ */
+export declare function enumerateLocalAuthInstalls(meta: Pick<Meta, 'accounts' | 'deviceAccounts'>, agentIds: readonly AgentId[]): LocalAuthInstall[];
+/**
+ * {@link authTargetKey} for every local probe target — what a cached row must
+ * match to still be about this device. A row outside it is an ORPHAN: its home
+ * was uninstalled, so nothing will ever re-probe it and its `checkedAt` is
+ * frozen at whatever the last probe left (PHNX-4051).
+ */
+export declare function localAuthTargetKeys(agentIds?: readonly AgentId[]): Set<string>;
 /** Read the whole cache (best-effort; a corrupt/missing file yields an empty map). */
 export declare function readAuthHealthCache(): Record<string, AuthHealth>;
 /** Read one entry, or null. */
 export declare function readAuthHealth(host: string, agent: AgentId | string, version: string): AuthHealth | null;
+/**
+ * Split a cache key back into the install it names, for one host. Returns null
+ * for a key that belongs to another host or does not name a known agent — the
+ * one place the `host:agent:version` join is undone.
+ */
+export declare function parseAuthCacheKey(key: string, host: string): {
+    agent: AgentId;
+    version: string;
+} | null;
 /** Reconstruct one host's published probe rows for a lease waiter/CLI reader. */
 export declare function readFleetAuthRows(host: string): AuthProbeRow[];
 /**
@@ -148,8 +204,15 @@ export declare function readFleetAuthRows(host: string): AuthProbeRow[];
  * behaviour promised by the `error` doc on AuthVerdict ("keep the last known
  * one"). Pure, so it's unit-tested directly. */
 export declare function mergeAuthHealthEntries(current: Record<string, AuthHealth>, incoming: Record<string, AuthHealth>): Record<string, AuthHealth>;
-/** Merge one or more entries into the cache (best-effort write). */
-export declare function writeAuthHealthEntries(entries: Record<string, AuthHealth>): void;
+/**
+ * Merge one or more entries into the cache (best-effort write).
+ *
+ * `drop` removes entries the writer knows are gone — it runs on the PRE-merge
+ * cache, so an incoming row always wins over a drop of the same key and the two
+ * can never fight. Only a writer that knows the full truth for the keys it drops
+ * may pass one (see {@link writeFleetAuthRows}).
+ */
+export declare function writeAuthHealthEntries(entries: Record<string, AuthHealth>, drop?: (key: string) => boolean): void;
 /**
  * Complete a live auth probe for one (agent, home). For claude/kimi/droid this
  * hits the provider — unless the account's usage cache already holds a fresh
@@ -239,5 +302,16 @@ export declare function probeLocalFleetAuth(opts?: {
      */
     signal?: AbortSignal;
 }): Promise<AuthProbeRow[]>;
-/** Persist a host's probed rows into the cache (keyed by host+agent+version). */
-export declare function writeFleetAuthRows(host: string, rows: AuthProbeRow[]): void;
+/**
+ * Persist a host's probed rows into the cache (keyed by host+agent+version).
+ *
+ * `installed` — the {@link authTargetKey} set of homes that still exist on
+ * `host` ({@link localAuthTargetKeys}) — prunes this host's ORPHAN entries: rows
+ * for a version that has since been uninstalled. Nothing re-probes those, so
+ * they never age out on their own; they froze the reuse window permanently false
+ * and kept surfacing in `agents view` / fleet status (PHNX-4051). Only a caller
+ * that enumerated `host`'s real installs may pass it — the `fleet ping` fan-out
+ * writes a PEER's rows and cannot enumerate that box's homes, so it omits it and
+ * merges as before.
+ */
+export declare function writeFleetAuthRows(host: string, rows: AuthProbeRow[], installed?: ReadonlySet<string>): void;