@phnx-labs/agents-cli 1.22.43 → 1.22.45

package/dist/lib/analytics/mix-commands.js

@@ -7,9 +7,8 @@
  * usage.db) still exists — it is now `agents insights mix` and the recipe
  * subcommands below. Latency stays on `agents perf`; quota on `agents usage`.
  *
- * `agents trends` remains a thin deprecated alias registered from
- * `commands/trends.ts` that shares this same registration — no second copy of
- * the recipe tree.
+ * Former top-level `agents trends` is gone. The nested spelling
+ * `agents insights trends` is an alias of `agents insights mix`.
  */
 import chalk from 'chalk';
 import { setHelpSections } from '../help.js';
@@ -56,33 +55,24 @@ export function renderMixDashboard(days, asJson, bannerLabel = 'agents insights
     for (const section of dash.sections)
         printMixSection(section);
 }
-/** One-line deprecation for the retired top-level `agents trends` spelling. */
-export function printTrendsDeprecation() {
-    console.error(chalk.yellow('agents trends is deprecated — use `agents insights mix` (or `agents insights <recipe>`).'));
-}
 /**
- * Attach counter-mix subcommands to a parent (typically `insights` or the
- * deprecated `trends` alias).
+ * Attach counter-mix subcommands to a parent (typically `insights`).
  *
  * Layout:
- *   <parent> mix                 multi-recipe board (default for trends alias)
+ *   <parent> mix                 multi-recipe board
+ *   <parent> trends              alias of mix (former top-level `agents trends`)
  *   <parent> recipes             list recipe ids
  *   <parent> query               raw usage.db rows
  *   <parent> harness-mix|…       one baked recipe
  */
