@phnx-labs/agents-cli 1.22.41 → 1.22.43

package/dist/lib/entitlement.d.ts

@@ -0,0 +1,31 @@
+/** How long a cached tier is trusted before the next call re-fetches. */
+export declare const ENTITLEMENT_CACHE_TTL_MS: number;
+export type EntitlementSource = 'live' | 'cache' | 'offline' | 'no-session';
+export interface EntitlementTier {
+    /** The raw tier name from the backend ('free', 'admin', or a paid tier name). */
+    tierName: string;
+    /** true for 'admin' or any tier name other than 'free'. */
+    isPaid: boolean;
+    /** Where this value came from — mainly for diagnostics/tests. */
+    source: EntitlementSource;
+}
+export declare function setEntitlementUserYamlPathForTest(value: string | null): void;
+export declare function setEntitlementCachePathForTest(value: string | null): void;
+export declare function setEntitlementFetchForTest(fn: typeof globalThis.fetch): void;
+export declare function entitlementCachePath(): string;
+/**
+ * The live plan tier, cache-first with a TTL.
+ *
+ * - No `~/.rush/user.yaml` at all → free, no network call.
+ * - A fresh cache entry (within {@link ENTITLEMENT_CACHE_TTL_MS}) is returned
+ *   with no network call.
+ * - A stale or missing cache triggers a live fetch; on success the result is
+ *   cached and returned.
+ * - A failed fetch (offline, timeout, non-2xx) falls back to a stale cache if
+ *   one exists — never silently drops a known-paid account to free just
+ *   because the network hiccuped — and only falls back to free when there is
+ *   no cache at all to fall back to.
+ */
+export declare function getTier(): Promise<EntitlementTier>;
+/** Per-harness account cap for a tier: 3 on free, 10 on paid/admin. */
+export declare function accountCapForTier(tier: Pick<EntitlementTier, 'isPaid'>): number;

package/dist/lib/entitlement.js

