@phnx-labs/agents-cli 1.22.42 → 1.22.44

package/dist/commands/sync.js

@@ -3,6 +3,7 @@
  *
  * Forms:
  *   agents sync                                         # umbrella: fetch config repos -> reconcile all (secrets opt-in)
+ *   agents sync status                                  # report fleet drift (former top-level `agents status`)
  *   agents sync --repos|--secrets                       # umbrella: fetch only those, then reconcile
  *   agents sync --cloud                                 # umbrella: fetch all, skip reconcile
  *   agents sync --local                                 # umbrella: reconcile all, no fetch
@@ -34,7 +35,7 @@ import { Option } from 'commander';
 import chalk from 'chalk';
 import { resolveSyncPassphraseFromEnv } from '../lib/secrets/sync-passphrase.js';
 import { agentLabel, resolveAgentName, MANAGED_AGENT_IDS, isAgentHardDeprecated, hardDeprecationError } from '../lib/agents.js';
-import { isVersionInstalled, syncResourcesToVersion, parseAgentSpec, resolveVersion, resolveVersionAlias, listInstalledVersions, getAvailableResources, getActuallySyncedResources, getProjectOnlyResources, getNewResources, hasNewResources, promptResourceSelection, promptNewResourceSelection, buildSelection, mergeRepoScopedSelections, listRepoNames, getVersionHomePath, } from '../lib/installations/versions.js';
+import { isVersionInstalled, syncResourcesToVersion, parseAgentSpec, resolveVersion, resolveVersionAlias, listInstalledVersions, healDanglingVersionPointers, getAvailableResources, getActuallySyncedResources, getProjectOnlyResources, getNewResources, hasNewResources, promptResourceSelection, promptNewResourceSelection, buildSelection, mergeRepoScopedSelections, listRepoNames, getVersionHomePath, } from '../lib/installations/versions.js';
 import { capableAgents } from '../lib/capabilities.js';
 import { parseHookManifest, registerHooksToSettings } from '../lib/hooks/install.js';
 import { compileRulesForProject } from '../lib/rules/compile.js';
@@ -45,6 +46,7 @@ import { runUmbrellaSync } from '../lib/sync-umbrella.js';
 import { addHostOption } from '../lib/hosts/option.js';
 import { syncRepoGit } from '../lib/git.js';
 import { getSystemAgentsDir, getUserAgentsDir, getEnabledExtraRepos } from '../lib/state.js';
