@phnx-labs/agents-cli 1.14.1 → 1.14.2

package/README.md

@@ -260,6 +260,24 @@ agents run claude "charge a test card" --secrets prod-stripe
 
 Merge order: profile env < `--secrets` < `--env K=V`. A missing keychain item aborts before the child starts.
 
+### Cross-machine sync via iCloud Keychain
+
+Pass `--icloud-sync` when creating a bundle and the values are written to the iCloud-synced keychain. Sign into the same iCloud account on another Mac (with iCloud Keychain enabled) and the values appear there within seconds — no copy-paste, no `.env` files emailed to yourself, no shared secret stores.
+
+```bash
+# On laptop:
+agents secrets create npm-tokens --icloud-sync
+agents secrets add npm-tokens NPM_TOKEN          # value lives in iCloud Keychain
+
+# On another Mac (same iCloud account):
+agents secrets add npm-tokens NPM_TOKEN          # the value is already there;
+                                                 # you only need the bundle YAML locally
+```
+
+Under the hood, `--icloud-sync` routes writes through a notarized helper app (`AgentsKeychain.app`) that holds the entitlement macOS requires for `kSecAttrSynchronizable`. Bundles without `--icloud-sync` use `/usr/bin/security` and stay device-local.
+
+Bundle YAML files (`~/.agents/secrets/*.yml`) are not synced — only the secret values. Push the YAMLs across machines via `agents repo push` if you want full bundle definitions to follow.
+
 ---
 
 ## Routines
@@ -403,7 +421,7 @@ No. API keys come from your shell environment or each agent CLI's existing auth.
 
 macOS and Linux. Windows via WSL works but isn't first-class yet.
 
-**macOS-only features:** Keychain-based secrets (`agents secrets`, `agents profiles login`) require macOS. On Linux, use environment variables or `.env` files for API keys. Native Linux credential store support is planned.
+**macOS-only features:** Keychain-based secrets (`agents secrets`, `agents profiles login`) require macOS. The `--icloud-sync` flag on bundles requires macOS + iCloud Keychain enabled. On Linux, use environment variables or `.env` files for API keys. Native Linux credential store support is planned.
 
 ### Do I need Node.js?
 

package/dist/commands/exec.js

@@ -16,12 +16,12 @@ const VALID_AGENTS = Object.keys(AGENT_COMMANDS);
 function isValidAgent(agent) {
     return VALID_AGENTS.includes(agent);
 }