@@ -0,0 +1,137 @@
+/**
+ * Plan-tier entitlement — the one place agents-cli reads a user's live billing
+ * tier for plan gates (the `agents accounts` per-harness cap, the `agents
+ * insights` paid split). Fetches `GET /api/v1/billing/subscription?agent=agi-cli`
+ * using the Rush session token from `~/.rush/user.yaml` (same read pattern as
+ * `lib/cloud/rush.ts` / `lib/secrets/drivers/rush.ts` — this module does not
+ * import either, since neither exports its token reader), caches the result on
+ * disk with a TTL, and stays offline-tolerant: a stale cache is honored over a
+ * failed network call rather than silently dropping a paid account to free, and
+ * no session file at all resolves straight to the free tier with no request.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import * as yaml from 'yaml';
+import { getCacheDir } from './state.js';
+import { atomicWriteFileSync, ensureLockTarget, withFileLock } from './fs-atomic.js';
+const PROXY_BASE = process.env.RUSH_PROXY_BASE ?? 'https://api.prix.dev';
+const SUBSCRIPTION_PATH = '/api/v1/billing/subscription?agent=agi-cli';
+/** How long a cached tier is trusted before the next call re-fetches. */
+export const ENTITLEMENT_CACHE_TTL_MS = 15 * 60_000;
+/** Same shape as bootstrap.ts's fetchNpmPackageMetadata — a hung connection
+ * (dead peer, a firewall dropping packets silently) must not block every
+ * `accounts add`/`insights` call indefinitely once the cache goes stale. */
+const FETCH_TIMEOUT_MS = 5000;
+const FREE_TIER = { tierName: 'free', isPaid: false };
+// ─── Injectable seams (tests only — the lib's own real read/write paths) ────
+let userYamlPathOverride = null;
+let cachePathOverride = null;
+let fetchImpl = globalThis.fetch;
+export function setEntitlementUserYamlPathForTest(value) {
+    userYamlPathOverride = value;
+}
+export function setEntitlementCachePathForTest(value) {
+    cachePathOverride = value;
+}
+export function setEntitlementFetchForTest(fn) {
+    fetchImpl = fn;
+}
+function userYamlPath() {
+    return userYamlPathOverride ?? path.join(os.homedir(), '.rush', 'user.yaml');
+}
+export function entitlementCachePath() {
+    return cachePathOverride ?? path.join(getCacheDir(), '.entitlement-cache.json');
+}
+function readRushToken() {
+    const file = userYamlPath();
+    if (!fs.existsSync(file))
+        return null;
+    try {
+        const data = yaml.parse(fs.readFileSync(file, 'utf-8'));
+        return data?.session?.access_token || null;
+    }
+    catch {
+        return null;
+    }
+}
+function readCache() {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(entitlementCachePath(), 'utf-8'));
+        if (parsed?.version === 1 && typeof parsed.tierName === 'string' && typeof parsed.fetchedAt === 'number')
+            return parsed;
+    }
+    catch {
+        // missing or corrupt — treat as no cache
+    }
+    return null;
+}
+/** Best-effort write; a failed cache write just means the next call re-fetches. */
+function writeCache(tierName, isPaid) {
+    try {
+        const target = entitlementCachePath();
+        ensureLockTarget(target);
+        withFileLock(target, () => {
+            const entry = { version: 1, tierName, isPaid, fetchedAt: Date.now() };
+            atomicWriteFileSync(target, JSON.stringify(entry, null, 2));
+        });
+    }
+    catch {
+        // best-effort
+    }
+}
+/**
+ * Only `tierName: "free"` (or an absent tier name) reads as free — every other
+ * name (`admin`, or a real paid-tier name once agi-cli has a pricing manifest,
+ * see the integration spec §4.4 G3) is treated as paid. Backend tier config for
+ * agi-cli doesn't exist yet, so this deliberately does not lean on
+ * `hasSubscription`/`needsUpgrade` nuance the backend isn't populating meaningfully
+ * for this agent today.
+ */
+function classifySubscription(sub) {
+    const tierName = typeof sub.tierName === 'string' && sub.tierName ? sub.tierName : 'free';
+    return { tierName, isPaid: tierName !== 'free' };
+}
+/**
+ * The live plan tier, cache-first with a TTL.
+ *
+ * - No `~/.rush/user.yaml` at all → free, no network call.
+ * - A fresh cache entry (within {@link ENTITLEMENT_CACHE_TTL_MS}) is returned
+ *   with no network call.
+ * - A stale or missing cache triggers a live fetch; on success the result is
+ *   cached and returned.
+ * - A failed fetch (offline, timeout, non-2xx) falls back to a stale cache if
+ *   one exists — never silently drops a known-paid account to free just
+ *   because the network hiccuped — and only falls back to free when there is
+ *   no cache at all to fall back to.
+ */
+export async function getTier() {
+    const token = readRushToken();
+    if (!token)
+        return { ...FREE_TIER, source: 'no-session' };
+    const cached = readCache();
+    if (cached && Date.now() - cached.fetchedAt < ENTITLEMENT_CACHE_TTL_MS) {
+        return { tierName: cached.tierName, isPaid: cached.isPaid, source: 'cache' };
+    }
+    try {
+        const res = await fetchImpl(`${PROXY_BASE}${SUBSCRIPTION_PATH}`, {
+            headers: { Authorization: `Bearer ${token}` },
+            signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+        });
+        if (!res.ok)
+            throw new Error(`billing/subscription responded ${res.status}`);
+        const sub = (await res.json());
+        const { tierName, isPaid } = classifySubscription(sub);
+        writeCache(tierName, isPaid);
+        return { tierName, isPaid, source: 'live' };
+    }
+    catch {
+        if (cached)
+            return { tierName: cached.tierName, isPaid: cached.isPaid, source: 'offline' };
+        return { ...FREE_TIER, source: 'offline' };
+    }
+}
+/** Per-harness account cap for a tier: 3 on free, 10 on paid/admin. */
+export function accountCapForTier(tier) {
+    return tier.isPaid ? 10 : 3;
+}

package/dist/lib/exec.js

@@ -19,8 +19,7 @@ import { sanitizeProcessEnv } from './secrets/bundles.js';
 import { resolveActor, actorEnv } from './actor.js';
 import { expandLocalHome } from './project-root.js';
 import { getShimsDir, getHistoryDir, getRuntimeStateDir } from './state.js';
-import { resolveCodexHome } from './codex-home.js';
-import { readCodexConfiguredModel } from './shims.js';
+import { readCodexConfiguredModel } from './installations/shims.js';
 import { writePidSessionEntry, extractSessionIdArg } from './session/pid-registry.js';
 import { writeSessionActorRecord, writeSessionAliasRecord } from './session/actor-sidecar.js';
 import { loadHookSessionIndex, resolveHookSessionId } from './session/hook-sessions.js';
