@phnx-labs/agents-cli 1.20.63 → 1.20.64

package/dist/commands/usage.js

@@ -3,8 +3,13 @@ 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. */
-const USAGE_SUPPORTED = new Set(['claude', 'codex']);
+/**
+ * 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']);
 export function registerUsageCommand(program) {
     addHostOption(program.command('usage [agent]'))
         .description('Show rate-limit / quota usage per agent')

package/dist/commands/view.d.ts

@@ -39,7 +39,7 @@ export interface ViewJsonVersion {
         currency: string;
     } | null;
     windows: Array<{
-        key: 'session' | 'week' | 'sonnet_week';
+        key: 'session' | 'week' | 'sonnet_week' | 'month';
         usedPercent: number;
         resetsAt: string | null;
     }>;

package/dist/index.js

@@ -50,7 +50,7 @@ if (IS_DEV_BUILD) {
 // module on each invocation (which loaded the whole ~50-module tree before the
 // first byte of output), the registry maps a command name to a thunk that
 // imports only what that command needs. See src/lib/startup/command-registry.ts.
-import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadMemory, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadPackages, loadDaemon, loadRoutines, loadRun, loadDefaults, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadCheck, loadStatus, loadProfiles, loadSecrets, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadLock, loadRefreshRules, loadDrive, loadFactory, loadUsage, loadCost, loadOutput, loadBudget, loadAlias, loadPty, loadTmux, loadWatchdog, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadAudit, loadWebhook, loadFunnel, loadSsh, loadPull, loadPush, loadRepo, loadSetup, loadFeed, } from './lib/startup/command-registry.js';
+import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadMemory, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadPackages, loadDaemon, loadRoutines, loadRun, loadDefaults, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadCheck, loadStatus, loadProfiles, loadSecrets, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadLock, loadRefreshRules, loadDrive, loadFactory, loadUsage, loadCost, loadOutput, loadBudget, loadAlias, loadPty, loadTmux, loadWatchdog, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadAudit, loadWebhook, loadFunnel, loadSsh, loadPull, loadPush, loadRepo, loadSetup, loadFeed, loadMailboxes, } from './lib/startup/command-registry.js';
 import { applyGlobalHelpConventions } from './lib/help.js';
 import { renderWhatsNew } from './lib/whats-new.js';
 import { emit, redactArgs } from './lib/events.js';
@@ -707,6 +707,7 @@ async function registerAllEagerCommands() {
     await reg(loadWebhook);
     await reg(loadFunnel);
     await reg(loadFeed);
+    await reg(loadMailboxes);
     await reg(loadSsh);
     registerJobsCronAliasCommand(program, 'jobs');
     registerJobsCronAliasCommand(program, 'cron');

package/dist/lib/agents.d.ts

@@ -130,6 +130,22 @@ export interface AccountInfo {
 }
 /** Return the email address associated with the agent's auth config, or null. */
 export declare function getAccountEmail(agentId: AgentId, home?: string): Promise<string | null>;
+/** Decrypted contents of Droid's auth.v2.file (subset we consume). */
+export interface DroidAuthPayload {
+    access_token?: string;
+    active_organization_id?: string | null;
+}
+/**
+ * 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
+ * in ~/.factory/auth.v2.key. On the keyfile-v2 source there is no OS-keychain /
+ * device binding — the key is on disk — so we can decrypt locally with no
+ * network call. Every failure (missing key file — e.g. a keyring-v2/legacy
+ * login with no on-disk key, a bad GCM tag, or malformed JSON) returns null.
+ * Never throws. Shared by account identity below and the Droid usage fetcher
+ * in usage.ts.
+ */
+export declare function decryptDroidAuthPayload(base: string): DroidAuthPayload | null;
 /**
  * Antigravity (`agy`) stores its OAuth token via the Go keyring library
  * (zalando/go-keyring), which is platform-split:
@@ -173,6 +189,8 @@ export declare function resolveLastActive(agentId: AgentId, base: string, config
  * Used during init to show approximate session count to user.
  */
 export declare function countSessionFiles(agentId: AgentId): number;