-/** Build a one-line banner describing which version the rotation picked. */
-function formatRotationBanner(result) {
+/** Build a one-line banner describing which version the strategy picked. */
+function formatRotationBanner(result, verb = 'balanced') {
     const { picked, healthy, excluded } = result;
     const label = picked.email ? `${picked.email} · ${picked.agent}@${picked.version}` : `${picked.agent}@${picked.version}`;
     const ratio = `${healthy.length} of ${healthy.length + excluded.length} healthy`;
-    return `[agents] rotation picked ${label} (${ratio})`;
+    return `[agents] ${verb} picked ${label} (${ratio})`;
 }
 /** Register the `agents run <agent> [prompt]` command. */
 export function registerRunCommand(program) {
@@ -42,8 +42,8 @@ export function registerRunCommand(program) {
         .option('--verbose', 'Show detailed execution logs')
         .option('--timeout <duration>', 'Kill the agent after this duration (e.g., 30m, 1h, 2h30m)')
         .option('--fallback <agents>', 'Comma-separated agents to try on rate-limit failure. Each entry accepts an optional @version pin (e.g., codex@0.116.0,gemini). The primary runs first; if it exits with a rate-limit error, the next agent picks up via /continue handoff.')
-        .option('-r, --rotate', 'Shortcut for --strategy rotate. Ignored when @version is pinned.')
-        .option('--strategy <strategy>', 'Version/account selection strategy: pinned | available | rotate. Defaults to run.<agent>.strategy, then pinned.')
+        .option('-b, --balanced', 'Shortcut for --strategy balanced. Ignored when @version is pinned.')
+        .option('--strategy <strategy>', 'Version/account selection strategy: pinned | available | balanced. Defaults to run.<agent>.strategy, then pinned. (Legacy `rotate` accepted as alias for `balanced`.)')
         .option('--acp', 'Route through the Agent Client Protocol instead of direct exec. Supported for gemini, claude (via @zed-industries/claude-code-acp adapter). Unified event stream; emits ndjson when --json.')
         .addHelpText('after', `
 Modes:
@@ -54,18 +54,20 @@ Run strategy:
   pinned     Use the workspace/global pinned version from agents.yaml.
   available  Use the pinned version if it has usage available; otherwise switch
              to another signed-in version with usage available.
-  rotate     Pick the signed-in account with usage available and the most
-             headroom; last-active breaks ties.
+  balanced   Distribute traffic across healthy accounts using weighted random
+             by remaining capacity — fresher accounts get more, near-exhausted
+             ones get less. Avoids bursting any single account.
   Configure with run.<agent>.strategy in agents.yaml, or override with
-  --strategy. --rotate is kept as a shortcut for --strategy rotate.
+  --strategy. --balanced is kept as a shortcut for --strategy balanced.
+  Legacy "rotate" is accepted as an alias for "balanced".
   Ignored when @version is pinned, when a profile is used, or with --fallback.
 
 Examples:
   # Interactive with the pinned default version
   agents run claude
 
-  # Interactive, rotate to the least-used healthy account
-  agents run claude --strategy rotate
+  # Interactive, distribute load across healthy accounts
+  agents run claude --strategy balanced
 
   # Headless, switch away from the pinned version when usage is unavailable
   agents run claude "summarize recent git commits" --mode plan --strategy available
@@ -134,14 +136,14 @@ Examples:
             console.error(chalk.red(`Invalid strategy: ${options.strategy}. Use ${RUN_STRATEGIES.join(', ')}.`));
             process.exit(1);
         }
-        if (options.rotate && explicitStrategy && explicitStrategy !== 'rotate') {
-            console.error(chalk.red('--rotate conflicts with --strategy. Use one strategy override.'));
+        if (options.balanced && explicitStrategy && explicitStrategy !== 'balanced') {
+            console.error(chalk.red('--balanced conflicts with --strategy. Use one strategy override.'));
             process.exit(1);
         }
-        const strategy = options.rotate ? 'rotate' : explicitStrategy ?? configuredStrategy;
+        const strategy = options.balanced ? 'balanced' : explicitStrategy ?? configuredStrategy;
         // Strategy only applies to bare agent invocations. Explicit @version,
         // profiles, and fallback chains already define their execution target.
-        if (strategy !== 'pinned' || options.rotate || explicitStrategy) {
+        if (strategy !== 'pinned' || options.balanced || explicitStrategy) {
             if (version) {
                 process.stderr.write(chalk.yellow(`[agents] strategy ${strategy} ignored: version ${version} is pinned\n`));
             }
@@ -157,9 +159,7 @@ Examples:
                     if (resolved.version) {
                         version = resolved.version;
                         if (resolved.rotation) {
-                            const banner = strategy === 'available'
-                                ? formatRotationBanner(resolved.rotation).replace('rotation picked', 'available picked')
-                                : formatRotationBanner(resolved.rotation);
+                            const banner = formatRotationBanner(resolved.rotation, strategy);
                             process.stderr.write(chalk.gray(banner + '\n'));
                         }
                     }

package/dist/commands/secrets.js

@@ -139,7 +139,7 @@ function redact(value, reveal) {
 export function registerSecretsCommands(program) {
     const cmd = program
         .command('secrets')
-        .description('Named bundles of env variables backed by macOS Keychain. Inject into agents via `agents run --secrets <name>`.')
+        .description('Named bundles of env variables backed by macOS Keychain (with optional iCloud sync). Inject into agents via `agents run --secrets <name>`.')
         .addHelpText('after', `
 Workflow:
   Bundles are containers; secrets are the variables inside them. Create a
@@ -147,10 +147,17 @@ Workflow:
   run with --secrets <name>. Keychain-backed values never touch disk in
   plaintext.
 
+  Pass --icloud-sync at create time to store values in the iCloud-synced
+  keychain so they appear automatically on your other Macs (same iCloud
+  account, iCloud Keychain enabled). Without the flag, values are device-local.
+
 Examples:
   # Create a bundle for production credentials
   agents secrets create prod --description "Production keys for the api stack"
 
+  # Create a bundle that syncs to your other Macs via iCloud Keychain
+  agents secrets create npm-tokens --icloud-sync
+
   # Add a keychain-backed secret (prompts for the value)
   agents secrets add prod STRIPE_API_KEY
 

package/dist/lib/rotate.d.ts

@@ -25,7 +25,13 @@ export interface RotateResult {
     excluded: RotateCandidate[];
 }
 export declare const RUN_STRATEGIES: RunStrategy[];
-/** Return a run strategy when the input is valid, otherwise null. */
+/**
+ * Return a run strategy when the input is valid, otherwise null.
+ *
+ * `'rotate'` is accepted as a deprecated alias for `'balanced'` so old yaml
+ * configs and `--strategy rotate` invocations keep working. The legacy alias
+ * normalizes to `'balanced'` and uses the weighted-random algorithm.
+ */
 export declare function normalizeRunStrategy(value: unknown): RunStrategy | null;
 /** Read project-local run strategy from the nearest agents.yaml, if present. */
 export declare function getProjectRunStrategy(agent: AgentId, startPath: string): RunStrategy | null;
@@ -34,23 +40,29 @@ export declare function getConfiguredRunStrategy(agent: AgentId, startPath?: str
 /** Persist the global run strategy used by bare `agents run <agent>`. */
 export declare function setGlobalRunStrategy(agent: AgentId, strategy: RunStrategy): void;
 /**
- * Pure selection: given a set of candidates, return the best one for the
- * next run. Kept separate from I/O so it can be unit-tested with fixtures.
+ * Pick a healthy candidate using weighted random by remaining capacity.
+ *
+ * Each healthy candidate gets weight = max(1, 100 - usedPercent) where
+ * usedPercent is the highest-utilized non-session window (week / sonnet_week
+ * for Claude). An account at 10% used gets weight 90; one at 90% used gets
+ * weight 10 — so the fresher account is 9× more likely to be picked. Over N
+ * calls, traffic distributes across healthy accounts proportional to their
+ * headroom, with no stampede on the lowest-usage one. Stateless — parallel
+ * callers naturally fan out via the random roll.
+ *
+ * Eligibility: signed in (email present), auth valid, and usage available
+ * (any non-session window strictly under 100%, or local flag not exhausted
+ * when no live snapshot exists).
+ *
+ * Dedupe: when multiple versions share an email, collapse to one candidate
+ * per email (the least-recently-active version). Prevents two parallel pods
+ * from "balancing" to different versions but hitting the same Anthropic
+ * account and both 429ing.
  *
- * Eligibility: signed in (email present) and not out of credits.
- * Dedupe: when multiple versions share an email (same Anthropic account
- * installed under several agent versions), collapse to one candidate per
- * email — the least-recently-active version. Without this, two parallel
- * pods could "rotate" to different versions but hit the same account and
- * both 429 against the same Anthropic quota.
- * Primary order: lowest live usage utilization wins. Least-recently-active is
- * the tie-breaker when usage is equal or unavailable. Never-used versions sort
- * oldest so fresh installs are tried before recently-used ones.
- * Tie-break: random — when two candidates share a `lastActive` timestamp
- * (common when N pods read the same snapshot), distribute across them so
- * parallel callers fan out instead of all picking the same version.
+ * Returns null if no candidate is eligible — callers fall back to the pinned
+ * version so behavior stays predictable.
  */
-export declare function pickRotateCandidate(candidates: RotateCandidate[]): RotateResult | null;
+export declare function pickBalancedCandidate(candidates: RotateCandidate[]): RotateResult | null;
 /**
  * Pick an available candidate. Prefers the configured pinned version when that
  * version has usage available; otherwise routes to the candidate with the most
@@ -58,19 +70,17 @@ export declare function pickRotateCandidate(candidates: RotateCandidate[]): Rota
  */
 export declare function pickAvailableCandidate(candidates: RotateCandidate[], preferredVersion?: string | null): RotateResult | null;
 /**
- * Rotate across installed versions of an agent and pick the best one for the
- * next run. "Best" means: signed in, usage available, and lowest usage
- * utilization, with least-recently-active as a tie-breaker.
+ * Pick a healthy version for `agent` using weighted random by remaining
+ * capacity. See `pickBalancedCandidate` for algorithm details.
  *
- * No external state: rotation and health are both read off per-version
- * AccountInfo — the same data `agents view` already surfaces. `lastActive`
- * advances naturally after each run, so the cursor is self-maintaining.
+ * No external state — health and capacity are both read off per-version
+ * AccountInfo (same data `agents view` surfaces). The weighted random roll
+ * keeps parallel callers fanned out without rotation files or locks.
  *
- * Returns null if no installed version is eligible (either nothing installed
- * or every account is exhausted / not signed in). Callers fall back to the
+ * Returns null if no installed version is eligible. Callers fall back to the
  * global default so behavior stays predictable — we never refuse to run.
  */
-export declare function selectRotateVersion(agent: AgentId): Promise<RotateResult | null>;
+export declare function selectBalancedVersion(agent: AgentId): Promise<RotateResult | null>;
 /** Select the configured version if available, otherwise another available version. */
 export declare function selectAvailableVersion(agent: AgentId, preferredVersion?: string | null): Promise<RotateResult | null>;
 export declare function resolveRunVersion(agent: AgentId, strategy: RunStrategy, cwd?: string): Promise<{

package/dist/lib/rotate.js

@@ -11,12 +11,20 @@ import { getAccountInfo } from './agents.js';
 import { readMeta, writeMeta, getAgentsDir } from './state.js';
 import { listInstalledVersions, getVersionHomePath, resolveVersion } from './versions.js';
 import { getUsageInfoByIdentity, getUsageLookupKey, isClaudeAuthValid, } from './usage.js';
-export const RUN_STRATEGIES = ['pinned', 'available', 'rotate'];
-/** Return a run strategy when the input is valid, otherwise null. */
+export const RUN_STRATEGIES = ['pinned', 'available', 'balanced'];
+/**
+ * Return a run strategy when the input is valid, otherwise null.
+ *
+ * `'rotate'` is accepted as a deprecated alias for `'balanced'` so old yaml
+ * configs and `--strategy rotate` invocations keep working. The legacy alias
+ * normalizes to `'balanced'` and uses the weighted-random algorithm.
+ */
 export function normalizeRunStrategy(value) {
-    return typeof value === 'string' && RUN_STRATEGIES.includes(value)
-        ? value
-        : null;
+    if (typeof value !== 'string')
+        return null;
+    if (value === 'rotate')
+        return 'balanced';
+    return RUN_STRATEGIES.includes(value) ? value : null;
 }
 /** Read project-local run strategy from the nearest agents.yaml, if present. */
 export function getProjectRunStrategy(agent, startPath) {
@@ -112,23 +120,29 @@ function dedupeAndSortCandidates(candidates) {
     return [...byEmail.values()].sort(compareCandidates);
 }
 /**
- * Pure selection: given a set of candidates, return the best one for the
- * next run. Kept separate from I/O so it can be unit-tested with fixtures.
+ * Pick a healthy candidate using weighted random by remaining capacity.
+ *
+ * Each healthy candidate gets weight = max(1, 100 - usedPercent) where
+ * usedPercent is the highest-utilized non-session window (week / sonnet_week
+ * for Claude). An account at 10% used gets weight 90; one at 90% used gets
+ * weight 10 — so the fresher account is 9× more likely to be picked. Over N
+ * calls, traffic distributes across healthy accounts proportional to their
+ * headroom, with no stampede on the lowest-usage one. Stateless — parallel
+ * callers naturally fan out via the random roll.
+ *
+ * Eligibility: signed in (email present), auth valid, and usage available
+ * (any non-session window strictly under 100%, or local flag not exhausted
+ * when no live snapshot exists).
+ *
+ * Dedupe: when multiple versions share an email, collapse to one candidate
+ * per email (the least-recently-active version). Prevents two parallel pods
+ * from "balancing" to different versions but hitting the same Anthropic
+ * account and both 429ing.
  *
- * Eligibility: signed in (email present) and not out of credits.
- * Dedupe: when multiple versions share an email (same Anthropic account
- * installed under several agent versions), collapse to one candidate per
- * email — the least-recently-active version. Without this, two parallel
- * pods could "rotate" to different versions but hit the same account and
- * both 429 against the same Anthropic quota.
- * Primary order: lowest live usage utilization wins. Least-recently-active is
- * the tie-breaker when usage is equal or unavailable. Never-used versions sort
- * oldest so fresh installs are tried before recently-used ones.
- * Tie-break: random — when two candidates share a `lastActive` timestamp
- * (common when N pods read the same snapshot), distribute across them so
- * parallel callers fan out instead of all picking the same version.
+ * Returns null if no candidate is eligible — callers fall back to the pinned
+ * version so behavior stays predictable.
  */
-export function pickRotateCandidate(candidates) {
+export function pickBalancedCandidate(candidates) {
     const healthy = [];
     const excluded = [];
     for (const c of candidates) {
@@ -146,7 +160,33 @@ export function pickRotateCandidate(candidates) {
         if (!deduped.has(c))
             excluded.push(c);
     }
-    return { picked: sorted[0], healthy: sorted, excluded };
+    const picked = weightedRandomByCapacity(sorted);
+    return { picked, healthy: sorted, excluded };
+}
+/**
+ * Pick one candidate from `sorted` using weights proportional to remaining
+ * routing capacity. Floor each weight at 1 so a near-exhausted-but-still-
+ * eligible candidate can still be picked occasionally. When usage is unknown
+ * (no live snapshot), treat the candidate as full-capacity (weight 100) — we
+ * have no signal to deprioritize it.
+ */
+function weightedRandomByCapacity(sorted) {
+    const weights = sorted.map((c) => {
+        const used = getRoutingUsedPercent(c.usageSnapshot);
+        if (used === null)
+            return 100;
+        return Math.max(1, 100 - used);
+    });
+    const total = weights.reduce((sum, w) => sum + w, 0);
+    if (total <= 0)
+        return sorted[0];
+    let roll = Math.random() * total;
+    for (let i = 0; i < sorted.length; i++) {
+        roll -= weights[i];
+        if (roll <= 0)
+            return sorted[i];
+    }
+    return sorted[sorted.length - 1];
 }
 /**
  * Pick an available candidate. Prefers the configured pinned version when that
@@ -210,20 +250,18 @@ async function collectRunCandidates(agent) {
     });
 }
 /**
- * Rotate across installed versions of an agent and pick the best one for the
- * next run. "Best" means: signed in, usage available, and lowest usage
- * utilization, with least-recently-active as a tie-breaker.
+ * Pick a healthy version for `agent` using weighted random by remaining
+ * capacity. See `pickBalancedCandidate` for algorithm details.
  *
- * No external state: rotation and health are both read off per-version
- * AccountInfo — the same data `agents view` already surfaces. `lastActive`
- * advances naturally after each run, so the cursor is self-maintaining.
+ * No external state — health and capacity are both read off per-version
+ * AccountInfo (same data `agents view` surfaces). The weighted random roll
+ * keeps parallel callers fanned out without rotation files or locks.
  *
- * Returns null if no installed version is eligible (either nothing installed
- * or every account is exhausted / not signed in). Callers fall back to the
+ * Returns null if no installed version is eligible. Callers fall back to the
  * global default so behavior stays predictable — we never refuse to run.
  */
-export async function selectRotateVersion(agent) {
-    return pickRotateCandidate(await collectRunCandidates(agent));
+export async function selectBalancedVersion(agent) {
+    return pickBalancedCandidate(await collectRunCandidates(agent));
 }
 /** Select the configured version if available, otherwise another available version. */
 export async function selectAvailableVersion(agent, preferredVersion) {
@@ -268,17 +306,21 @@ export async function resolveRunVersion(agent, strategy, cwd = process.cwd()) {
     }
     const rotation = strategy === 'available'
         ? await selectAvailableVersion(agent, fallback)
-        : await selectRotateVersion(agent);
+        : await selectBalancedVersion(agent);
     if (rotation) {
-        // If another process just picked the same version (within 60s), try the
-        // next healthy candidate to distribute load across accounts.
-        const recentPick = readRotationStamp(agent);
-        if (recentPick === rotation.picked.version && rotation.healthy.length > 1) {
-            const alt = rotation.healthy.find(c => c.version !== recentPick);
-            if (alt)
-                rotation.picked = alt;
+        // `available` is sticky to the pinned default when healthy. Use the 60s
+        // anti-collision stamp to nudge parallel callers off the same version.
+        // `balanced` doesn't need this — its weighted random roll already
+        // distributes naturally across healthy accounts.
+        if (strategy === 'available') {
+            const recentPick = readRotationStamp(agent);
+            if (recentPick === rotation.picked.version && rotation.healthy.length > 1) {
+                const alt = rotation.healthy.find(c => c.version !== recentPick);
+                if (alt)
+                    rotation.picked = alt;
+            }
+            recordRotationPick(agent, rotation.picked.version);
         }
-        recordRotationPick(agent, rotation.picked.version);
         return { version: rotation.picked.version, rotation };
     }
     return { version: fallback, rotation: null };

package/dist/lib/types.d.ts

@@ -8,7 +8,7 @@
 /** Unique identifier for a supported AI coding agent. */
 export type AgentId = 'claude' | 'codex' | 'gemini' | 'cursor' | 'opencode' | 'openclaw' | 'copilot' | 'amp' | 'kiro' | 'goose' | 'roo';
 /** How `agents run <agent>` chooses an installed version when none is pinned. */
-export type RunStrategy = 'pinned' | 'available' | 'rotate';
+export type RunStrategy = 'pinned' | 'available' | 'balanced';
 /** Preview features that users can opt into via `agents beta`. */
 export type BetaFeatureName = 'drive' | 'factory';
 /** Subset of chalk color names used for agent-specific terminal output. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.14.1",
+  "version": "1.14.2",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams",
   "type": "module",
   "main": "dist/index.js",