-export function registerMixCommands(parent, opts = {}) {
-    const before = () => {
-        if (opts.deprecated)
-            printTrendsDeprecation();
-    };
-    const banner = opts.dashboardBanner ?? 'agents insights mix';
+export function registerMixCommands(parent) {
+    const banner = 'agents insights mix';
     const mix = parent
         .command('mix')
         .description('Counter recipes — harness/model mix, token ratios, resource frequency (sessions index + usage.db)')
         .option('--days <n>', 'Days of history to include', '7')
         .option('--json', 'Emit JSON instead of tables')
         .action(function summary() {
-        before();
         const o = this.opts();
         renderMixDashboard(parseMixDays(o.days), Boolean(o.json), banner);
     });
@@ -115,7 +105,6 @@ export function registerMixCommands(parent, opts = {}) {
         .description('List baked mix-recipe ids')
         .option('--json', 'Emit JSON')
         .action((o) => {
-        before();
         const list = listRecipes();
         if (o.json) {
             console.log(JSON.stringify(list, null, 2));
@@ -134,7 +123,6 @@ export function registerMixCommands(parent, opts = {}) {
         .option('--limit <n>', 'Max rows', '40')
         .option('--json', 'Emit JSON')
         .action((o) => {
-        before();
         const win = analyticsWindow(parseMixDays(o.days));
         const kind = o.kind && USAGE_KINDS.includes(o.kind)
             ? o.kind
@@ -177,7 +165,6 @@ export function registerMixCommands(parent, opts = {}) {
             .option('--days <n>', 'Days of history', '7')
             .option('--json', 'Emit JSON')
             .action(function recipeAction() {
-            before();
             const parentOpts = this.parent?.opts?.();
             const o = { ...parentOpts, ...this.opts() };
             const win = analyticsWindow(parseMixDays(o.days));
@@ -193,37 +180,24 @@ export function registerMixCommands(parent, opts = {}) {
             printMixSection(section);
         });
     }
-}
-/**
- * Thin top-level `agents trends` alias: same mix tree, deprecation on every path,
- * default action = mix board (old `agents trends` with no subcommand).
- */
-export function registerDeprecatedTrendsAlias(program) {
-    const trends = program
+    // Nested home for the former top-level `agents trends` spelling.
+    const trends = parent
         .command('trends')
-        .description('Deprecated alias of `agents insights mix` — counter recipes over sessions + usage.db')
+        .description('Alias of `mix` — former top-level `agents trends`')
         .option('--days <n>', 'Days of history to include', '7')
         .option('--json', 'Emit JSON instead of tables')
         .action(function summary() {
-        printTrendsDeprecation();
         const o = this.opts();
-        renderMixDashboard(parseMixDays(o.days), Boolean(o.json), 'agents insights mix');
+        renderMixDashboard(parseMixDays(o.days), Boolean(o.json), banner);
     });
     setHelpSections(trends, {
         examples: `
-      # Prefer the canonical spelling
+      agents insights trends
       agents insights mix
-
-      # Still works (prints a deprecation line)
-      agents trends
-      agents trends harness-mix --json
     `,
         notes: `
-      \`agents trends\` is a compatibility alias. New code and agent briefs should use
-      \`agents insights mix\` / \`agents insights <recipe>\`. Behavioural report remains
-      bare \`agents insights\`. Latency remains \`agents perf\`.
+      \`agents insights trends\` is the nested spelling of the former top-level
+      \`agents trends\`. Prefer \`agents insights mix\`.
     `,
     });
-    // Same subcommands as insights, with deprecation on every fire.
-    registerMixCommands(trends, { deprecated: true, dashboardBanner: 'agents insights mix' });
 }

package/dist/lib/audit/log.d.ts

@@ -6,7 +6,7 @@
  * NOT append there. Operators list run outcomes with:
  *
  *   agents events --include runs
- *   agents audit                 # alias of the above
+ *   agents events audit          # nested alias of the above
  */
 /** First record's `prevHash` — a fixed anchor so the chain has a root. */
 export declare const GENESIS_HASH = "GENESIS";
@@ -59,7 +59,7 @@ export declare function verifyAuditChain(logPath?: string): {
     ok: boolean;
     brokenAt?: number;
 };
-/** Read the whole chain, oldest-first. Exposed for `agents audit list`. */
+/** Read the whole chain, oldest-first. Exposed for `agents events audit verify`. */
 export declare function readAuditLog(logPath?: string): AuditRecord[];
 /**
  * Record ONE dispatched run at the single exec chokepoint into the unified

package/dist/lib/audit/log.js

@@ -6,7 +6,7 @@
  * NOT append there. Operators list run outcomes with:
  *
  *   agents events --include runs
- *   agents audit                 # alias of the above
+ *   agents events audit          # nested alias of the above
  */
 import * as fs from 'fs';
 import * as path from 'path';
@@ -116,7 +116,7 @@ export function verifyAuditChain(logPath = getAuditLogPath()) {
     }
     return { ok: true };
 }
-/** Read the whole chain, oldest-first. Exposed for `agents audit list`. */
+/** Read the whole chain, oldest-first. Exposed for `agents events audit verify`. */
 export function readAuditLog(logPath = getAuditLogPath()) {
     return readRecords(logPath);
 }

package/dist/lib/beta.js

@@ -86,5 +86,5 @@ export function setBetaEnabled(features, enabled) {
     return { ...location, enabledFeatures };
 }
 export function betaEnableHint(feature) {
-    return `Enable it with: agents beta enable ${feature}`;
+    return `Enable it with: agents setup beta enable ${feature}`;
 }

package/dist/lib/browser/domain-skills.d.ts

@@ -2,7 +2,9 @@
  * Domain-skill discovery for `agents browser start`.
  *
  * When a browser task opens a URL, look up a site-specific SKILL.md from
- * `~/.agents/skills/browser/domain-skills/<dir>/SKILL.md` and surface its
+ * `skills/browser/domain-skills/<dir>/SKILL.md` in the layered DotAgents
+ * repos — project > user > system, first layer with a match wins, the same
+ * precedence `resolveResource` in `../resources.ts` applies — and surface its
  * contents so the calling agent gets per-site operating instructions
  * (selectors, gotchas, sign-in quirks) before it starts driving the page.
  *
@@ -24,8 +26,21 @@ export interface ResolvedDomainSkill {
     /** Hostname the match was made against (post-www strip). */
     hostname: string;
 }
-/** Where domain-skills live. Override via $AGENTS_BROWSER_DOMAIN_SKILLS_DIR for tests. */
-export declare function domainSkillsRoot(): string;
+/**
+ * Where domain-skills live, in precedence order: project > user > system >
+ * extra repos — the same layering `resolveResource` applies. A layer whose
+ * root does not exist is simply skipped at resolve time.
+ *
+ * The project layer resolves from `cwd` (default `process.cwd()`). The
+ * browser daemon is shared and long-lived, and its IPC request does not yet
+ * carry the calling CLI's cwd, so at that call site the project layer follows
+ * the daemon's own cwd until the caller's cwd is threaded through
+ * (RUSH-2996); user/system/extra-repo layers are cwd-independent.
+ *
+ * $AGENTS_BROWSER_DOMAIN_SKILLS_DIR overrides the whole list with a single
+ * root, for tests.
+ */
+export declare function domainSkillsRoots(cwd?: string): string[];
 /**
  * Derive match candidates from a hostname. Order matters — earlier candidates
  * are tried first.
@@ -40,12 +55,17 @@ export declare function hostnameMatchCandidates(hostname: string): string[];
 /**
  * Resolve a URL to its matching domain-skill, or null if none.
  *
- * Two-pass strategy:
+ * Roots are searched in `domainSkillsRoots` order (project > user > system);
+ * the first layer with a match wins outright — an earlier layer's
+ * directory-name match beats a later layer's `domains:` pin, mirroring
+ * `resolveResource`'s layer precedence. Within one layer, two passes:
  *   1. Index every SKILL.md in the root and read its `domains:` frontmatter.
  *      If any pinned domain matches a candidate, return that skill.
  *   2. Fall back to directory-name match against the candidate list.
  *
  * Errors (missing root, unreadable file, invalid URL) are swallowed and
- * yield null — domain-skill discovery must never break browser start.
+ * yield null — domain-skill discovery must never break browser start. A miss
+ * logs the roots searched at debug level (AGENTS_DEBUG/DEBUG) so a skill
+ * sitting in an unsearched layer is diagnosable rather than silent.
  */
-export declare function resolveDomainSkill(url: string): ResolvedDomainSkill | null;
+export declare function resolveDomainSkill(url: string, cwd?: string): ResolvedDomainSkill | null;

package/dist/lib/browser/domain-skills.js

@@ -2,7 +2,9 @@
  * Domain-skill discovery for `agents browser start`.
  *
  * When a browser task opens a URL, look up a site-specific SKILL.md from
- * `~/.agents/skills/browser/domain-skills/<dir>/SKILL.md` and surface its
+ * `skills/browser/domain-skills/<dir>/SKILL.md` in the layered DotAgents
+ * repos — project > user > system, first layer with a match wins, the same
+ * precedence `resolveResource` in `../resources.ts` applies — and surface its
  * contents so the calling agent gets per-site operating instructions
  * (selectors, gotchas, sign-in quirks) before it starts driving the page.
  *
@@ -14,14 +16,37 @@
  * the directory-name match.
  */
 import * as fs from 'fs';
-import * as os from 'os';
 import * as path from 'path';
-/** Where domain-skills live. Override via $AGENTS_BROWSER_DOMAIN_SKILLS_DIR for tests. */
-export function domainSkillsRoot() {
+import { getEnabledExtraRepos, getProjectAgentsDir, getSystemAgentsDir, getUserAgentsDir, } from '../state.js';
+/**
+ * Where domain-skills live, in precedence order: project > user > system >
+ * extra repos — the same layering `resolveResource` applies. A layer whose
+ * root does not exist is simply skipped at resolve time.
+ *
+ * The project layer resolves from `cwd` (default `process.cwd()`). The
+ * browser daemon is shared and long-lived, and its IPC request does not yet
+ * carry the calling CLI's cwd, so at that call site the project layer follows
+ * the daemon's own cwd until the caller's cwd is threaded through
+ * (RUSH-2996); user/system/extra-repo layers are cwd-independent.
+ *
+ * $AGENTS_BROWSER_DOMAIN_SKILLS_DIR overrides the whole list with a single
+ * root, for tests.
+ */
+export function domainSkillsRoots(cwd) {
     const override = process.env.AGENTS_BROWSER_DOMAIN_SKILLS_DIR;
     if (override)
-        return override;
-    return path.join(os.homedir(), '.agents', 'skills', 'browser', 'domain-skills');
+        return [override];
+    const sub = ['skills', 'browser', 'domain-skills'];
+    const roots = [];
+    const projectDir = getProjectAgentsDir(cwd);
+    if (projectDir)
+        roots.push(path.join(projectDir, ...sub));
+    roots.push(path.join(getUserAgentsDir(), ...sub));
+    roots.push(path.join(getSystemAgentsDir(), ...sub));
+    for (const extra of getEnabledExtraRepos()) {
+        roots.push(path.join(extra.dir, ...sub));
+    }
+    return roots;
 }
 /**
  * Derive match candidates from a hostname. Order matters — earlier candidates
@@ -85,18 +110,28 @@ function parseDomainsFrontmatter(content) {
     }
     return [];
 }
+/** Stderr debug line, gated on AGENTS_DEBUG/DEBUG — same convention as `../teams/debug.ts`. */
+function debug(message) {
+    if (process.env.AGENTS_DEBUG || process.env.DEBUG)
+        console.error(message);
+}
 /**
  * Resolve a URL to its matching domain-skill, or null if none.
  *
- * Two-pass strategy:
+ * Roots are searched in `domainSkillsRoots` order (project > user > system);
+ * the first layer with a match wins outright — an earlier layer's
+ * directory-name match beats a later layer's `domains:` pin, mirroring
+ * `resolveResource`'s layer precedence. Within one layer, two passes:
  *   1. Index every SKILL.md in the root and read its `domains:` frontmatter.
  *      If any pinned domain matches a candidate, return that skill.
  *   2. Fall back to directory-name match against the candidate list.
  *
  * Errors (missing root, unreadable file, invalid URL) are swallowed and
- * yield null — domain-skill discovery must never break browser start.
+ * yield null — domain-skill discovery must never break browser start. A miss
+ * logs the roots searched at debug level (AGENTS_DEBUG/DEBUG) so a skill
+ * sitting in an unsearched layer is diagnosable rather than silent.
  */
-export function resolveDomainSkill(url) {
+export function resolveDomainSkill(url, cwd) {
     let hostname;
     try {
         hostname = new URL(url).hostname;
@@ -106,52 +141,55 @@ export function resolveDomainSkill(url) {
     }
     if (!hostname)
         return null;
-    const root = domainSkillsRoot();
-    let entries;
-    try {
-        entries = fs.readdirSync(root, { withFileTypes: true });
-    }
-    catch {
-        return null;
-    }
     const candidates = hostnameMatchCandidates(hostname);
     if (candidates.length === 0)
         return null;
     const candidateSet = new Set(candidates);
-    const indexed = [];
-    for (const e of entries) {
-        if (!e.isDirectory())
-            continue;
-        const skillPath = path.join(root, e.name, 'SKILL.md');
-        let content;
+    const roots = domainSkillsRoots(cwd);
+    for (const root of roots) {
+        let entries;
         try {
-            content = fs.readFileSync(skillPath, 'utf-8');
+            entries = fs.readdirSync(root, { withFileTypes: true });
         }
         catch {
             continue;
         }
-        indexed.push({
-            name: e.name,
-            skillPath,
-            content,
-            pinned: parseDomainsFrontmatter(content),
-        });
-    }
-    // Pass 1: explicit `domains:` overrides.
-    for (const s of indexed) {
-        for (const d of s.pinned) {
-            if (candidateSet.has(d)) {
-                return { name: s.name, path: s.skillPath, content: s.content, hostname };
+        const indexed = [];
+        for (const e of entries) {
+            if (!e.isDirectory())
+                continue;
+            const skillPath = path.join(root, e.name, 'SKILL.md');
+            let content;
+            try {
+                content = fs.readFileSync(skillPath, 'utf-8');
+            }
+            catch {
+                continue;
             }
+            indexed.push({
+                name: e.name,
+                skillPath,
+                content,
+                pinned: parseDomainsFrontmatter(content),
+            });
         }
-    }
-    // Pass 2: directory-name match, walking candidates in priority order.
-    const byName = new Map(indexed.map((s) => [s.name.toLowerCase(), s]));
-    for (const c of candidates) {
-        const hit = byName.get(c);
-        if (hit) {
-            return { name: hit.name, path: hit.skillPath, content: hit.content, hostname };
+        // Pass 1: explicit `domains:` overrides.
+        for (const s of indexed) {
+            for (const d of s.pinned) {
+                if (candidateSet.has(d)) {
+                    return { name: s.name, path: s.skillPath, content: s.content, hostname };
+                }
+            }
+        }
+        // Pass 2: directory-name match, walking candidates in priority order.
+        const byName = new Map(indexed.map((s) => [s.name.toLowerCase(), s]));
+        for (const c of candidates) {
+            const hit = byName.get(c);
+            if (hit) {
+                return { name: hit.name, path: hit.skillPath, content: hit.content, hostname };
+            }
         }
     }
+    debug(`[browser] no domain-skill for ${hostname}; searched: ${roots.join(', ')}`);
     return null;
 }

package/dist/lib/daemon/daemon.js

@@ -1868,6 +1868,17 @@ export function ensureDaemonStarted() {
     // callers that branch on this return (e.g. secrets/agent.ts).
     if (isDaemonRunning())
         return startDaemon();
+    // RUSH-3021: never LAUNCH a daemon from a redirected (sandbox/test) HOME.
+    // #2860 gated service-manager registration on this signal but left the
+    // detached spawn itself ungated, so a test-spawned CLI could fork a daemon
+    // into the test's temp HOME; the child outlives the test and races its
+    // recursive teardown rm (ENOTEMPTY). Placed after the already-running branch
+    // — reporting a live daemon stays allowed, same as the circuit breaker.
+    // AGENTS_SERVICE_MANAGER_ALLOW_REDIRECTED_HOME=1 is the test seam for suites
+    // that exercise daemon startup deliberately; `agents daemon start` remains
+    // the operator override.
+    if (!serviceManagerRegistrationAllowed().allowed)
+        return null;
     // RUSH-2418: the auto-start circuit breaker. A daemon that dies during
     // startup would otherwise be relaunched by EVERY foreground command that
     // wants one (secrets unlock, browser start, watchdog, ...) — an

package/dist/lib/daemon/daemon.test-fixture.d.ts

@@ -0,0 +1,24 @@
+import { type KeychainBackend } from '../secrets/index.js';
+/**
+ * Shared fixture for the daemon.*.test.ts suite slices (RUSH-2819).
+ *
+ * daemon.test.ts was a single 2201-line file (88 tests, ~112s in CI) — the
+ * slowest file in the daemon test-ownership group, serializing an entire
+ * vitest fork while every other selected file finished. The suite is split
+ * into topical slices so per-file fork parallelism can spread the
+ * process-spawning / real-daemon integration tests across workers; the
+ * helpers shared by more than one slice live here.
+ */
+/** An in-memory KeychainBackend stand-in, so a test never touches the real OS keychain. */
+export declare function makeMemoryBackend(): {
+    backend: KeychainBackend;
+    store: Map<string, string>;
+};
+/**
+ * Registers the keychain-backend swap + AGENTS_SECRETS_NO_AGENT hermeticity
+ * beforeEach/afterEach every slice of the original daemon.test.ts ran under,
+ * verbatim. Call once at the top level of each slice file.
+ */
+export declare function installKeychainHermeticity(): void;
+export declare const REPO_ROOT: string;
+export declare const DIST_ENTRY: string;

package/dist/lib/daemon/daemon.test-fixture.js

@@ -0,0 +1,71 @@
+import { beforeEach, afterEach } from 'vitest';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+import { setKeychainBackendForTest } from '../secrets/index.js';
+import { deleteBundle } from '../secrets/bundles.js';
+/**
+ * Shared fixture for the daemon.*.test.ts suite slices (RUSH-2819).
+ *
+ * daemon.test.ts was a single 2201-line file (88 tests, ~112s in CI) — the
+ * slowest file in the daemon test-ownership group, serializing an entire
+ * vitest fork while every other selected file finished. The suite is split
+ * into topical slices so per-file fork parallelism can spread the
+ * process-spawning / real-daemon integration tests across workers; the
+ * helpers shared by more than one slice live here.
+ */
+/** An in-memory KeychainBackend stand-in, so a test never touches the real OS keychain. */
+export function makeMemoryBackend() {
+    const store = new Map();
+    const backend = {
+        has: (item) => store.has(item),
+        get: (item) => {
+            const v = store.get(item);
+            if (v === undefined)
+                throw new Error(`Keychain item '${item}' not found.`);
+            return v;
+        },
+        set: (item, value) => { store.set(item, value); },
+        delete: (item) => store.delete(item),
+        list: (prefix) => Array.from(store.keys()).filter((k) => k.startsWith(prefix)),
+    };
+    return { backend, store };
+}
+/**
+ * Registers the keychain-backend swap + AGENTS_SECRETS_NO_AGENT hermeticity
+ * beforeEach/afterEach every slice of the original daemon.test.ts ran under,
+ * verbatim. Call once at the top level of each slice file.
+ */
+export function installKeychainHermeticity() {
+    let restore = null;
+    let prevNoAgent;
+    beforeEach(() => {
+        const m = makeMemoryBackend();
+        restore = setKeychainBackendForTest(m.backend);
+        // Hermeticity: readAndResolveBundleEnv consults the running secrets-agent
+        // (bundles.ts agentGetSync fast-path) BEFORE the injected keychain backend.
+        // On a dev machine where the agent is live and the real `claude` bundle is
+        // unlocked, that returns the machine's real CLAUDE_CODE_OAUTH_TOKEN and this
+        // test reads a live credential instead of the seeded value (CI has no agent,
+        // so it only bites locally). Disable the agent so the read falls through to
+        // the in-memory backend above — hermetic regardless of host state.
+        prevNoAgent = process.env.AGENTS_SECRETS_NO_AGENT;
+        process.env.AGENTS_SECRETS_NO_AGENT = '1';
+    });
+    afterEach(() => {
+        try {
+            deleteBundle('claude');
+        }
+        catch { /* not created */ }
+        setKeychainBackendForTest(restore);
+        if (prevNoAgent === undefined)
+            delete process.env.AGENTS_SECRETS_NO_AGENT;
+        else
+            process.env.AGENTS_SECRETS_NO_AGENT = prevNoAgent;
+    });
+}
+// The real compiled CLI entry, shared by every slice that drives an actual
+// `__daemon-run` subprocess (lifecycle/registry/stop). Computed relative to
+// this file's own location, which stays in src/lib/daemon/ alongside every
+// slice, so the path math is unaffected by the split.
+export const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+export const DIST_ENTRY = path.join(REPO_ROOT, 'dist', 'index.js');

package/dist/lib/daemon-ticks.d.ts

@@ -18,11 +18,48 @@ export declare function isFreshFleetAuthSnapshot(value: {
     row: FleetStatusRow;
     authRows: AuthProbeRow[];
 }, minimumCapturedAt: number): boolean;
+/**
+ * How stale a cached auth verdict may get before the periodic tick re-probes.
+ *
+ * The auth verdict rides the same rate-limited `/api/oauth/usage` endpoint as
+ * the usage probe. Firing it every 3-minute tick on every fleet device drove one
+ * per-account request quota to a permanent 429, and the shared backoff then
+ * parked usage fleet-wide and froze the usage cache (RUSH-2998). Re-probing at
+ * most every 20 minutes cuts that endpoint traffic ~5x while still catching a
+ * revocation within one window — and every device keeps a REAL verdict (not a
+ * degraded "unverified"), so `agents devices ping --strict` and the run
+ * auth-preflight keep working on every host, unlike a publisher/subscriber split
+ * that would blind every non-primary box to revocation. Fleet status still
+ * publishes every tick — it does not ride that endpoint.
+ */
+export declare const AUTH_PROBE_MAX_AGE_MS: number;
+/**
+ * True when every cached auth row was probed within {@link AUTH_PROBE_MAX_AGE_MS}
+ * — i.e. reusing them would not let a verdict get staler than one probe window.
+ * Empty cache is never fresh (nothing to reuse). Pure — unit-tested.
+ */
+export declare function isCachedFleetAuthProbeFresh(authRows: AuthProbeRow[], now: number, maxAgeMs?: number): boolean;
+/**
+ * Whether the tick may reuse the cached auth verdict instead of re-probing the
+ * rate-limited endpoint. `force` (an on-demand `agents devices ping`) ALWAYS
+ * re-probes — the whole point of the command is a genuinely live verdict, and
+ * missing this `!force` is exactly how a `--strict` check silently passed a
+ * revoked account (the second `runFleetPing` call site, RUSH-2998). Pure —
+ * unit-tested so that inversion cannot regress unnoticed.
+ */
+export declare function shouldReuseCachedAuthProbe(force: boolean, cached: AuthProbeRow[], now: number, maxAgeMs?: number): boolean;
 /**
  * Fleet cache warm: publish THIS host's row for the caches `agents fleet
  * status` / `agents devices list` read (PUBLISH-OWN / READ-UNION, RUSH-2061).
+ *
+ * `force` is set by on-demand callers (`agents devices ping`) that must return a
+ * genuinely live verdict; the periodic daemon tick leaves it unset so it reuses a
+ * recent verdict per {@link AUTH_PROBE_MAX_AGE_MS} instead of hammering the
+ * rate-limited endpoint every 3 minutes (RUSH-2998).
  */
-export declare function refreshLocalFleetAuthState(): Promise<{
+export declare function refreshLocalFleetAuthState(opts?: {
+    force?: boolean;
+}): Promise<{
     row: FleetStatusRow;
     authRows: import('./auth-health.js').AuthProbeRow[];
 }>;

package/dist/lib/daemon-ticks.js

@@ -17,11 +17,51 @@ export function isFreshFleetAuthSnapshot(value, minimumCapturedAt) {
         && value.authRows.length > 0
         && value.authRows.every(authRow => authRow.health.checkedAt >= minimumCapturedAt);
 }
+/**
+ * How stale a cached auth verdict may get before the periodic tick re-probes.
+ *
+ * The auth verdict rides the same rate-limited `/api/oauth/usage` endpoint as
+ * the usage probe. Firing it every 3-minute tick on every fleet device drove one
+ * per-account request quota to a permanent 429, and the shared backoff then
+ * parked usage fleet-wide and froze the usage cache (RUSH-2998). Re-probing at
+ * most every 20 minutes cuts that endpoint traffic ~5x while still catching a
+ * revocation within one window — and every device keeps a REAL verdict (not a
+ * degraded "unverified"), so `agents devices ping --strict` and the run
+ * auth-preflight keep working on every host, unlike a publisher/subscriber split
+ * that would blind every non-primary box to revocation. Fleet status still
+ * publishes every tick — it does not ride that endpoint.
+ */
+export const AUTH_PROBE_MAX_AGE_MS = 20 * 60_000;
+/**
+ * True when every cached auth row was probed within {@link AUTH_PROBE_MAX_AGE_MS}
+ * — i.e. reusing them would not let a verdict get staler than one probe window.
+ * Empty cache is never fresh (nothing to reuse). Pure — unit-tested.
+ */
+export function isCachedFleetAuthProbeFresh(authRows, now, maxAgeMs = AUTH_PROBE_MAX_AGE_MS) {
+    return authRows.length > 0 && authRows.every((r) => now - r.health.checkedAt < maxAgeMs);
+}
+/**
+ * Whether the tick may reuse the cached auth verdict instead of re-probing the
+ * rate-limited endpoint. `force` (an on-demand `agents devices ping`) ALWAYS
+ * re-probes — the whole point of the command is a genuinely live verdict, and
+ * missing this `!force` is exactly how a `--strict` check silently passed a
+ * revoked account (the second `runFleetPing` call site, RUSH-2998). Pure —
+ * unit-tested so that inversion cannot regress unnoticed.
+ */
+export function shouldReuseCachedAuthProbe(force, cached, now, maxAgeMs = AUTH_PROBE_MAX_AGE_MS) {
+    return !force && isCachedFleetAuthProbeFresh(cached, now, maxAgeMs);
+}
 /**
  * Fleet cache warm: publish THIS host's row for the caches `agents fleet
  * status` / `agents devices list` read (PUBLISH-OWN / READ-UNION, RUSH-2061).
+ *
+ * `force` is set by on-demand callers (`agents devices ping`) that must return a
+ * genuinely live verdict; the periodic daemon tick leaves it unset so it reuses a
+ * recent verdict per {@link AUTH_PROBE_MAX_AGE_MS} instead of hammering the
+ * rate-limited endpoint every 3 minutes (RUSH-2998).
  */
-export async function refreshLocalFleetAuthState() {
+export async function refreshLocalFleetAuthState(opts) {
+    const force = opts?.force === true;
     const { machineId } = await import('./machine-id.js');
     const { probeLocalFleetAuth, readFleetAuthRows, writeFleetAuthRows } = await import('./auth-health.js');
     const { getCliVersion } = await import('./version.js');
@@ -40,11 +80,18 @@ export async function refreshLocalFleetAuthState() {
             return { row, authRows: readFleetAuthRows(self) };
         },
         // A recent daemon publication is the completed result, not a reason to probe
-        // every provider a second time.
-        isCompleted: (value) => isFreshFleetAuthSnapshot(value, minimumCapturedAt),
+        // every provider a second time. An on-demand caller (force) never accepts a
+        // cached snapshot — it must return a genuinely live verdict.
+        isCompleted: (value) => !force && isFreshFleetAuthSnapshot(value, minimumCapturedAt),
         refresh: async () => {
-            const authRows = await probeLocalFleetAuth({ cliVersion: getCliVersion() });
-            writeFleetAuthRows(self, authRows);
+            // Re-probe the rate-limited /oauth/usage endpoint at most every
+            // AUTH_PROBE_MAX_AGE_MS; reuse the last real verdict in between (RUSH-2998).
+            // Fleet status publishes every tick regardless — it does not ride that endpoint.
+            const cached = readFleetAuthRows(self);
+            const reuse = shouldReuseCachedAuthProbe(force, cached, requestedAt);
+            const authRows = reuse ? cached : await probeLocalFleetAuth({ cliVersion: getCliVersion() });
+            if (!reuse)
+                writeFleetAuthRows(self, authRows);
             const row = await publishLocalFleetStatus(self);
             return { row, authRows };
         },

package/dist/lib/device-config.js

@@ -243,8 +243,7 @@ export const CONFIG_KEYS = [
         type: 'string',
         description: "What this device is for, fleet-wide: 'worker' (a box agents run on) or 'personal' (a machine you sit at — never " +
             'picked automatically). Marking ANY device worker turns automatic placement into an allowlist: `--device auto` then ' +
-            'picks only from the marked workers. (A paired iPhone/iPad cockpit is marked control by `agents devices pair-ios` ' +
-            'and is excluded from placement by that role, not this key.)',
+            'picks only from the marked workers.',
         validate: (v) => DEVICE_ROLES.includes(v)
             ? null
             : `role must be one of ${DEVICE_ROLES.join(' | ')}.`,