+/** Decode the payload section of a JWT token without verifying its signature. */
+export declare function decodeJwtPayload(token: string): Record<string, any> | null;
 /** Register an MCP server with an agent's CLI via `mcp add`. */
 export declare function registerMcp(agentId: AgentId, name: string, command: string, scope?: 'user' | 'project', transport?: string, options?: {
     home?: string;

package/dist/lib/agents.js

@@ -984,15 +984,12 @@ function resolveAccountCredentialPath(base, ...segments) {
  * (AES-256-GCM, format `ivB64:tagB64:ctB64`) with the 32-byte key base64-stored
  * in ~/.factory/auth.v2.key. On the keyfile-v2 source there is no OS-keychain /
  * device binding — the key is on disk — so we can decrypt locally with no
- * network call. The decrypted JSON credential's `access_token` is a WorkOS JWT
- * carrying an `email` claim (plus org_id / role). We decode the claim WITHOUT
- * verifying `exp`: the email is stable identity for display, not an
- * authorization decision, so an expired token still yields the right address.
- * Every failure (missing key file — e.g. a keyring-v2/legacy login with no
- * on-disk key, a bad GCM tag, malformed JSON, or no email claim) returns null so
- * the caller falls back to the file-presence signed-in signal. Never throws.
+ * network call. Every failure (missing key file — e.g. a keyring-v2/legacy
+ * login with no on-disk key, a bad GCM tag, or malformed JSON) returns null.
+ * Never throws. Shared by account identity below and the Droid usage fetcher
+ * in usage.ts.
  */
-function decryptDroidCredential(base) {
+export function decryptDroidAuthPayload(base) {
     const filePath = resolveAccountCredentialPath(base, '.factory', 'auth.v2.file');
     const keyPath = resolveAccountCredentialPath(base, '.factory', 'auth.v2.key');
     if (!filePath || !keyPath)
@@ -1012,19 +1009,32 @@ function decryptDroidCredential(base) {
             decipher.final(),
         ]).toString('utf-8');
         const cred = JSON.parse(plaintext);
-        const claims = typeof cred?.access_token === 'string' ? decodeJwtPayload(cred.access_token) : null;
-        if (!claims)
-            return null;
-        return {
-            email: typeof claims.email === 'string' ? claims.email : null,
-            orgId: normalizeIdentityPart(claims.org_id ?? cred.active_organization_id),
-            role: typeof claims.role === 'string' ? claims.role : null,
-        };
+        return cred && typeof cred === 'object' ? cred : null;
     }
     catch {
         return null;
     }
 }
+/**
+ * Derive Droid account identity from the decrypted credential. The
+ * `access_token` is a WorkOS JWT carrying an `email` claim (plus org_id /
+ * role). We decode the claim WITHOUT verifying `exp`: the email is stable
+ * identity for display, not an authorization decision, so an expired token
+ * still yields the right address. Returns null when the credential can't be
+ * decrypted or has no decodable claims, so the caller falls back to the
+ * file-presence signed-in signal.
+ */
+function decryptDroidCredential(base) {
+    const cred = decryptDroidAuthPayload(base);
+    const claims = typeof cred?.access_token === 'string' ? decodeJwtPayload(cred.access_token) : null;
+    if (!claims)
+        return null;
+    return {
+        email: typeof claims.email === 'string' ? claims.email : null,
+        orgId: normalizeIdentityPart(claims.org_id ?? cred?.active_organization_id),
+        role: typeof claims.role === 'string' ? claims.role : null,
+    };
+}
 let cachedAgyKeychainSignedIn;
 /**
  * Antigravity (`agy`) stores its OAuth token via the Go keyring library
@@ -1564,7 +1574,7 @@ export function countSessionFiles(agentId) {
     return count;
 }
 /** Decode the payload section of a JWT token without verifying its signature. */
-function decodeJwtPayload(token) {
+export function decodeJwtPayload(token) {
     const payload = token.split('.')[1];
     if (!payload)
         return null;

package/dist/lib/browser/drivers/ssh.js

@@ -9,7 +9,7 @@ import { writeProfileRuntime, clearProfileRuntime } from '../runtime-state.js';
 // is the shared hardened baseline (BatchMode + ConnectTimeout + keepalive) —
 // reuse it so the raw-ssh spawns below fail fast on an unreachable host instead
 // of hanging on the default ~127s TCP timeout, rather than re-listing options.
-import { shellQuote, SSH_OPTS } from '../../ssh-exec.js';
+import { shellQuote, SSH_OPTS, assertValidSshTarget } from '../../ssh-exec.js';
 export { shellQuote };
 // The `ssh -L` tunnel spawn is shared with `agents computer --host`; it lives in
 // the single ssh-tunnel helper. Calling it with no options preserves this
@@ -292,6 +292,12 @@ export function buildKillCmd(remoteOs, port) {
     return `pids=$(lsof -ti ${shellQuote(`:${port}`)} 2>/dev/null); [ -z "$pids" ] || kill -9 $pids 2>/dev/null || true`;
 }
 export async function ensureRemoteBrowser(user, host, browserType, port, remoteOs, customBinary) {
+    // `user`/`host` derive from an ssh:// profile endpoint (git-tracked user
+    // config). Validate the composed target before it reaches the raw `ssh` spawn:
+    // an endpoint like `ssh://-Fattack@victim` would otherwise place `-Fattack` at
+    // the target position, where OpenSSH parses it as `-F <file>` and an
+    // attacker-supplied ssh config's ProxyCommand yields local code execution.
+    assertValidSshTarget(`${user}@${host}`);
     const remoteCmd = buildLaunchCmd(remoteOs, browserType, port, customBinary);
     return new Promise((resolve, reject) => {
         // Capture stderr so a real launch failure (missing exe, auth denied, bad
@@ -362,7 +368,18 @@ export function killRemoteBrowser(user, host, remoteOs, port) {
     return runSSHCommand(user, host, buildKillCmd(remoteOs, port));
 }
 function runSSHCommand(user, host, cmd) {
-    return new Promise((resolve) => {
+    return new Promise((resolve, reject) => {
+        // Reject an option-injecting target (e.g. a `-`-leading user from a crafted
+        // ssh:// profile) before it reaches the raw `ssh` spawn. Reject rather than
+        // throw synchronously so `killRemoteBrowser(...).catch()` stays best-effort.
+        // See ensureRemoteBrowser.
+        try {
+            assertValidSshTarget(`${user}@${host}`);
+        }
+        catch (err) {
+            reject(err);
+            return;
+        }
         // Reuse the shared hardened baseline so a hung TCP SYN to an unreachable
         // host is bounded by ConnectTimeout (the local 3s kill below only bounds a
         // connected-but-slow command, not the connect itself). Options precede the

package/dist/lib/comms-render.d.ts

@@ -0,0 +1,37 @@
+import type { CommsMsg } from './mailbox.js';
+export type { CommsMsg } from './mailbox.js';
+export declare const GLYPH: {
+    readonly live: "●";
+    readonly idle: "○";
+    readonly ask: "▲";
+    readonly delivered: "✓";
+    readonly pending: "⏳";
+    readonly route: "→";
+    readonly stream: "─→";
+    readonly thread: "⇄";
+};
+export type Accent = 'cyan' | 'amber';
+/** Render the shared one-line comms header, with `right` aligned to the terminal edge. */
+export declare function masthead(o: {
+    title: string;
+    host: string;
+    accent: Accent;
+    right?: string;
+    stats?: string[];
+}): string;
+/** Normalize non-negative counts across the eight Unicode sparkline levels. */
+export declare function sparkline(counts: number[]): string;
+/** Flatten mailbox histories into one newest-first communication stream. */
+export declare function aggregate(boxes: {
+    id: string;
+    label: string;
+    messages: import('./mailbox.js').StoredMessage[];
+}[]): CommsMsg[];
+/** Count messages in rolling one-hour buckets, ordered oldest to newest. */
+export declare function hourlyCounts(msgs: CommsMsg[], hours: number, now?: Date): number[];
+/** Aggregate the human-readable sender-to-recipient routes, busiest first. */
+export declare function graphEdges(msgs: CommsMsg[]): {
+    from: string;
+    to: string;
+    count: number;
+}[];

package/dist/lib/comms-render.js

@@ -0,0 +1,89 @@
+import chalk from 'chalk';
+import { stringWidth, terminalWidth } from './session/width.js';
+export const GLYPH = {
+    live: '●',
+    idle: '○',
+    ask: '▲',
+    delivered: '✓',
+    pending: '⏳',
+    route: '→',
+    stream: '─→',
+    thread: '⇄',
+};
+/** Render the shared one-line comms header, with `right` aligned to the terminal edge. */
+export function masthead(o) {
+    const accent = o.accent === 'cyan' ? chalk.cyan : chalk.yellow;
+    const title = `${accent('⌁')} ${chalk.bold(accent(o.title))}`;
+    const host = chalk.dim(` · ${o.host}`);
+    const stats = o.stats?.length ? `   ${o.stats.join(chalk.dim(' · '))}` : '';
+    const left = `${title}${host}${stats}`;
+    if (!o.right)
+        return left;
+    const right = chalk.dim(o.right);
+    const gap = Math.max(1, terminalWidth() - stringWidth(left) - stringWidth(right));
+    return `${left}${' '.repeat(gap)}${right}`;
+}
+const SPARK_LEVELS = '▁▂▃▄▅▆▇█';
+/** Normalize non-negative counts across the eight Unicode sparkline levels. */
+export function sparkline(counts) {
+    if (counts.length === 0)
+        return ' ';
+    const normalized = counts.map((count) => Number.isFinite(count) ? Math.max(0, count) : 0);
+    const max = Math.max(...normalized);
+    if (max === 0)
+        return ' '.repeat(counts.length);
+    return normalized
+        .map((count) => SPARK_LEVELS[Math.round((count / max) * (SPARK_LEVELS.length - 1))])
+        .join('');
+}
+/** Flatten mailbox histories into one newest-first communication stream. */
+export function aggregate(boxes) {
+    return boxes
+        .flatMap((box) => {
+        const toLabel = box.label || box.id.slice(0, 8);
+        return box.messages.map((message) => ({
+            from: message.from || 'operator',
+            to: message.to,
+            toLabel,
+            ts: message.ts,
+            text: message.text,
+            state: message.state,
+            box: box.id,
+        }));
+    })
+        .sort((a, b) => compareText(b.ts, a.ts));
+}
+const HOUR_MS = 60 * 60 * 1_000;
+/** Count messages in rolling one-hour buckets, ordered oldest to newest. */
+export function hourlyCounts(msgs, hours, now = new Date()) {
+    const bucketCount = Number.isFinite(hours) ? Math.max(0, Math.floor(hours)) : 0;
+    const counts = Array.from({ length: bucketCount }, () => 0);
+    const nowMs = now.getTime();
+    if (bucketCount === 0 || !Number.isFinite(nowMs))
+        return counts;
+    for (const message of msgs) {
+        const timestamp = Date.parse(message.ts);
+        const age = nowMs - timestamp;
+        if (!Number.isFinite(timestamp) || age < 0 || age >= bucketCount * HOUR_MS)
+            continue;
+        const bucket = bucketCount - 1 - Math.floor(age / HOUR_MS);
+        counts[bucket]++;
+    }
+    return counts;
+}
+/** Aggregate the human-readable sender-to-recipient routes, busiest first. */
+export function graphEdges(msgs) {
+    const edges = new Map();
+    for (const message of msgs) {
+        const key = JSON.stringify([message.from, message.toLabel]);
+        const existing = edges.get(key);
+        if (existing)
+            existing.count++;
+        else
+            edges.set(key, { from: message.from, to: message.toLabel, count: 1 });
+    }
+    return [...edges.values()].sort((a, b) => b.count - a.count || compareText(a.from, b.from) || compareText(a.to, b.to));
+}
+function compareText(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}

package/dist/lib/crabbox/cli.d.ts

@@ -11,6 +11,7 @@
  * needs a provider token (e.g. HCLOUD_TOKEN) in the environment. We inject it
  * from a secrets bundle when one is configured (see `crabboxEnv`).
  */
+import { type SecretsBundle } from '../secrets/bundles.js';
 /** A crabbox machine as reported by `crabbox list --json`. */
 export interface CrabboxBox {
     /** Provider machine name, e.g. `crabbox-blue-hermit-1039689b`. */
@@ -29,6 +30,16 @@ export interface CrabboxBox {
     class?: string;
     /** True when running + bootstrap-complete. */
     ready: boolean;
+    /** crabbox `keep` label — a kept box survives `crabbox cleanup` past its TTL. */
+    keep: boolean;
+    /** Unix seconds the box was created, or null when the label is absent. */
+    createdAt: number | null;
+    /** Unix seconds the lease expires, or null. */
+    expiresAt: number | null;
+    /** Unix seconds the box was last touched (reused / run against), or null. */
+    lastTouchedAt: number | null;
+    /** Idle-timeout window in seconds, or null. */
+    idleTimeoutSecs: number | null;
 }
 export interface CrabboxOptions {
     /**
@@ -41,6 +52,38 @@ export interface CrabboxOptions {
 }
 /** Locate the crabbox binary, or throw an actionable error. */
 export declare function findCrabbox(): string;
+/**
+ * Env keys that mark a secrets bundle as usable for `--lease` — the provider
+ * tokens crabbox reads to reach a cloud API. Matching a bundle needs only its
+ * declared key NAMES; only the matched key's VALUE is ever injected (see
+ * `crabboxEnv`), so an auto-detected bundle can't leak its other secrets.
+ */
+export declare const LEASE_PROVIDER_TOKEN_KEYS: string[];
+/** The first bundle that declares a provider token key, or undefined. Pure over `bundles`. */
+export declare function pickLeaseBundleFromList(bundles: SecretsBundle[]): string | undefined;
+/** A resolved lease bundle: its name, plus (auto-detect only) the exact keys to inject. */
+export interface ResolvedLeaseBundle {
+    name: string;
+    /** When set (auto-detect), inject ONLY these keys — not the whole bundle. */
+    keys?: string[];
+}
+/**
+ * The secrets bundle to feed crabbox, resolved in priority order:
+ *   1. `AGENTS_LEASE_SECRETS_BUNDLE` env var          — explicit, no keychain
+ *   2. `lease.secretsBundle` config (set by `lease setup`) — explicit, no keychain
+ *   3. auto-detect: the first keychain bundle DECLARING a provider token key
+ *
+ * Tiers 1–2 are the frictionless steady state (env + config are plain, no keychain
+ * read). Tier 3 is a fallback that DOES read bundle metadata via `listBundles()`
+ * (one batched keychain unlock, ~7-day broker cache) — so it only runs when
+ * neither env nor config is set, and `crabboxEnv` memoizes the result for the
+ * process (it is called several times per lease, and we don't want a scan each
+ * time). Once `lease setup` persists the choice (tier 2), tier 3 never runs.
+ * Returns undefined when nothing matches — crabbox then falls back to `crabbox login`.
+ */
+export declare function resolveLeaseBundle(): ResolvedLeaseBundle | undefined;
+/** Persist `lease.secretsBundle` in agents config so `--lease` needs no env var. */
+export declare function setLeaseSecretsBundle(name: string): void;
 /** Build the child env for crabbox, injecting a secrets bundle when configured. */
 export declare function crabboxEnv(opts: CrabboxOptions): NodeJS.ProcessEnv;
 /** All crabbox machines the broker knows about. */
@@ -96,3 +139,32 @@ export declare function crabboxRun(slug: string, remoteCmd: string, opts?: Crabb
 export declare function crabboxRunScript(slug: string, script: string, opts?: CrabboxRunOptions): Promise<number | null>;
 /** Release the lease / delete the box. Best-effort; never throws. */
 export declare function crabboxStop(slug: string, opts?: CrabboxOptions): boolean;
+/** Never reap a box touched within this many seconds, regardless of idle-timeout. */
+export declare const REAP_MIN_IDLE_SECS = 3600;
+/**
+ * Whether a box is a genuine orphan that is safe to reap.
+ *
+ * Reap-safe ONLY when BOTH hold: the lease has already expired (`expiresAt` in the
+ * past) AND the box has not been touched for a safety window of
+ * `max(2 × idleTimeout, 1h)`. The freshness guard is what makes this safe against
+ * a TOCTOU race: a box a concurrent run just reused (`cbx_acquire_box`) has a
+ * recent `lastTouchedAt` and is never eligible. Reaping by `profile`/`ready` alone
+ * — as `crabbox cleanup` cannot (it skips `keep=true`, which every real orphan is)
+ * — would kill in-use boxes. Boxes with unknown age (`expiresAt`/`lastTouchedAt`
+ * null) are never reaped. `nowSecs` is injected so tests don't wall-clock.
+ */
+export declare function isReapSafe(box: CrabboxBox, nowSecs: number): boolean;
+/** The reap-safe orphans among `boxes`, most-stale (oldest touch) first. */
+export declare function reapSafeOrphans(boxes: CrabboxBox[], nowSecs: number): CrabboxBox[];
+/**
+ * List reap-safe orphans and (unless `dryRun`) stop them. Returns the candidates
+ * considered and the slugs actually stopped. Best-effort per box — a stop failure
+ * is skipped, never thrown. Backs `agents lease gc` and the 403 auto-reap opt-in.
+ */
+export declare function reapOrphans(opts?: CrabboxOptions & {
+    nowSecs?: number;
+    dryRun?: boolean;
+}): {
+    candidates: CrabboxBox[];
+    reaped: string[];
+};

package/dist/lib/crabbox/cli.js

@@ -12,7 +12,8 @@
  * from a secrets bundle when one is configured (see `crabboxEnv`).
  */
 import { spawn, spawnSync } from 'child_process';
-import { readAndResolveBundleEnv } from '../secrets/bundles.js';
+import { readAndResolveBundleEnv, listBundles, bundleExists } from '../secrets/bundles.js';
+import { readMeta, writeMeta } from '../state.js';
 /** Locate the crabbox binary, or throw an actionable error. */
 export function findCrabbox() {
     const r = spawnSync('crabbox', ['--help'], { encoding: 'utf-8' });
@@ -21,21 +22,95 @@ export function findCrabbox() {
     }
     return 'crabbox';
 }
+/**
+ * Env keys that mark a secrets bundle as usable for `--lease` — the provider
+ * tokens crabbox reads to reach a cloud API. Matching a bundle needs only its
+ * declared key NAMES; only the matched key's VALUE is ever injected (see
+ * `crabboxEnv`), so an auto-detected bundle can't leak its other secrets.
+ */
+export const LEASE_PROVIDER_TOKEN_KEYS = ['HCLOUD_TOKEN', 'AWS_ACCESS_KEY_ID', 'DIGITALOCEAN_TOKEN', 'DO_TOKEN'];
+/** The first bundle that declares a provider token key, or undefined. Pure over `bundles`. */
+export function pickLeaseBundleFromList(bundles) {
+    for (const b of bundles) {
+        if (Object.keys(b.vars ?? {}).some((k) => LEASE_PROVIDER_TOKEN_KEYS.includes(k)))
+            return b.name;
+    }
+    return undefined;
+}
+/**
+ * The secrets bundle to feed crabbox, resolved in priority order:
+ *   1. `AGENTS_LEASE_SECRETS_BUNDLE` env var          — explicit, no keychain
+ *   2. `lease.secretsBundle` config (set by `lease setup`) — explicit, no keychain
+ *   3. auto-detect: the first keychain bundle DECLARING a provider token key
+ *
+ * Tiers 1–2 are the frictionless steady state (env + config are plain, no keychain
+ * read). Tier 3 is a fallback that DOES read bundle metadata via `listBundles()`
+ * (one batched keychain unlock, ~7-day broker cache) — so it only runs when
+ * neither env nor config is set, and `crabboxEnv` memoizes the result for the
+ * process (it is called several times per lease, and we don't want a scan each
+ * time). Once `lease setup` persists the choice (tier 2), tier 3 never runs.
+ * Returns undefined when nothing matches — crabbox then falls back to `crabbox login`.
+ */
+export function resolveLeaseBundle() {
+    const env = process.env.AGENTS_LEASE_SECRETS_BUNDLE;
+    if (env)
+        return { name: env };
+    try {
+        const configured = readMeta().lease?.secretsBundle;
+        if (configured && bundleExists(configured))
+            return { name: configured };
+    }
+    catch {
+        /* config unreadable — fall through to auto-detect */
+    }
+    try {
+        const bundles = listBundles();
+        const name = pickLeaseBundleFromList(bundles);
+        if (name) {
+            const b = bundles.find((x) => x.name === name);
+            const keys = LEASE_PROVIDER_TOKEN_KEYS.filter((k) => !!b && k in (b.vars ?? {}));
+            return { name, keys };
+        }
+    }
+    catch {
+        /* secrets unreadable — no auto-detect */
+    }
+    return undefined;
+}
+/** Process-lifetime memo so the tier-3 `listBundles()` scan runs at most once. */
+let leaseBundleMemo;
+function resolveLeaseBundleMemo() {
+    if (!leaseBundleMemo)
+        leaseBundleMemo = { value: resolveLeaseBundle() };
+    return leaseBundleMemo.value;
+}
+/** Persist `lease.secretsBundle` in agents config so `--lease` needs no env var. */
+export function setLeaseSecretsBundle(name) {
+    const meta = readMeta();
+    writeMeta({ ...meta, lease: { ...meta.lease, secretsBundle: name } });
+    leaseBundleMemo = undefined; // invalidate so the next resolve sees the new config
+}
 /** Build the child env for crabbox, injecting a secrets bundle when configured. */
 export function crabboxEnv(opts) {
-    const bundle = opts.secretsBundle ?? process.env.AGENTS_LEASE_SECRETS_BUNDLE;
-    if (!bundle)
+    const resolved = opts.secretsBundle
+        ? { name: opts.secretsBundle }
+        : resolveLeaseBundleMemo();
+    if (!resolved)
         return process.env;
     try {
-        // Reuse the same resolver `agents secrets exec` uses so a keychain-backed
-        // bundle (e.g. hetzner.com → HCLOUD_TOKEN) reaches crabbox without ever
-        // touching disk.
-        const { env } = readAndResolveBundleEnv(bundle, { caller: 'agents run --lease (crabbox)' });
+        // Auto-detected bundle → inject ONLY the provider token key(s) (least
+        // privilege; an unrelated bundle can't leak its other secrets into crabbox).
+        // An explicitly-named bundle (env/config or `opts.secretsBundle`) injects
+        // whole — the user chose it. Same resolver `agents secrets exec` uses.
+        const { env } = readAndResolveBundleEnv(resolved.name, {
+            caller: 'agents run --lease (crabbox)',
+            keys: resolved.keys,
+        });
         return { ...process.env, ...env };
     }
     catch (e) {
-        throw new Error(`Could not load secrets bundle "${bundle}" for crabbox: ${e.message}. ` +
-            `Fix the bundle (agents secrets view ${bundle}) or unset lease.secretsBundle to use crabbox's own login.`);
+        throw new Error(`Could not load secrets bundle "${resolved.name}" for crabbox: ${e.message}. ` +
+            `Fix the bundle (agents secrets view ${resolved.name}) or unset lease.secretsBundle to use crabbox's own login.`);
     }
 }
 function normalizeBox(raw) {
@@ -46,6 +121,12 @@ function normalizeBox(raw) {
     const status = String(raw.status ?? '');
     const state = String(labels.state ?? '');
     const publicNet = (raw.public_net ?? {});
+    const num = (v) => {
+        if (v === undefined || v === '')
+            return null;
+        const n = Number(v);
+        return Number.isFinite(n) ? n : null;
+    };
     return {
         name: String(raw.name ?? ''),
         status,
@@ -56,6 +137,11 @@ function normalizeBox(raw) {
         profile: labels.profile,
         class: labels.class,
         ready: status === 'running' && state === 'ready',
+        keep: labels.keep === 'true',
+        createdAt: num(labels.created_at),
+        expiresAt: num(labels.expires_at),
+        lastTouchedAt: num(labels.last_touched_at),
+        idleTimeoutSecs: num(labels.idle_timeout_secs ?? labels.idle_timeout),
     };
 }
 /** All crabbox machines the broker knows about. */
@@ -113,6 +199,24 @@ export async function crabboxWarmup(opts = {}) {
     });
     if (r.status !== 0) {
         const detail = (r.stderr || r.stdout || '').trim();
+        // A provider `server_limit` / `resource_limit_exceeded` 403 means the account's
+        // box quota is full. Turn the raw 403 into an actionable message that names the
+        // reap-safe orphans + the one-command fix, instead of a generic failure.
+        if (/server_limit|resource_limit_exceeded/i.test(detail)) {
+            let hint = ' Stop unused boxes (`crabbox list`) or raise your provider server limit.';
+            try {
+                const orphans = reapSafeOrphans(crabboxList(opts), Math.floor(Date.now() / 1000));
+                if (orphans.length) {
+                    hint =
+                        ` ${orphans.length} expired, idle box(es) are holding the quota — free them with ` +
+                            `\`agents lease gc\` (or \`crabbox stop ${orphans[0].slug}\`).`;
+                }
+            }
+            catch {
+                /* best-effort hint; fall back to the generic guidance above */
+            }
+            throw new Error(`crabbox warmup failed: provider server limit reached.${hint}`);
+        }
         throw new Error(`crabbox warmup failed: ${detail || 'unknown error'}. ` +
             `Check provider access with \`crabbox doctor\`; a missing cloud token often means \`crabbox login\` or a lease.secretsBundle is needed.`);
     }
@@ -229,3 +333,48 @@ export function crabboxStop(slug, opts = {}) {
         return false;
     }
 }
+/** Never reap a box touched within this many seconds, regardless of idle-timeout. */
+export const REAP_MIN_IDLE_SECS = 3600;
+/**
+ * Whether a box is a genuine orphan that is safe to reap.
+ *
+ * Reap-safe ONLY when BOTH hold: the lease has already expired (`expiresAt` in the
+ * past) AND the box has not been touched for a safety window of
+ * `max(2 × idleTimeout, 1h)`. The freshness guard is what makes this safe against
+ * a TOCTOU race: a box a concurrent run just reused (`cbx_acquire_box`) has a
+ * recent `lastTouchedAt` and is never eligible. Reaping by `profile`/`ready` alone
+ * — as `crabbox cleanup` cannot (it skips `keep=true`, which every real orphan is)
+ * — would kill in-use boxes. Boxes with unknown age (`expiresAt`/`lastTouchedAt`
+ * null) are never reaped. `nowSecs` is injected so tests don't wall-clock.
+ */
+export function isReapSafe(box, nowSecs) {
+    if (box.expiresAt === null || box.lastTouchedAt === null)
+        return false;
+    if (box.expiresAt > nowSecs)
+        return false;
+    const window = Math.max((box.idleTimeoutSecs ?? 0) * 2, REAP_MIN_IDLE_SECS);
+    return nowSecs - box.lastTouchedAt >= window;
+}
+/** The reap-safe orphans among `boxes`, most-stale (oldest touch) first. */
+export function reapSafeOrphans(boxes, nowSecs) {
+    return boxes
+        .filter((b) => isReapSafe(b, nowSecs))
+        .sort((a, b) => (a.lastTouchedAt ?? 0) - (b.lastTouchedAt ?? 0));
+}
+/**
+ * List reap-safe orphans and (unless `dryRun`) stop them. Returns the candidates
+ * considered and the slugs actually stopped. Best-effort per box — a stop failure
+ * is skipped, never thrown. Backs `agents lease gc` and the 403 auto-reap opt-in.
+ */
+export function reapOrphans(opts = {}) {
+    const nowSecs = opts.nowSecs ?? Math.floor(Date.now() / 1000);
+    const candidates = reapSafeOrphans(crabboxList(opts), nowSecs);
+    if (opts.dryRun)
+        return { candidates, reaped: [] };
+    const reaped = [];
+    for (const b of candidates) {
+        if (crabboxStop(b.slug, opts))
+            reaped.push(b.slug);
+    }
+    return { candidates, reaped };
+}

package/dist/lib/crabbox/runtimes.d.ts

@@ -47,6 +47,19 @@ export declare function pickRuntimes(detected: DetectedRuntime[], prompt?: (choi
     checked: boolean;
     disabled: boolean | string;
 }[]) => Promise<AgentId[]>): Promise<AgentId[]>;
+/**
+ * The lease runtime to provision for a headless run of `agentName`.
+ *
+ * When the agent is itself a lease-capable runtime (claude/codex/gemini/grok)
+ * that IS the runtime to install. Otherwise fall back to the single signed-in
+ * lease runtime (preferring claude), or null when none is signed in. This is the
+ * non-interactive replacement for the runtime checkbox picker: `--lease` requires
+ * a prompt, so it is headless by contract and must never block on a TTY.
+ *
+ * Profile-dispatch agents (kimi/deepseek) and custom workflow agents that run
+ * under a non-obvious runtime are resolved separately — see RUSH-1725.
+ */
+export declare function inferLeaseRuntime(agentName: string, detected: DetectedRuntime[]): AgentId | null;
 /**
  * Where Claude Code reads its OAuth token on the box. `.claude.json` (the file
  * LEASE_RUNTIMES copies) is config/account-metadata ONLY — the actual token