+import { registerStatusCommand } from './status.js';
 /** Emit one JSON object to stdout for `--json` callers / fleet fan-out. */
 function emitJson(payload) {
     console.log(JSON.stringify(payload));
@@ -134,7 +136,7 @@ export function addSelectorOptions(cmd) {
 export function registerSyncCommand(program) {
     const cmd = addHostOption(program.command('sync [agentSpec] [repo]'))
         .summary('Make this machine current, or sync resources into one agent')
-        .description('With an [agentSpec], syncs resources (commands, skills, hooks, rules, MCPs, plugins, etc.) into that installed agent version — previews changes and lets you pick. e.g. "claude", "claude@2.1.142", a selector: @latest / @oldest / @pinned (= @default), or @all for every installed version.\n\nAppend a [repo] (or pass --repo) to scope the sync to a single DotAgent repo — system / user / project / <alias>. e.g. "agents sync claude@all system" reconciles only the system repo\'s resources into every installed Claude.\n\nGive a DotAgent repo name ALONE — "agents sync system" / "agents sync user" / "agents sync <alias>" — to git-sync that one repo: git pull --rebase against origin when the tree is clean; when it is dirty, fast-forward anyway if no incoming path is uncommitted, else refuse and name what collided. The user repo and extra aliases also push local commits up; the system repo is a pull-only mirror.\n\nWith NO agent, runs the umbrella verb: fetch the config repos then reconcile them into every installed agent. Secrets are opt-in — add --secrets to pull secret bundles. Session transcripts are queryable live via "agents sessions --device <machine>", or moved with "agents sessions export/import". Also: --cloud (fetch only), --local (reconcile only).')
+        .description('With an [agentSpec], syncs resources (commands, skills, hooks, rules, MCPs, plugins, etc.) into that installed agent version — previews changes and lets you pick. e.g. "claude", "claude@2.1.142", a selector: @latest / @oldest / @pinned (= @default), or @all for every installed version.\n\nAppend a [repo] (or pass --repo) to scope the sync to a single DotAgent repo — system / user / project / <alias>. e.g. "agents sync claude@all system" reconciles only the system repo\'s resources into every installed Claude.\n\nGive a DotAgent repo name ALONE — "agents sync system" / "agents sync user" / "agents sync <alias>" — to git-sync that one repo: git pull --rebase against origin when the tree is clean; when it is dirty, fast-forward anyway if no incoming path is uncommitted, else refuse and name what collided. The user repo and extra aliases also push local commits up; the system repo is a pull-only mirror.\n\nWith NO agent, runs the umbrella verb: fetch the config repos then reconcile them into every installed agent. Secrets are opt-in — add --secrets to pull secret bundles. Session transcripts are queryable live via "agents sessions --device <machine>", or moved with "agents sessions export/import". Also: --cloud (fetch only), --local (reconcile only).\n\n`agents sync status` reports fleet drift (what is drifted, missing, or behind) and can reconcile it — the former top-level `agents status`.')
         .option('--agent <agent>', 'Agent identifier (legacy form; prefer the positional spec)')
         .option('--agent-version <version>', 'Version to sync into (legacy form; prefer "agent@version" or --version)')
         .option('--repo <name>', 'Scope the sync to a single DotAgent repo: system / user / project / <alias> (also accepted as a positional)')
@@ -158,6 +160,8 @@ export function registerSyncCommand(program) {
     // Per-kind resource selectors + --version. Registered after the main flags so
     // help output groups the positional/repo/agent flags first.
     addSelectorOptions(cmd);
+    // `status` is a reserved subcommand (not an agentSpec/repo positional).
+    registerStatusCommand(cmd);
 }
 /**
  * Resolve a DotAgent repo name to its git working directory + whether local
@@ -507,6 +511,27 @@ async function runSync(agentSpec, repoArg, opts) {
     const projectDir = opts.projectDir;
     const cwd = opts.cwd || process.cwd();
     const force = !!opts.force;
+    // RUSH-2471: self-heal any version pointer (global/isolated default, ~/.<agent>
+    // symlink) left aimed at a version that is no longer installed BEFORE resolving
+    // the version to sync. Skipped on --dry-run since it mutates on-disk pointers.
+    let healed = {};
+    if (!opts.dryRun) {
+        healed = await healDanglingVersionPointers(agentId, cwd);
+        if (!quiet && !json) {
+            if (healed.globalDefault) {
+                const to = healed.globalDefault.to ? `@${healed.globalDefault.to}` : 'none';
+                outLog(chalk.yellow(`Reassigned ${agentLabel(agentId)} default from @${healed.globalDefault.from} (not installed) to ${to}.`));
+            }
+            if (healed.isolatedDefault) {
+                const to = healed.isolatedDefault.to ? `@${healed.isolatedDefault.to}` : 'none';
+                outLog(chalk.yellow(`Reassigned ${agentLabel(agentId)} isolated default from @${healed.isolatedDefault.from} (not installed) to ${to}.`));
+            }
+            if (healed.configSymlink) {
+                outLog(chalk.yellow(`Repointed ${agentLabel(agentId)} config symlink from @${healed.configSymlink.from} (not installed) to @${healed.configSymlink.to}.`));
+            }
+        }
+    }
+    const healedPointers = Object.keys(healed).length > 0 ? { healedPointers: healed } : {};
     // Promote to @all when no version can be resolved and multiple are installed.
     // Replaces the old "no default version pinned" error: bare `agents sync claude`
     // with multiple installed versions and no pinned default now syncs them all.
@@ -582,6 +607,7 @@ async function runSync(agentSpec, repoArg, opts) {
                 mode: 'agent-all',
                 agent: agentId,
                 repo: repoScope,
+                ...healedPointers,
                 versions: versions.map(({ version: v, result }) => ({
                     version: v,
                     commands: !!result.commands,
@@ -786,6 +812,7 @@ async function runSync(agentSpec, repoArg, opts) {
     if (json) {
         emitJson({
             ...agentSyncJson(agentId, version, result),
+            ...healedPointers,
             projectCompile: projectCompile
                 ? {
                     compiled: !!projectCompile.compiled,

package/dist/commands/view.js

@@ -1241,6 +1241,8 @@ export function parseResourceSections(options, jsonMode) {
  */
 export async function collectAgentsJson(filterAgentId, resourceSections) {
     const agentsToShow = filterAgentId ? [filterAgentId] : ALL_AGENT_IDS;
+    const authCache = readAuthHealthCache();
+    const host = machineId();
     const wantResources = !!resourceSections && resourceSections.size > 0;
     // Only pay for the git-status + resource scans when resources were requested.
     const resourceSync = wantResources ? await loadResourceSyncData() : null;
@@ -1293,6 +1295,7 @@ export async function collectAgentsJson(filterAgentId, resourceSections) {
             isolated: isVersionIsolated(agentId, version),
             isIsolatedDefault: getIsolatedDefault(agentId) === version,
             signedIn: info.signedIn,
+            authVerdict: authCache[authCacheKey(host, agentId, version)]?.verdict ?? null,
             email: info.email,
             accountId: info.accountId,
             organizationType: info.organizationType ?? null,
@@ -1308,6 +1311,12 @@ export async function collectAgentsJson(filterAgentId, resourceSections) {
                     resetsAt: w.resetsAt ? w.resetsAt.toISOString() : null,
                 }))
                 : [],
+            unavailable: snapshot?.unavailable
+                ? {
+                    reason: snapshot.unavailable.reason,
+                    resetsAt: snapshot.unavailable.resetsAt.toISOString(),
+                }
+                : undefined,
             lastActive: info.lastActive ? info.lastActive.toISOString() : null,
             path: getVersionDir(agentId, version),
             configuredModel: resolveConfiguredModel(agentId, version),
@@ -1734,8 +1743,8 @@ Output:
   - With agent name: versions for that agent, showing which is the default
   - With a custom harness name: that harness's host, model, provider, and auth
   - With agent@version: detailed breakdown of resources synced to that version
-  - With --json: structured JSON with version, isDefault, signedIn, email, plan,
-    usageStatus, per-window usedPercent, lastActive, and path
+  - With --json: structured JSON with version, isDefault, signedIn, authVerdict,
+    email, plan, usageStatus, per-window usedPercent, lastActive, and path
   - With --prune: plan of which older versions will be removed, then confirm
   - With --prune --dry-run: preview only, no deletions
 `)

package/dist/commands/webhook.js

@@ -85,7 +85,7 @@ export function registerWebhooksCommand(program) {
             const address = server.address();
             const bound = typeof address === 'object' && address ? address.port : port;
             console.log(`${chalk.green('agents webhooks')} ${chalk.dim('→')} ${chalk.cyan(`http://${opts.bind ?? DEFAULT_HOST}:${bound}`)}`);
-            console.log(chalk.dim('signed · localhost by default · endpoints: /hooks/github, /hooks/linear · acks 202 then dispatches · Ctrl-C to stop'));
+            console.log(chalk.dim('signed · localhost by default · endpoints: /hooks/github, /hooks/linear, /hooks/slack · acks 202 then dispatches · Ctrl-C to stop'));
             console.log(chalk.dim('for a supervised receiver that survives reboot: agents daemon webhooks add --secrets-bundle <name>'));
             const shutdown = () => {
                 server.close(() => process.exit(0));

package/dist/lib/accounting/rotate.d.ts

@@ -58,9 +58,11 @@ export interface RotateResult {
     /** Candidates excluded (not signed in, or out of credits). */
     excluded: RotateCandidate[];
     /**
-     * True when NO candidate on this machine had usage data fresh enough to decide
-     * on, so the pick was made from unverified snapshots. Callers surface it —
-     * routing blind is a fact the operator needs, not an internal detail.
+     * True when the PICKED candidate's usage could not be verified fresh, so the
+     * route was decided on an unverified snapshot. Callers surface it — routing
+     * blind is a fact the operator needs, not an internal detail. (Previously
+     * this only reported the all-stale case; a stale pick out of a mixed pool
+     * was silently reported as verified.)
      */
     usageUnverified?: boolean;
 }

package/dist/lib/accounting/rotate.js

@@ -122,7 +122,7 @@ export function isUsageVerified(candidate, nowMs = Date.now()) {
 }
 function hasUsageAvailable(candidate) {
     const snapshot = candidate.usageSnapshot;
-    if (snapshot && snapshot.windows.length > 0) {
+    if (snapshot) {
         // Eligibility mirrors the `agents view` throttle badge exactly
         // (deriveUsageStatusFromSnapshot): an account maxed on ANY blocking window —
         // including the 5-hour session window — cannot serve the next request, so it
@@ -131,7 +131,9 @@ function hasUsageAvailable(candidate) {
         // stayed "eligible" and the router kept launching into it while `ag view`
         // showed it rate-limited. Capacity *weighting* still ranks eligible accounts
         // by weekly headroom; this gate only decides can-it-run-right-now.
-        return deriveUsageStatusFromSnapshot(snapshot) !== 'rate_limited';
+        const status = deriveUsageStatusFromSnapshot(snapshot);
+        if (status !== null)
+            return status !== 'rate_limited';
     }
     // No live snapshot: fall back to the coarse cached status.
     if (candidate.usageStatus === 'out_of_credits' || candidate.usageStatus === 'rate_limited') {
@@ -300,11 +302,12 @@ export function pickBalancedCandidate(candidates, nowMs = Date.now()) {
         if (!deduped.has(c))
             excluded.push(c);
     }
-    const { picked, usageUnverified } = preferVerified(sorted, nowMs, weightedRandomByCapacity);
+    const { picked, usageUnverified } = preferVerified(sorted, nowMs, weightedRandomByCapacity, 'representative');
     return { picked, healthy: sorted, excluded, usageUnverified };
 }
 /**
- * Choose from the VERIFIED candidates when any exist, else from the whole pool.
+ * Choose from the VERIFIED candidates when they are a representative share of
+ * the pool (at least half), else from the whole pool.
  *
  * An eligible account whose usage we could not confirm is a guess, not a green
  * light: the snapshot reads "48% used" with equal confidence whether it was
@@ -312,6 +315,29 @@ export function pickBalancedCandidate(candidates, nowMs = Date.now()) {
  * wrong indefinitely. Confirmed headroom therefore beats apparent headroom, even
  * when the unconfirmed number looks better.
  *
+ * But narrowing to a verified MINORITY inverts the safety. When the usage
+ * endpoint 429-throttles a machine, each refresh cycle confirms roughly one
+ * account before backing off — so "verified" is a singleton, `choose` runs over
+ * a one-element list, and every launch lands on the same account. Launching
+ * into it refreshes that account's snapshot again, so it stays the only
+ * verified candidate while the rest are never picked and never probed: the
+ * rotation degrades to a fixed pin that burns one account to its weekly cap
+ * while its siblings idle (observed 2026-08-20 across yosemite-s0/s1 — the
+ * "same version every time under --strategy balanced" incident).
+ *
+ * The two failure modes belong to different CHOOSERS, so `narrowing` is picked
+ * per caller: `'representative'` (the weighted-random balanced path) narrows to
+ * verified only when they cover at least half the pool — below that the whole
+ * pool competes, fresh candidates keep their confirmed weights, stale/unknown
+ * ones get the full default weight `capacityWeight` assigns to "no signal", and
+ * the random roll spreads the load. `'any-verified'` (deterministic `from[0]`
+ * choosers: `--strategy available`, run-auto harness classification) keeps the
+ * original rule — narrow whenever ANY verified candidate exists — because a
+ * deterministic pick over the whole pool would hand the front slot back to an
+ * unconfirmed "48% used" over an accurate "90% used", the exact yosemite-s1
+ * inversion above, and a deterministic chooser cannot spread load anyway, so
+ * the singleton-collapse concern does not apply to it.
+ *
  * `healthy` deliberately keeps every eligible candidate rather than just the
  * verified ones. Declining to *pick* an account on stale data and declining to
  * *fail over to* it after the primary has already hit a 429 are different risks:
@@ -319,11 +345,14 @@ export function pickBalancedCandidate(candidates, nowMs = Date.now()) {
  * (rotationFailoverChain, which reads `healthy`) keeps its full safety net —
  * exactly on the machines this guard is protecting.
  */
-function preferVerified(pool, nowMs, choose) {
+function preferVerified(pool, nowMs, choose, narrowing = 'any-verified') {
     const verified = pool.filter((c) => isUsageVerified(c, nowMs));
+    const narrow = verified.length > 0 &&
+        (narrowing === 'any-verified' || verified.length >= Math.ceil(pool.length / 2));
+    const picked = choose(narrow ? verified : pool);
     return {
-        picked: choose(verified.length > 0 ? verified : pool),
-        usageUnverified: verified.length === 0,
+        picked,
+        usageUnverified: !isUsageVerified(picked, nowMs),
     };
 }
 /**

package/dist/lib/accounting/usage.d.ts

@@ -91,6 +91,11 @@ export interface UsageSnapshot {
     capturedAt: Date | null;
     windows: UsageWindow[];
     plan?: string | null;
+    /** A refusal observed from a real harness run, independent of API windows. */
+    unavailable?: {
+        reason: 'session_limit';
+        resetsAt: Date;
+    };
 }
 /** Usage data plus any error encountered while fetching. */
 export interface UsageInfo {
@@ -464,7 +469,6 @@ export declare function normalizeDroidWindows(data: DroidBillingLimitsResponse):
  *     the Claude CLI stores its OAuth token in this plaintext file instead. The
  *     keychain read above finds nothing on that platform, so we fall back to the
  *     file. Same wrapped `{ claudeAiOauth }` shape, so one parser handles both.
- *     Mirrors `readClaudeCredentialsBlob` (cloud/rush.ts), the proven pattern.
  *
  * Without step 2 the live usage fetch got no token on Linux, so `agents view`
  * (run remotely over SSH by `--device`) rendered no usage bars even though the
@@ -476,9 +480,10 @@ export declare function normalizeDroidWindows(data: DroidBillingLimitsResponse):
  * reads Claude Code's interactive login (transmitting that ACL-bound OAuth token
  * to Anthropic's API is what gets it revoked; see the branch body and
  * docs/credential-management.md). It is OFF by default so full-credential
- * callers that refresh (`isClaudeAuthValid` -> `getClaudeAccessToken`) or export
- * the full blob (`readClaudeCredentialsBlob` for Rush Cloud dispatch) still read
- * the interactive login.
+ * callers that refresh (`isClaudeAuthValid` -> `getClaudeAccessToken`) still
+ * read the interactive login. Rush Cloud dispatch does not call this helper
+ * at all (SING-1b: the account manifest is email-only; RUSH-2359 removed the
+ * leftover blob reader that used to send the interactive login).
  *
  * `opts.fileOnly` skips the ACL keychain read entirely — setup-token and
  * `.credentials.json` only. Used by the daemon usage refresher so a background
@@ -506,8 +511,17 @@ export declare function getClaudeKeychainService(home?: string): string;
 export declare function isClaudeUsageOrgMatch(requestedOrgId: string | null | undefined, liveOrgId: string | null | undefined): boolean;
 /** Read a cached usage snapshot for a given usage key. Returns null if absent or stale. */
 export declare function readClaudeUsageCache(usageKey: string, cachePath?: string, now?: Date): UsageSnapshot | null;
+/** Delete an expired cache row only if it is still expired under the write lock. */
+export declare function pruneExpiredClaudeUsageCacheEntry(usageKey: string, cachePath?: string, now?: Date): void;
 /** Write a usage snapshot to the on-disk cache. */
 export declare function writeClaudeUsageCache(usageKey: string, snapshot: UsageSnapshot, cachePath?: string): void;
+/**
+ * Persist a Claude session-limit refusal from a real run until its stated reset.
+ * This quota is not part of Anthropic's five-hour/weekly usage response.
+ */
+export declare function noteClaudeSessionLimit(usageKey: string, resetsAt: Date, cachePath?: string): void;
+/** Parse Claude's `hit your session limit · resets …` refusal. */
+export declare function parseClaudeSessionLimitReset(text: string, nowMs?: number): Date | null;
 /**
  * Check whether the Claude OAuth credentials for a given home are usable.
  * Attempts a token refresh if the access token is expired.

package/dist/lib/accounting/usage.js

@@ -398,6 +398,9 @@ export function formatUsageSummary(plan, snapshot, planWidth = 3, opts) {
         parts.push(chalk.gray(plan.padEnd(planWidth)));
     }
     if (snapshot) {
+        if (snapshot.unavailable?.reason === 'session_limit') {
+            parts.push(chalk.yellow(`session-limited (${formatResetHint(snapshot.unavailable.resetsAt)})`));
+        }
         // Compact rows show BLOCKING windows — the same set
         // deriveUsageStatusFromSnapshot uses for the rate-limited badge — so an
         // account throttled by its month window (Droid meters on 5h/week/month)
@@ -467,7 +470,12 @@ export function formatUsageSummary(plan, snapshot, planWidth = 3, opts) {
  * one model, not the account, so it shouldn't flip the whole row to throttled.
  */
 export function deriveUsageStatusFromSnapshot(snapshot) {
-    if (!snapshot || snapshot.windows.length === 0)
+    if (!snapshot)
+        return null;
+    if (snapshot.unavailable && snapshot.unavailable.resetsAt.getTime() > Date.now()) {
+        return 'rate_limited';
+    }
+    if (snapshot.windows.length === 0)
         return null;
     const blocking = snapshot.windows.filter((window) => window.key !== 'sonnet_week');
     const windows = blocking.length > 0 ? blocking : snapshot.windows;
@@ -1286,7 +1294,6 @@ function deleteCachedClaudeOauth(service) {
  *     the Claude CLI stores its OAuth token in this plaintext file instead. The
  *     keychain read above finds nothing on that platform, so we fall back to the
  *     file. Same wrapped `{ claudeAiOauth }` shape, so one parser handles both.
- *     Mirrors `readClaudeCredentialsBlob` (cloud/rush.ts), the proven pattern.
  *
  * Without step 2 the live usage fetch got no token on Linux, so `agents view`
  * (run remotely over SSH by `--device`) rendered no usage bars even though the
@@ -1298,9 +1305,10 @@ function deleteCachedClaudeOauth(service) {
  * reads Claude Code's interactive login (transmitting that ACL-bound OAuth token
  * to Anthropic's API is what gets it revoked; see the branch body and
  * docs/credential-management.md). It is OFF by default so full-credential
- * callers that refresh (`isClaudeAuthValid` -> `getClaudeAccessToken`) or export
- * the full blob (`readClaudeCredentialsBlob` for Rush Cloud dispatch) still read
- * the interactive login.
+ * callers that refresh (`isClaudeAuthValid` -> `getClaudeAccessToken`) still
+ * read the interactive login. Rush Cloud dispatch does not call this helper
+ * at all (SING-1b: the account manifest is email-only; RUSH-2359 removed the
+ * leftover blob reader that used to send the interactive login).
  *
  * `opts.fileOnly` skips the ACL keychain read entirely — setup-token and
  * `.credentials.json` only. Used by the daemon usage refresher so a background
@@ -1334,9 +1342,10 @@ export async function loadClaudeOauth(home, opts) {
         // setup-token via the mint-auth path to restore usage/probe for the account.
         return null;
     }
-    // Full-credential callers (isClaudeAuthValid -> getClaudeAccessToken; Rush
-    // Cloud dispatch) legitimately read the interactive login to run/refresh
-    // Claude. The OS keychain/keyring step is macOS/Linux-only; Windows and any
+    // Full-credential callers (isClaudeAuthValid -> getClaudeAccessToken)
+    // legitimately read the interactive login to run/refresh Claude. Rush Cloud
+    // dispatch does not (SING-1b / RUSH-2359). The OS keychain/keyring step is
+    // macOS/Linux-only; Windows and any
     // fileOnly caller skip to the .credentials.json read below (the Claude CLI
     // stores its OAuth token in that file too). An injected test backend makes the
     // keychain path exercisable anywhere, so the platform check yields to it.
@@ -1446,11 +1455,29 @@ export function readClaudeUsageCache(usageKey, cachePath = getClaudeUsageCachePa
     }
     const snapshot = deserializeClaudeUsageSnapshot(cached, now);
     if (!snapshot) {
-        delete cache[usageKey];
-        writeClaudeUsageCacheFile(cache, cachePath);
+        pruneExpiredClaudeUsageCacheEntry(usageKey, cachePath, now);
     }
     return snapshot;
 }
+/** Delete an expired cache row only if it is still expired under the write lock. */
+export function pruneExpiredClaudeUsageCacheEntry(usageKey, cachePath = getClaudeUsageCachePath(), now = new Date()) {
+    try {
+        ensureLockTarget(cachePath, '{}');
+        withFileLock(cachePath, () => {
+            // The row may have been refreshed after readClaudeUsageCache observed it.
+            // Re-read under the lock so stale cleanup cannot erase that newer write.
+            const latest = readClaudeUsageCacheFile(cachePath);
+            const current = latest[usageKey];
+            if (!current || deserializeClaudeUsageSnapshot(current, now))
+                return;
+            delete latest[usageKey];
+            atomicWriteFileSync(cachePath, JSON.stringify(latest, null, 2), 'utf-8');
+        });
+    }
+    catch {
+        /* best-effort cache cleanup — lock busy or disk full */
+    }
+}
 /** Write a usage snapshot to the on-disk cache. */
 export function writeClaudeUsageCache(usageKey, snapshot, cachePath = getClaudeUsageCachePath()) {
     try {
@@ -1459,7 +1486,14 @@ export function writeClaudeUsageCache(usageKey, snapshot, cachePath = getClaudeU
             // Re-read under the lock so a concurrent daemon tick / agents view
             // refresh cannot drop another account's row (lost update).
             const cache = readClaudeUsageCacheFile(cachePath);
-            cache[usageKey] = serializeClaudeUsageSnapshot(snapshot);
+            const prior = cache[usageKey];
+            const priorReset = parseDateValue(prior?.unavailable?.resetsAt);
+            cache[usageKey] = serializeClaudeUsageSnapshot({
+                ...snapshot,
+                unavailable: priorReset && priorReset.getTime() > Date.now()
+                    ? { reason: 'session_limit', resetsAt: priorReset }
+                    : snapshot.unavailable,
+            });
             atomicWriteFileSync(cachePath, JSON.stringify(cache, null, 2), 'utf-8');
         });
     }
@@ -1495,6 +1529,9 @@ function serializeClaudeUsageSnapshot(snapshot) {
     return {
         capturedAt: snapshot.capturedAt?.toISOString() || null,
         plan: snapshot.plan ?? null,
+        unavailable: snapshot.unavailable
+            ? { reason: snapshot.unavailable.reason, resetsAt: snapshot.unavailable.resetsAt.toISOString() }
+            : undefined,
         windows: snapshot.windows.map((window) => ({
             key: window.key,
             label: window.label,
@@ -1505,25 +1542,34 @@ function serializeClaudeUsageSnapshot(snapshot) {
         })),
     };
 }
-/** Deserialize a cached snapshot, zeroing out windows whose reset time has passed. */
+/**
+ * Deserialize a cached snapshot, dropping windows whose reset time has passed.
+ *
+ * An expired window is UNKNOWN, not 0%: the counter reset, and anything may
+ * have burned since. Zeroing-but-keeping it (the previous behavior) rendered a
+ * weeks-frozen cache as "S: 0% (now)" with `deriveUsageStatusFromSnapshot` →
+ * 'available', so a genuinely rate-limited account read as an idle dispatch
+ * candidate (RUSH-2858). Dropping mirrors the Grok collector, and an all-expired
+ * snapshot deserializes to null so `readClaudeUsageCache` deletes the entry and
+ * callers surface "usage unavailable" plus the recorded throttle reason.
+ */
 function deserializeClaudeUsageSnapshot(snapshot, now) {
     const capturedAt = parseDateValue(snapshot.capturedAt);
     const windows = snapshot.windows
-        .map((window) => {
-        const w = {
-            key: window.key,
-            label: window.label,
-            shortLabel: window.shortLabel,
-            usedPercent: window.usedPercent,
-            resetsAt: parseDateValue(window.resetsAt),
-            windowMinutes: window.windowMinutes,
-        };
-        if (!isCachedUsageWindowFresh(w, capturedAt, now)) {
-            w.usedPercent = 0;
-        }
-        return w;
-    });
-    if (windows.length === 0) {
+        .map((window) => ({
+        key: window.key,
+        label: window.label,
+        shortLabel: window.shortLabel,
+        usedPercent: window.usedPercent,
+        resetsAt: parseDateValue(window.resetsAt),
+        windowMinutes: window.windowMinutes,
+    }))
+        .filter((window) => isCachedUsageWindowFresh(window, capturedAt, now));
+    const unavailableReset = parseDateValue(snapshot.unavailable?.resetsAt);
+    const unavailable = unavailableReset && unavailableReset.getTime() > now.getTime()
+        ? { reason: 'session_limit', resetsAt: unavailableReset }
+        : undefined;
+    if (windows.length === 0 && !unavailable) {
         return null;
     }
     return {
@@ -1532,8 +1578,73 @@ function deserializeClaudeUsageSnapshot(snapshot, now) {
         capturedAt,
         windows,
         plan: snapshot.plan ?? null,
+        unavailable,
     };
 }
+/**
+ * Persist a Claude session-limit refusal from a real run until its stated reset.
+ * This quota is not part of Anthropic's five-hour/weekly usage response.
+ */
+export function noteClaudeSessionLimit(usageKey, resetsAt, cachePath = getClaudeUsageCachePath()) {
+    try {
+        ensureLockTarget(cachePath, '{}');
+        withFileLock(cachePath, () => {
+            const cache = readClaudeUsageCacheFile(cachePath);
+            const existing = cache[usageKey] ?? { capturedAt: null, windows: [] };
+            cache[usageKey] = {
+                ...existing,
+                unavailable: { reason: 'session_limit', resetsAt: resetsAt.toISOString() },
+            };
+            atomicWriteFileSync(cachePath, JSON.stringify(cache, null, 2), 'utf-8');
+        });
+    }
+    catch {
+        /* best-effort cache write — lock busy or disk full */
+    }
+}
+/** Parse Claude's `hit your session limit · resets …` refusal. */
+export function parseClaudeSessionLimitReset(text, nowMs = Date.now()) {
+    if (!/hit your session limit/i.test(text))
+        return null;
+    const match = /resets\s+([^.;!\n]+)/i.exec(text);
+    if (!match)
+        return null;
+    const segment = match[1].trim();
+    const timeZone = /\(([A-Za-z_]+\/[A-Za-z_]+)\)/.exec(segment)?.[1];
+    const timePart = segment.replace(/\([A-Za-z_]+\/[A-Za-z_]+\)/, '').trim();
+    const absolute = Date.parse(timePart);
+    if (!Number.isNaN(absolute) && absolute > nowMs)
+        return new Date(absolute);
+    const clock = /(\d{1,2})(?::(\d{2}))?\s*(am|pm)/i.exec(timePart);
+    if (!clock)
+        return null;
+    let hour = Number(clock[1]) % 12;
+    if (clock[3].toLowerCase() === 'pm')
+        hour += 12;
+    const minute = clock[2] ? Number(clock[2]) : 0;
+    try {
+        if (!timeZone) {
+            const result = new Date(nowMs);
+            result.setHours(hour, minute, 0, 0);
+            if (result.getTime() <= nowMs)
+                result.setDate(result.getDate() + 1);
+            return result;
+        }
+        const parts = new Intl.DateTimeFormat('en-US', {
+            timeZone, hour12: false, year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit',
+        }).formatToParts(new Date(nowMs));
+        const part = (type) => Number(parts.find((item) => item.type === type)?.value ?? 0);
+        const wallNow = Date.UTC(part('year'), part('month') - 1, part('day'), part('hour') % 24, part('minute'));
+        const offset = wallNow - nowMs;
+        let result = Date.UTC(part('year'), part('month') - 1, part('day'), hour, minute) - offset;
+        if (result <= nowMs)
+            result += 24 * 60 * 60 * 1000;
+        return new Date(result);
+    }
+    catch {
+        return null;
+    }
+}
 /** Check whether a cached usage window is still relevant (not expired or reset). */
 function isCachedUsageWindowFresh(window, capturedAt, now) {
     if (window.resetsAt && window.resetsAt.getTime() <= now.getTime()) {

package/dist/lib/agent-spec/agents.d.ts

@@ -85,15 +85,15 @@ export declare const AGENTS: Record<AgentId, AgentRegistryConfig>;
 /** All current and legacy agent IDs derived from the AGENTS registry. */
 export declare const ALL_AGENT_IDS: AgentId[];
 /**
- * CLI command templates per agent for daemon-fired routine jobs, with
- * {prompt} as a placeholder. Lives here (not runner.ts) so routines.ts can
- * import ROUTINE_AGENT_IDS for schedule-time validation without a circular
+ * Agents the routine daemon can fire locally. Lives here (not runner.ts) so
+ * routines.ts can import it for schedule-time validation without a circular
  * import (runner.ts already imports from routines.ts).
+ *
+ * This is a curated subset of AGENT_COMMANDS, not "every harness that can run
+ * headlessly". Expanding it is a product change (gemini is hard-deprecated and
+ * is deliberately absent). Argv itself is baked from AGENT_COMMANDS in
+ * daemon/runner.ts bakeRoutineArgv — do not reintroduce a second token table.
  */
-export declare const ROUTINE_AGENT_COMMANDS: Record<string, string[]>;
-/** Agents the routine daemon can actually run when firing locally, derived
- * from the command table above so the `--agent` help and validateJob's
- * schedule-time check can never drift from it. */
 export declare const ROUTINE_AGENT_IDS: readonly string[];
 /** Agents retained only for legacy reads, not install/import/sync targets. */
 export declare const HARD_DEPRECATED_AGENT_IDS: AgentId[];

package/dist/lib/agent-spec/agents.js

@@ -1087,26 +1087,26 @@ export const AGENTS = {
 /** All current and legacy agent IDs derived from the AGENTS registry. */
 export const ALL_AGENT_IDS = Object.keys(AGENTS);
 /**
- * CLI command templates per agent for daemon-fired routine jobs, with
- * {prompt} as a placeholder. Lives here (not runner.ts) so routines.ts can
- * import ROUTINE_AGENT_IDS for schedule-time validation without a circular
+ * Agents the routine daemon can fire locally. Lives here (not runner.ts) so
+ * routines.ts can import it for schedule-time validation without a circular
  * import (runner.ts already imports from routines.ts).
+ *
+ * This is a curated subset of AGENT_COMMANDS, not "every harness that can run
+ * headlessly". Expanding it is a product change (gemini is hard-deprecated and
+ * is deliberately absent). Argv itself is baked from AGENT_COMMANDS in
+ * daemon/runner.ts bakeRoutineArgv — do not reintroduce a second token table.
  */
-export const ROUTINE_AGENT_COMMANDS = {
-    claude: ['claude', '-p', '--verbose', '{prompt}', '--output-format', 'stream-json', '--permission-mode', 'plan'],
-    codex: ['codex', 'exec', '{prompt}', '--json'],
+export const ROUTINE_AGENT_IDS = Object.freeze([
+    'claude',
+    'codex',
     // gemini is hard-deprecated (Antigravity replaced it) — no routine target. A
     // legacy gemini routine now fails validateJob loud instead of firing a
     // retired backend; the id survives only for reading old sessions/config.
-    cursor: ['cursor-agent', '-p', '{prompt}', '--output-format', 'stream-json'],
-    kimi: ['kimi', '--prompt', '{prompt}', '--output-format', 'stream-json'],
-    droid: ['droid', 'exec', '{prompt}', '-o', 'stream-json'],
-    muse: ['muse', 'exec', '{prompt}', '--json'],
-};
-/** Agents the routine daemon can actually run when firing locally, derived
- * from the command table above so the `--agent` help and validateJob's
- * schedule-time check can never drift from it. */
-export const ROUTINE_AGENT_IDS = Object.freeze(Object.keys(ROUTINE_AGENT_COMMANDS));
+    'cursor',
+    'kimi',
+    'droid',
+    'muse',
+]);
 /** Agents retained only for legacy reads, not install/import/sync targets. */
 export const HARD_DEPRECATED_AGENT_IDS = ALL_AGENT_IDS.filter((id) => AGENTS[id].deprecated?.hard);
 /** Agents that can receive managed installs, imports, and resource sync writes. */