@@ -32,10 +31,14 @@ import { isTmuxInstalled } from './tmux/binary.js';
 import { isTmuxEnabled } from './device-config.js';
 import { machineId } from './machine-id.js';
 import { shellQuote } from './ssh-exec.js';
-import { resolveClaudeSetupToken } from './claude-account-token.js';
 import { codexEditWritableRoots, codexPolicyArgs } from './codex-policy.js';
+import { resolveClaudeSetupToken } from './claude-account-token.js';
 import { applyAddDirs } from './add-dir.js';
 import { applyActiveRulesPresetAtRun } from './rules/run-sync.js';
+import { resolveHarnessAdapter, stripForeignConfigDir } from './harness/index.js';
+import { resolveConfigVersion } from './harness/exec-config-version.js';
+import { getAccountInfo } from './agents.js';
+import { getUsageLookupKey, noteClaudeSessionLimit, parseClaudeSessionLimitReset } from './accounting/usage.js';
 /**
  * Map a raw mode string (CLI flag, YAML field, env var) to the canonical Mode.
  *
@@ -282,180 +285,25 @@ export function buildExecEnv(options) {
     // Config-dir env vars are agent-specific. When the caller is running inside
     // an agent-managed shell, process.env already carries one; spreading into a
     // different agent's env would leak a config pointer the target CLI doesn't
-    // understand. Strip foreign vars and pin the right one to the versioned home.
-    if (options.agent === 'claude') {
-        const cwd = options.cwd || process.cwd();
-        const resolvedVersion = options.version ?? resolveVersion('claude', cwd);
-        // Use an explicitly pinned version unconditionally; for auto-resolved versions
-        // only inject the path when the version is actually installed on disk.
-        const version = options.version
-            ? resolvedVersion
-            : (resolvedVersion && isVersionInstalled('claude', resolvedVersion) ? resolvedVersion : null);
-        // The per-account `claude setup-token` only resolves when there is a version
-        // home to key it to; version===null (claude unresolved / not installed) yields
-        // null, exactly as the routines path treats it (`runner.ts:1017-1021`). The
-        // token decision below runs even then, so an ambient inherited value is stripped
-        // on the routines/provisioned path regardless of whether a version resolved.
-        const versionHome = version ? getVersionHomePath('claude', version) : null;
-        const setupToken = versionHome ? resolveClaudeSetupToken(versionHome) : null;
-        if (versionHome) {
-            result.CLAUDE_CONFIG_DIR = path.join(versionHome, '.claude');
-            // A managed pin lives in a per-version dir; Claude Code's own background
-            // auto-updater would rewrite that pinned binary in place (and has left it
-            // half-swapped and broken). Disable it so a pin stays a pin. Honor an
-            // explicit user value — from process.env (already in result) or from
-            // options.env (spread over result below).
-            if (result.DISABLE_AUTOUPDATER === undefined) {
-                result.DISABLE_AUTOUPDATER = '1';
-            }
-        }
-        // The `auth` bundle's setup-token exists so a run with NO human present
-        // authenticates without the Touch-ID-gated login item — usage probes,
-        // routines, dispatched runs (claude-account-token.ts). An interactive run
-        // has a human at the TTY, and their own per-version login is the credential
-        // they established and expect; overriding it made `/status` report
-        // `Auth token: CLAUDE_CODE_OAUTH_TOKEN` on a personal machine and took every
-        // hand-driven session off that login. macOS cannot cheaply confirm a home's
-        // login first (probing the Keychain raises an authorization sheet per
-        // installed version on the `agents run` hot path — agents.ts
-        // `isClaudeCredentialFileBlank`), so interactive simply defers to Claude
-        // Code, which prompts a present human to log in if the login is missing.
-        if (resolveInteractive(options)) {
-            // Drop an INHERITED copy of OUR OWN setup-token: an interactive launch from
-            // inside a headless agent's shell inherits that agent's injected value via
-            // sanitizeProcessEnv(process.env) and would keep authenticating as it.
-            // Matched by VALUE, so a token the user exported deliberately is a different
-            // string and is left alone (#2383). This is NARROWER than the non-interactive
-            // path below, which overwrites-or-deletes unconditionally and never inspects
-            // the inherited value — a DIFFERENT account's inherited setup-token passing
-            // through this equality check is the adjacent hole RUSH-2360 leaves as
-            // follow-up (it does not silently run on a *shared, rotating* token, which is
-            // what caused the RUSH-1822 logout storm).
-            if (setupToken && result.CLAUDE_CODE_OAUTH_TOKEN === setupToken) {
-                delete result.CLAUDE_CODE_OAUTH_TOKEN;
-            }
-        }
-        else {
-            // Non-interactive (routines, dispatched, provisioned box): mirror the routines
-            // path (`runner.ts:1017-1021`) UNCONDITIONALLY. Inject the per-account
-            // setup-token when one resolves — it replaces any ambient shared value
-            // inherited from the launcher. When NONE resolves, STRIP the ambient
-            // CLAUDE_CODE_OAUTH_TOKEN so a run on a provisioned box can never silently
-            // authenticate as the shared, rotating token an earlier version of this path
-            // let through — the RUSH-1822 fleet-wide-logout hazard, tracked by RUSH-2360.
-            // A missing login then fails loud (401) against this home's own credential
-            // instead of quietly borrowing another's. options.env still wins below for an
-            // explicit caller override.
-            if (setupToken) {
-                result.CLAUDE_CODE_OAUTH_TOKEN = setupToken;
-            }
-            else {
-                delete result.CLAUDE_CODE_OAUTH_TOKEN;
-            }
-        }
-        delete result.CODEX_HOME;
-        delete result.COPILOT_HOME;
-        delete result.KIMI_CODE_HOME;
-    }
-    else if (options.agent === 'codex') {
-        const cwd = options.cwd || process.cwd();
-        const resolvedVersion = options.version ?? resolveVersion('codex', cwd);
-        const version = options.version
-            ? resolvedVersion
-            : (resolvedVersion && isVersionInstalled('codex', resolvedVersion) ? resolvedVersion : null);
-        if (version) {
-            // On macOS the deep versioned home overflows the Unix-socket SUN_LEN
-            // limit for codex's app-server control socket; resolve to a short,
-            // SUN_LEN-safe home (migrating once if needed). See codex-home.ts.
-            const versionedHome = path.join(getVersionHomePath('codex', version), '.codex');
-            const agentsUserDir = path.dirname(getHistoryDir());
-            result.CODEX_HOME = resolveCodexHome(versionedHome, agentsUserDir, version);
-        }
-        delete result.CLAUDE_CONFIG_DIR;
-        delete result.COPILOT_HOME;
-        delete result.KIMI_CODE_HOME;
-    }
-    else if (options.agent === 'copilot') {
-        // Copilot honors COPILOT_HOME (relocates ~/.copilot, including settings,
-        // mcp-config.json, sessions, logs). Pin it at the per-version home so
-        // version switches isolate MCP servers, auth, and session history.
-        const cwd = options.cwd || process.cwd();
-        const resolvedVersion = options.version ?? resolveVersion('copilot', cwd);
-        const version = options.version
-            ? resolvedVersion
-            : (resolvedVersion && isVersionInstalled('copilot', resolvedVersion) ? resolvedVersion : null);
-        if (version) {
-            result.COPILOT_HOME = path.join(getVersionHomePath('copilot', version), '.copilot');
-        }
-        delete result.CLAUDE_CONFIG_DIR;
-        delete result.CODEX_HOME;
-        delete result.KIMI_CODE_HOME;
-    }
-    else if (options.agent === 'kimi') {
-        // Kimi honors KIMI_CODE_HOME (relocates ~/.kimi-code, including config,
-        // skills, hooks, sessions). Pin it at the per-version home.
-        const cwd = options.cwd || process.cwd();
-        const resolvedVersion = options.version ?? resolveVersion('kimi', cwd);
-        const version = options.version
-            ? resolvedVersion
-            : (resolvedVersion && isVersionInstalled('kimi', resolvedVersion) ? resolvedVersion : null);
-        if (version) {
-            result.KIMI_CODE_HOME = path.join(getVersionHomePath('kimi', version), '.kimi-code');
-        }
-        delete result.CLAUDE_CONFIG_DIR;
-        delete result.CODEX_HOME;
-        delete result.COPILOT_HOME;
-    }
-    else if (options.agent === 'muse') {
-        // Muse has no MUSE_CONFIG_DIR. Config is XDG-based:
-        //   $XDG_CONFIG_HOME/muse  (settings, skills, hooks, auth)
-        //   $XDG_DATA_HOME/muse    (sessions, plugins)
-        // Pin both into the version home so multi-version isolation matches
-        // Claude's CLAUDE_CONFIG_DIR / Codex's CODEX_HOME, and so Muse never
-        // resolves through the adopt-time ~/.config/muse symlink (SymlinkOrReparse).
-        const cwd = options.cwd || process.cwd();
-        const resolvedVersion = options.version ?? resolveVersion('muse', cwd);
-        const version = options.version
-            ? resolvedVersion
-            : (resolvedVersion && isVersionInstalled('muse', resolvedVersion) ? resolvedVersion : null);
-        if (version) {
-            const versionHome = getVersionHomePath('muse', version);
-            result.XDG_CONFIG_HOME = path.join(versionHome, '.config');
-            result.XDG_DATA_HOME = path.join(versionHome, '.local', 'share');
-        }
-        delete result.CLAUDE_CONFIG_DIR;
-        delete result.CODEX_HOME;
-        delete result.COPILOT_HOME;
-        delete result.KIMI_CODE_HOME;
-    }
-    else if (options.agent === 'cursor') {
-        // Cursor has no config-dir env var (only CURSOR_API_KEY / CURSOR_API_ENDPOINT).
-        // Its OAuth token — the login gate — lives at $XDG_CONFIG_HOME/cursor/auth.json
-        // (verified empirically: relocating XDG_CONFIG_HOME relocates the login;
-        // ~/.cursor/cli-config.json holds only account metadata, not the token). Pin
-        // XDG_CONFIG_HOME into the version home so each installed Cursor account
-        // authenticates from its own token, isolated per run — no global ~/.cursor
-        // symlink swap, so concurrent runs on different accounts never clobber one
-        // another. cli-config.json (HOME-relative) has no override and stays on the
-        // shared home; only the token is per-account, which is what gates the login.
-        const cwd = options.cwd || process.cwd();
-        const resolvedVersion = options.version ?? resolveVersion('cursor', cwd);
-        const version = options.version
-            ? resolvedVersion
-            : (resolvedVersion && isVersionInstalled('cursor', resolvedVersion) ? resolvedVersion : null);
-        if (version) {
-            result.XDG_CONFIG_HOME = path.join(getVersionHomePath('cursor', version), '.config');
-        }
-        delete result.CLAUDE_CONFIG_DIR;
-        delete result.CODEX_HOME;
-        delete result.COPILOT_HOME;
-        delete result.KIMI_CODE_HOME;
+    // understand. Each harness adapter pins its own config-dir var to the versioned
+    // home and strips the foreign ones; a harness with no config-dir env (the old
+    // `else`) has no adapter override, so all four are stripped here.
+    const configAdapter = resolveHarnessAdapter(options.agent);
+    if (configAdapter.applyExecConfigEnv) {
+        // Resolve version/versionHome here (this module already imports
+        // installations/versions); the adapters must not import it themselves or they
+        // close a versions -> shims -> harness -> adapter import cycle.
+        const { version, versionHome } = resolveConfigVersion(options.agent, options.cwd || process.cwd(), options.version);
+        configAdapter.applyExecConfigEnv(result, {
+            agent: options.agent,
+            version,
+            versionHome,
+            interactive: resolveInteractive(options),
+            resolveClaudeSetupToken,
+        });
     }
     else {
-        delete result.CLAUDE_CONFIG_DIR;
-        delete result.CODEX_HOME;
-        delete result.COPILOT_HOME;
-        delete result.KIMI_CODE_HOME;
+        stripForeignConfigDir(result);
     }
     // Point the agent at its own mailbox so the PreToolUse `mailbox-inject` hook
     // knows which box to drain and inject mid-run. Keyed by the session id — the
@@ -952,18 +800,24 @@ export function buildExecCommand(options) {
         // AGENT_COMMANDS.modeFlags drifted apart. Tests assert they agree.
         throw new Error(`Internal error: ${options.agent} declares '${resolvedMode}' in capabilities.modes but has no entry in AGENT_COMMANDS.modeFlags.${resolvedMode}.`);
     }
-    if (options.agent === 'cursor' && resolvedMode === 'edit' && !interactive) {
-        // A configured headless run is the workspace trust decision. Keep this
-        // narrower than --yolo/-f, which also bypasses permission checks.
-        cmd.push('--trust');
+    // Launch-arg quirks (the harness axis of Move 3): cursor's additive `--trust`
+    // and the codex/kimi mode-flag overrides move to the harness adapter, so the
+    // per-agent name-chain collapses to one dispatch. The generic resume-subcommand
+    // and modeFlags paths stay here — they are not per-harness.
+    const launchAdapter = resolveHarnessAdapter(options.agent);
+    const launchArgsCtx = {
+        resolvedMode,
+        interactive,
+        cwd: options.cwd ?? process.cwd(),
+        addDirs: (options.addDirs ?? []).map(expandLocalHome),
+    };
+    const preModeArgs = launchAdapter.execPreModeArgs?.(launchArgsCtx);
+    if (preModeArgs) {
+        cmd.push(...preModeArgs);
     }
-    if (options.agent === 'codex') {
-        const policyMode = resolvedMode === 'plan' || resolvedMode === 'skip' ? resolvedMode : 'edit';
-        const writableRoots = [
-            ...codexEditWritableRoots(options.cwd ?? process.cwd()),
-            ...(options.addDirs ?? []).map(expandLocalHome),
-        ];
-        cmd.push(...codexPolicyArgs(policyMode, writableRoots));
+    const modeArgsOverride = launchAdapter.execModeArgs?.(launchArgsCtx);
+    if (modeArgsOverride !== undefined) {
+        cmd.push(...modeArgsOverride);
     }
     else if (resumeSpec && 'subcommand' in resumeSpec) {
         if (resolvedMode === 'skip') {
@@ -982,21 +836,6 @@ export function buildExecCommand(options) {
             cmd.push(...modeFlags);
         }
     }
-    else if (options.agent === 'kimi' && !interactive) {
-        // kimi's headless prompt mode (`-p`/`--prompt`) is self-contained and REFUSES
-        // to be combined with any startup-mode flag: `--plan`, `--auto`, and `--yolo`
-        // all abort with "Cannot combine --prompt with --X" (verified against the live
-        // kimi CLI). The write-capable modes (edit/auto/skip) all collapse to kimi's
-        // default `-p` behavior, which already auto-approves tool calls, so we emit no
-        // mode flag. Plan can't reach here headless — resolveHeadlessMode already
-        // downgraded it to auto (kimi's headlessPlan:false); this asserts that
-        // invariant so a plan-mode run can never silently mutate the workspace.
-        if (resolvedMode === 'plan') {
-            throw new Error(`Internal error: kimi reached headless command build with resolved mode 'plan'; ` +
-                `resolveHeadlessMode should have downgraded it to auto (capabilities.headlessPlan is false).`);
-        }
-        // edit/auto/skip: emit no mode flag — `kimi -p` auto-runs.
-    }
     else {
         cmd.push(...modeFlags);
     }
@@ -1228,7 +1067,7 @@ export async function execShimPassthrough(agent, rawArgs, cwd, pinnedVersion) {
     // not parse `rawArgs`, so a `-p "task"` passthrough is headless in fact and
     // interactive by this classification, and loses the token. Windows-only in
     // practice (POSIX uses the bash shim, which execs the binary and never reaches
-    // buildExecEnv — `shims.ts:749`, `shims.ts:761-764`).
+    // buildExecEnv — `installations/shims.ts` generateShimScript).
     const env = buildExecEnv({ agent, version, cwd, mode: defaultModeFor(agent), effort: 'auto', env: { AGENT_LAUNCH_ID: launchId } });
     const { command, args, shell } = resolveShimSpawn(process.platform, binary, [...launchArgs, ...rawArgs]);
     return new Promise((resolve) => {
@@ -2246,12 +2085,20 @@ export async function runWithFallback(options) {
             }
             throw err;
         }
-        if (result.exitCode === 0)
+        const output = `${result.stderr}\n${result.stdout}`;
+        const sessionLimitReset = agent === 'claude' ? parseClaudeSessionLimitReset(output) : null;
+        if (sessionLimitReset && version) {
+            const account = await getAccountInfo(agent, getVersionHomePath(agent, version));
+            const usageKey = getUsageLookupKey(account);
+            if (usageKey)
+                noteClaudeSessionLimit(usageKey, sessionLimitReset);
+        }
+        if (result.exitCode === 0 && !sessionLimitReset)
             return 0;
         const isLast = i === chain.length - 1;
         if (isLast)
-            return result.exitCode;
-        if (!detectRateLimit(result.stderr) && !detectRateLimit(result.stdout)) {
+            return result.exitCode || 1;
+        if (!sessionLimitReset && !detectRateLimit(result.stderr) && !detectRateLimit(result.stdout)) {
             return result.exitCode;
         }
         const next = chain[i + 1];

package/dist/lib/feed/feed.js

@@ -28,6 +28,7 @@ import { stringifyDoc } from '../yaml-io.js';
 import { getFeedDir, getUserAgentsDir } from '../state.js';
 import { isAdmin, isHighConsequenceAllowed, isKnownOperator } from '../operator.js';
 import { projectKeyFromCwd } from '../project-key.js';
+import { atomicWriteJsonSync } from '../fs-atomic.js';
 /**
  * Stable block id for a session. One block per session -- a new question
  * replaces the previous one (the agent can only ask one question at a time).
@@ -56,11 +57,6 @@ function safeReadJson(file) {
         return undefined;
     }
 }
-function atomicWriteJson(file, value) {
-    const tmp = `${file}.${process.pid}.tmp`;
-    fs.writeFileSync(tmp, JSON.stringify(value, null, 2), 'utf-8');
-    fs.renameSync(tmp, file);
-}
 /** Read one block record. Returns undefined when missing or corrupt. */
 export function readBlock(blockId, root) {
     const parsed = safeReadJson(blockPath(root ?? getFeedDir(), blockId));
@@ -285,9 +281,7 @@ export function publishBlock(block, root) {
     const dir = root ?? getFeedDir();
     fs.mkdirSync(dir, { recursive: true });
     const target = blockPath(dir, block.blockId);
-    const tmp = `${target}.${process.pid}.tmp`;
-    fs.writeFileSync(tmp, JSON.stringify(block, null, 2), 'utf-8');
-    fs.renameSync(tmp, target);
+    atomicWriteJsonSync(target, block);
 }
 /** Read all block records. Returns them sorted by stable block filename. */
 export function listBlocks(root) {

package/dist/lib/format.d.ts

@@ -27,6 +27,15 @@ export declare function formatDie(msg: string, opts?: DieOptions): {
  * keep the original red-stderr behavior.
  */
 export declare function die(msg: string, code?: number, opts?: DieOptions): never;
+/**
+ * Await a command action and turn a thrown Error into a clean `die(message)`
+ * instead of Node's raw stack dump — bootstrap's parseAsync catch deliberately
+ * rethrows plain Errors as engineering bugs, so a command whose helpers throw
+ * user-actionable errors (auth, org) wraps its `.action(...)` call site with
+ * this. The helpers keep throwing so tests can assert on them. Pass `json`
+ * so a `--json` caller still gets the structured `{"error"}` payload.
+ */
+export declare function runOrDie(fn: () => void | Promise<void>, opts?: DieOptions): Promise<void>;
 /**
  * `die()` with a structured friction event attached. Use this at CLI error
  * chokepoints so the nightly routine can classify and rank recurring failures

package/dist/lib/format.js

@@ -44,6 +44,22 @@ export function die(msg, code = 1, opts = {}) {
         console.error(text);
     process.exit(code);
 }
+/**
+ * Await a command action and turn a thrown Error into a clean `die(message)`
+ * instead of Node's raw stack dump — bootstrap's parseAsync catch deliberately
+ * rethrows plain Errors as engineering bugs, so a command whose helpers throw
+ * user-actionable errors (auth, org) wraps its `.action(...)` call site with
+ * this. The helpers keep throwing so tests can assert on them. Pass `json`
+ * so a `--json` caller still gets the structured `{"error"}` payload.
+ */
+export async function runOrDie(fn, opts = {}) {
+    try {
+        await fn();
+    }
+    catch (err) {
+        die(err instanceof Error ? err.message : String(err), 1, opts);
+    }
+}
 /**
  * `die()` with a structured friction event attached. Use this at CLI error
  * chokepoints so the nightly routine can classify and rank recurring failures

package/dist/lib/fs-atomic.d.ts

@@ -11,6 +11,13 @@ export declare function ensureLockTarget(filePath: string, initialContent?: stri
  * partial write. On POSIX, rename(2) is atomic.
  */
 export declare function atomicWriteFileSync(filePath: string, content: string, options?: fs.WriteFileOptions): void;
+/**
+ * Convenience wrapper around {@link atomicWriteFileSync} for the common case of
+ * writing pretty-printed JSON (RUSH-2840). Same tmp-then-rename mechanics, same
+ * caller responsibility to ensure the parent directory exists first — this adds
+ * only the `JSON.stringify`.
+ */
+export declare function atomicWriteJsonSync(filePath: string, data: unknown): void;
 /**
  * Acquires an exclusive proper-lockfile lock on filePath, runs fn, then
  * releases the lock. Retries with capped linear back-off until either the lock

package/dist/lib/fs-atomic.js

@@ -55,6 +55,15 @@ export function atomicWriteFileSync(filePath, content, options = 'utf-8') {
         throw err;
     }
 }
+/**
+ * Convenience wrapper around {@link atomicWriteFileSync} for the common case of
+ * writing pretty-printed JSON (RUSH-2840). Same tmp-then-rename mechanics, same
+ * caller responsibility to ensure the parent directory exists first — this adds
+ * only the `JSON.stringify`.
+ */
+export function atomicWriteJsonSync(filePath, data) {
+    atomicWriteFileSync(filePath, JSON.stringify(data, null, 2));
+}
 export function withFileLock(filePath, fn, opts = {}) {
     let release = null;
     let lastError;

package/dist/lib/github/pr-mergeable.d.ts

@@ -0,0 +1,49 @@
+/**
+ * List this user's mergeable PRs across registered project repos.
+ *
+ * The built-in `pr-merge-on-green` monitor used to run `gh pr list --author @me`
+ * with no `--repo`. `gh` then infers the repository from the working directory,
+ * and the daemon's cwd is not a git repo, so every poll returned empty.
+ *
+ * This helper:
+ *   1. Collects GitHub slugs from `~/.agents/projects/*.yaml` (`repo` / `repos[].slug`).
+ *   2. Canonicalizes each slug (`gh repo view` — `phnx-labs/agents-cli` lists
+ *      nothing; the live name is `phnx-labs/agi-cli`).
+ *   3. Runs `gh pr list --repo <slug> --author @me` (cwd-independent).
+ *   4. Keeps CI-green PRs with a merge-guard verdict (formal APPROVED review
+ *      OR an APPROVE comment on THIS PR).
+ *
+ * Stdout is a single line of `owner/repo#n` refs (or empty). Empty is a silent
+ * observation under `condition.mode: every` — do not write to stderr on the
+ * no-match path, or command.ts will treat stderr as the observation and fire.
+ */
+import { type ProjectDef } from '../projects.js';
+import { type MergeablePrInput, type StatusCheck } from './pr-verdict.js';
+export type GhExec = (args: string[]) => Promise<string>;
+/** Default runner: `gh` with a 30s timeout. Non-zero exit throws. */
+export declare function ghExec(args: string[]): Promise<string>;
+/** Unique GitHub slugs declared on project definitions. */
+export declare function projectRepoSlugs(defs: readonly ProjectDef[]): string[];
+/**
+ * Resolve a slug to GitHub's current `nameWithOwner`. A renamed repo
+ * (`phnx-labs/agents-cli` → `phnx-labs/agi-cli`) lists zero PRs under the old
+ * name; `gh repo view` returns the live one. On error, keep the input slug.
+ */
+export declare function canonicalizeRepo(slug: string, gh: GhExec): Promise<string>;
+interface ListedPr {
+    number: number;
+    reviewDecision?: string | null;
+    statusCheckRollup?: StatusCheck[] | null;
+}
+/**
+ * Given PRs already listed for one repo, attach verdict payloads only for the
+ * CI-green ones that lack a formal APPROVED reviewDecision, then select.
+ */
+export declare function selectListedMergeable(repo: string, listed: readonly ListedPr[], gh: GhExec): Promise<MergeablePrInput[]>;
+/** List mergeable `owner/repo#n` refs, space-separated. Empty string if none. */
+export declare function listMergeableRefs(opts?: {
+    gh?: GhExec;
+    defs?: ProjectDef[];
+    repos?: string[];
+}): Promise<string>;
+export {};