@phnx-labs/agents-cli 1.22.35 → 1.22.38

package/dist/lib/usage.js

@@ -25,6 +25,7 @@ import { formatBackoffRemaining, noteUsageRateLimited, usageRateLimitedUntil, }
 import { getCacheDir } from './state.js';
 import { mapBounded } from './concurrency.js';
 import { atomicWriteFileSync, ensureLockTarget, withFileLock } from './fs-atomic.js';
+import { withRefreshLease } from './refresh-coordinator.js';
 const execFileAsync = promisify(execFile);
 const CLAUDE_USAGE_URL = 'https://api.anthropic.com/api/oauth/usage';
 const CLAUDE_TOKEN_URL = 'https://platform.claude.com/v1/oauth/token';
@@ -62,6 +63,40 @@ export function usageRejectedError(agent, status) {
         ? `${agent} is rate-limiting the usage endpoint for this machine (HTTP 429).`
         : `${agent} rejected the usage read (HTTP ${status}).`;
 }
+/**
+ * Canonical phrase for the Anthropic setup-token scope gap (RUSH-2392).
+ * `claude setup-token` mints `user:inference` only; the usage endpoint requires
+ * `user:profile`. The account can still run; usage bars cannot populate via
+ * that token. Callers detect this string with {@link isUsageHeadlessScopeError}
+ * so the UI can render it distinctly from a generic "unverified" failure.
+ */
+export const USAGE_HEADLESS_SCOPE_MARKER = 'usage unavailable (headless)';
+/**
+ * Distinct error when Claude's usage API returns 403 because the setup-token
+ * lacks `user:profile` (RUSH-2392). Not a revocation, not a missing mint —
+ * a permanent tradeoff of the headless credential.
+ */
+export function usageHeadlessScopeError(agent = 'Claude') {
+    return `${agent} ${USAGE_HEADLESS_SCOPE_MARKER} — setup-token lacks user:profile; account can still run.`;
+}
+/** True when an error string is the setup-token scope gap (RUSH-2392). */
+export function isUsageHeadlessScopeError(error) {
+    return typeof error === 'string' && error.includes(USAGE_HEADLESS_SCOPE_MARKER);
+}
+/**
+ * Detect Anthropic's usage-endpoint scope denial: HTTP 403 whose body names
+ * `user:profile` (or "scope requirement"). A bare 403 without that body stays
+ * classified as a real rejection — only the known setup-token shape is special
+ * (RUSH-2392).
+ */
+export function isClaudeUsageScopeDenied(status, bodyText) {
+    if (status !== 403)
+        return false;
+    if (!bodyText)
+        return false;
+    const lower = bodyText.toLowerCase();
+    return lower.includes('user:profile') || lower.includes('scope requirement');
+}
 /**
  * The read threw rather than answering — a timeout, DNS/TLS failure, a payload
  * that would not parse, a credential that would not decrypt. Every provider
@@ -193,9 +228,9 @@ export function agentReportsUsage(agentId) {
 }
 /**
  * Whether an agent's usage source makes a live NETWORK call (Claude/Kimi/Droid/
- * Cursor/Antigravity) versus reading local session logs (Codex/Grok). Only the
- * networked ones go through the on-disk cache, and only they need the daemon's
- * background refresher to keep that cache warm for the routing hot path.
+ * Cursor/Antigravity) versus reading local session logs (Codex/Grok). Both
+ * kinds publish through the shared cache; callers use this only to distinguish
+ * provider I/O from local collection.
  */
 export function agentUsesNetworkUsage(agentId) {
     return getUsageSource(agentId)?.network === true;
@@ -207,27 +242,6 @@ export function agentUsesNetworkUsage(agentId) {
  * (and cannot stack behind delayed responses until the process is pegged).
  */
 export const USAGE_FETCH_CONCURRENCY = 3;
-/**
- * Concurrent background SWR refreshes. Kept below the blocking concurrency so
- * a display path that returns cached data immediately does not still flood the
- * network with N silent refreshes that finish long after the command exits and
- * pile onto the next invocation.
- */
-const USAGE_BG_REFRESH_CONCURRENCY = 2;
-/**
- * How long a cached snapshot is treated as fresh enough that we skip the network
- * entirely. Five minutes balances "still accurate enough to glance at" against
- * "don't re-hit every account on every `agents view` in a tight loop". Was 2
- * minutes; that re-fired too often when delayed responses stacked.
- */
-export const USAGE_CACHE_FRESH_MS = 5 * 60 * 1000;
-export const USAGE_CACHE_SWR_MS = 24 * 60 * 60 * 1000; // 24 hours — beyond this, block on live fetch.
-/**
- * Unified entry for every multi-account usage lookup (`agents view`, rotation,
- * JSON export). Deduplicates by usage identity, then fans out through the
- * shared SWR + timeout path with a hard concurrency cap so delayed calls
- * cannot pile up.
- */
 export async function getUsageInfoByIdentity(inputs, opts) {
     const { canonicalByUsageKey, usageFetchInputs } = buildCanonicalUsageContext(inputs);
     const entries = [...usageFetchInputs.entries()];
@@ -246,63 +260,36 @@ export async function getUsageInfoByIdentity(inputs, opts) {
     };
 }
 /**
- * How stale a cached snapshot may be before the read stops serving it and blocks
- * on the network. Defaults to the full 24h stale-while-revalidate window; a
- * caller that is about to ROUTE on the number passes a shorter `maxAgeMs` and
- * gets a live read instead of a day-old one. Never widens past 24h — a caller
- * cannot opt into more staleness than the cache policy allows.
- */
-export function swrWindowMsFor(maxAgeMs) {
-    if (maxAgeMs === undefined || !Number.isFinite(maxAgeMs))
-        return USAGE_CACHE_SWR_MS;
-    return Math.min(USAGE_CACHE_SWR_MS, Math.max(0, maxAgeMs));
-}
-/**
- * In-process dedup for live + background usage work on the same identity.
- * Covers both the blocking cold-cache path and SWR background refreshes so a
- * delayed HTTP response cannot be stacked under a second request for the same
- * key (the pile-up that made consecutive `agents view` runs peg CPU/network).
+ * In-process dedup complements the device-wide lease. It avoids lock contention
+ * when several callers in one process explicitly request the same refresh.
  */
 const inFlightLiveFetches = new Map();
-const inFlightBgKeys = new Set();
-const bgRefreshQueue = [];
-let bgRefreshActive = 0;
 /**
- * Fetch usage for a single identity using stale-while-revalidate.
- *
- * - Cache fresh (< 5 min): return cached snapshot, NO network.
- * - Cache stale but < 24h: return cached snapshot instantly, enqueue a
- *   concurrency-capped background refresh.
- * - Cache too stale or absent: block on live fetch (shared in-flight promise),
- *   fall back to cache on error.
- *
- * This keeps `agents run` / `agents view` off the network on the hot path. The
- * first invocation after a cold install or 24h gap still blocks once to seed
- * the cache; every run after that returns instantly while the cache silently
- * refreshes in the background — never more than {@link USAGE_BG_REFRESH_CONCURRENCY}
- * at a time.
+ * Fetch usage for one identity. Ordinary callers always read the shared cache;
+ * the daemon and explicit `--refresh` calls collect through one device lease.
  */
 export async function getUsageInfoForIdentity(input, opts) {
     const usageKey = getUsageLookupKey(input.info);
     const forceRefresh = opts?.forceRefresh === true;
-    const readOnly = opts?.readOnly === true;
-    // Agents whose registered usage source makes a live network call go
-    // through the stale-while-revalidate cache below so `agents run`/`agents view`
-    // stay off the network on the hot path. Everything else (Codex reads local
-    // session logs) takes the legacy blocking path. The on-disk cache is shared and
+    // Reading is the default. Only an explicit forceRefresh is authorized to
+    // collect provider/local-log state; callers cannot accidentally turn a
+    // display or routing path into a collector by omitting an option.
+    const readOnly = !forceRefresh;
+    // The on-disk cache is shared for both provider and local-log sources and is
     // keyed by usageKey, which is namespaced per agent (`claude:org=…`,
     // `kimi:user=…`, `droid:org=…`, `cursor:user=…`, `antigravity:sub=…`), so one
     // cache file holds every account without collision.
-    const usesNetworkUsage = getUsageSource(input.agentId)?.network === true;
-    if (!usesNetworkUsage || !usageKey) {
+    if (!usageKey) {
+        if (readOnly)
+            return { snapshot: null, error: 'stale' };
         return getUsageInfo(input.agentId, {
             home: input.home,
             cliVersion: input.cliVersion,
             organizationId: input.info.organizationId,
+            fileOnly: opts?.fileOnly,
         });
     }
     const cached = readClaudeUsageCache(usageKey);
-    const ageMs = cached?.capturedAt ? Date.now() - cached.capturedAt.getTime() : Infinity;
     // `readOnly` (the `agents run` routing hot path): serve the cache and NEVER
     // touch the network — not even a background refresh. `collectRunCandidates`
     // used to pass a 5-minute `maxAgeMs`, which made a snapshot older than that
@@ -319,58 +306,48 @@ export async function getUsageInfoForIdentity(input, opts) {
             return { snapshot: cached, error: null };
         return { snapshot: null, error: 'stale' };
     }
-    // `--refresh` (forceRefresh) skips both cache short-circuits and blocks on a
-    // live fetch below, so `agents view --refresh` repopulates every account we can
-    // actually reach a token for.
-    if (!forceRefresh) {
-        // Fresh: cache is recent enough, skip network entirely.
-        if (cached && ageMs < USAGE_CACHE_FRESH_MS) {
-            return { snapshot: cached, error: null };
-        }
-        // Stale-while-revalidate: cache exists and isn't ancient, return it now and
-        // refresh in the background so the next invocation has fresh data.
-        //
-        // `maxAgeMs` shortens that window for callers that are about to make a
-        // DECISION on the number rather than display it. Serving a day-old snapshot
-        // to the account router is how a launch lands on an already-exhausted
-        // account: the box picks from its own cache, the background refresh lands
-        // after the choice is made, and nothing reconciles. Display callers keep the
-        // full 24h window and stay off the hot path.
-        const swrWindowMs = swrWindowMsFor(opts?.maxAgeMs);
-        if (cached && ageMs < swrWindowMs) {
-            enqueueBackgroundUsageRefresh(input, usageKey);
-            return { snapshot: cached, error: null };
-        }
-    }
-    // Cold cache or > 24h old (or forceRefresh): block on a shared live fetch so
-    // concurrent callers for the same identity share one in-flight HTTP call.
-    return fetchLiveUsageDeduped(input, usageKey, cached);
+    // Explicit refresh: block on the shared device collector.
+    return fetchLiveUsageDeduped(input, usageKey, cached, opts?.fileOnly === true);
 }
 /**
  * Single-flight live usage fetch per usage key. Concurrent callers (view +
  * rotation, or two rows sharing an account) await the same promise rather than
  * opening duplicate HTTP requests that then time out and pile up.
  */
-async function fetchLiveUsageDeduped(input, usageKey, cached) {
+async function fetchLiveUsageDeduped(input, usageKey, cached, fileOnly) {
     const existing = inFlightLiveFetches.get(usageKey);
     if (existing)
         return existing;
-    const promise = (async () => {
-        const usage = await getUsageInfo(input.agentId, {
-            home: input.home,
-            cliVersion: input.cliVersion,
-            organizationId: input.info.organizationId,
-        });
-        if (usage.snapshot?.source === 'live') {
-            writeClaudeUsageCache(usageKey, usage.snapshot);
+    const previousCapturedAt = cached?.capturedAt?.getTime() ?? 0;
+    const promise = withRefreshLease({
+        scope: 'usage',
+        key: usageKey,
+        readCompleted: () => {
+            const snapshot = readClaudeUsageCache(usageKey);
+            return snapshot ? { snapshot, error: null } : null;
+        },
+        isCompleted: (value) => (value.snapshot?.capturedAt?.getTime() ?? 0) > previousCapturedAt,
+        refresh: async () => {
+            const latestCached = readClaudeUsageCache(usageKey) ?? cached;
+            const usage = await getUsageInfo(input.agentId, {
+                home: input.home,
+                cliVersion: input.cliVersion,
+                organizationId: input.info.organizationId,
+                fileOnly,
+            });
+            if (usage.snapshot) {
+                if (!usage.snapshot.capturedAt || usage.snapshot.capturedAt.getTime() <= previousCapturedAt) {
+                    usage.snapshot.capturedAt = new Date(previousCapturedAt + 1);
+                }
+                writeClaudeUsageCache(usageKey, usage.snapshot);
+                return usage;
+            }
+            // Live fetch failed — last-resort fallback to whatever cache we had.
+            if (latestCached)
+                return { snapshot: latestCached, error: usage.error };
             return usage;
-        }
-        // Live fetch failed — last-resort fallback to whatever cache we had.
-        if (cached) {
-            return { snapshot: cached, error: usage.error };
-        }
-        return usage;
-    })();
+        },
+    });
     inFlightLiveFetches.set(usageKey, promise);
     try {
         return await promise;
@@ -379,46 +356,6 @@ async function fetchLiveUsageDeduped(input, usageKey, cached) {
         inFlightLiveFetches.delete(usageKey);
     }
 }
-/**
- * Enqueue a background refresh of the usage cache. Errors are swallowed — a
- * failed refresh leaves the existing cache in place. Work is deferred via
- * `setImmediate` (keychain reads do sync I/O) and drained with a hard
- * concurrency cap so N stale accounts do not open N HTTP calls at once.
- */
-function enqueueBackgroundUsageRefresh(input, usageKey) {
-    if (inFlightBgKeys.has(usageKey) || inFlightLiveFetches.has(usageKey))
-        return;
-    inFlightBgKeys.add(usageKey);
-    bgRefreshQueue.push(async () => {
-        try {
-            // Reuse the single-flight live path so a blocking caller that arrives
-            // mid-refresh shares the same HTTP call instead of racing it.
-            const cached = readClaudeUsageCache(usageKey);
-            await fetchLiveUsageDeduped(input, usageKey, cached);
-        }
-        catch {
-            /* background refresh failed — leave existing cache in place */
-        }
-        finally {
-            inFlightBgKeys.delete(usageKey);
-        }
-    });
-    pumpBackgroundUsageRefreshes();
-}
-function pumpBackgroundUsageRefreshes() {
-    while (bgRefreshActive < USAGE_BG_REFRESH_CONCURRENCY && bgRefreshQueue.length > 0) {
-        const work = bgRefreshQueue.shift();
-        bgRefreshActive++;
-        // setImmediate so the SWR caller returns the cached snapshot before any
-        // keychain/network work starts on this tick.
-        setImmediate(() => {
-            work().finally(() => {
-                bgRefreshActive--;
-                pumpBackgroundUsageRefreshes();
-            });
-        });
-    }
-}
 /**
  * Pick which usage windows to render in a compact one-line summary.
  *
@@ -488,10 +425,20 @@ export function formatUsageSummary(plan, snapshot, planWidth = 3, opts) {
         // The bars came from the cache and the live read that should have confirmed
         // them failed, so they are the last thing we saw — not the current state.
         // Drawing them unmarked is what let a 26h-old "48% used" read as fact.
-        if (opts?.unverified) {
+        // Headless-scope (RUSH-2392) is a known permanent gap, not a flaky cache:
+        // prefer that label over the generic "unverified" so operators do not re-mint.
+        if (opts?.headless) {
+            parts.push(chalk.dim(USAGE_HEADLESS_SCOPE_MARKER));
+        }
+        else if (opts?.unverified) {
             parts.push(chalk.yellow('unverified'));
         }
     }
+    else if (opts?.headless) {
+        // No bars at all: still name the scope gap so "usage pending" is not
+        // mistaken for a missing setup-token or seeding failure (RUSH-2392).
+        parts.push(chalk.dim(USAGE_HEADLESS_SCOPE_MARKER));
+    }
     else if (opts?.unavailable) {
         // Signed-in account we could NOT fetch usage for (no live token in a reachable
         // home / org mismatch / fetch error). Say so explicitly instead of drawing a
@@ -725,6 +672,21 @@ async function getClaudeUsageInfo(options) {
             if (response.status === 429) {
                 noteUsageRateLimited('claude', response.headers.get('retry-after'));
             }
+            // Setup-token is user:inference only; usage needs user:profile → 403
+            // with a scope-requirement body. Distinct from a real rejection so the
+            // UI does not say "unverified" / re-mint (RUSH-2392).
+            if (response.status === 403) {
+                let bodyText = '';
+                try {
+                    bodyText = await response.text();
+                }
+                catch {
+                    // ignore — fall through to generic rejection
+                }
+                if (isClaudeUsageScopeDenied(response.status, bodyText)) {
+                    return { snapshot: null, error: usageHeadlessScopeError('Claude') };
+                }
+            }
             return { snapshot: null, error: usageRejectedError('Claude', response.status) };
         }
         const data = await response.json();
@@ -908,7 +870,7 @@ export function formatKimiPlan(data) {
     return tail.charAt(0).toUpperCase() + tail.slice(1).toLowerCase();
 }
 /**
- * Fetch Droid usage via Factory's billing limits API — the same endpoint the
+ * Fetch Droid usage via Factory.ai's billing limits API — the same endpoint the
  * droid CLI polls for its token-limit banner. The WorkOS access token comes
  * from the locally decrypted ~/.factory/auth.v2.file (the same credential
  * account identity in agents.ts reads).
@@ -1018,6 +980,25 @@ export async function probeClaudeStatus(home, cliVersion) {
         if (response.status === 429) {
             noteUsageRateLimited('claude', response.headers.get('retry-after'));
         }
+        // Setup-token is user:inference only; usage needs user:profile → 403.
+        // That is NOT a revocation — the account still runs (RUSH-2392).
+        if (response.status === 403) {
+            let bodyText = '';
+            try {
+                bodyText = await response.text();
+            }
+            catch {
+                // Body unreadable: fall through to a bare 403 (classified as revoked).
+            }
+            if (isClaudeUsageScopeDenied(response.status, bodyText)) {
+                return {
+                    status: 403,
+                    token: 'present',
+                    reason: 'usage_scope',
+                    error: USAGE_HEADLESS_SCOPE_MARKER,
+                };
+            }
+        }
         return { status: response.status, token: 'present' };
     }
     catch (err) {
@@ -1316,7 +1297,7 @@ function deleteCachedClaudeOauth(service) {
  * a file-based setup-token and, when none is provisioned, gets `null` — it never
  * 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/design/credential-management.md). It is OFF by default so full-credential
+ * 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.
@@ -1348,7 +1329,7 @@ export async function loadClaudeOauth(home, opts) {
         // interactive credential used programmatically, which Anthropic flags and
         // revokes (the fleet-wide-logout class, RUSH-1822), and which violates the
         // invariant that the interactive/rotating login is untouchable
-        // (docs/design/credential-management.md). Report unprovisioned (-> probe
+        // (docs/credential-management.md). Report unprovisioned (-> probe
         // token 'missing' -> auth-health 'unconfigured', benign for rotation); seed a
         // setup-token via the mint-auth path to restore usage/probe for the account.
         return null;
@@ -1786,12 +1767,20 @@ async function getGrokUsageInfo(options) {
         const match = await readLatestGrokBilling(logPath);
         if (!match)
             return { snapshot: null, error: null };
+        // Grok has no live usage API (`network: false`) — bars are last-seen from
+        // this machine's unified.jsonl only. Drop windows whose billing period has
+        // already ended so a stale 100% does not paint "rate-limited" after reset,
+        // and so an expired 92% on one box cannot disagree with a fresh reading on
+        // another. Missing `creditUsagePercent` never reaches here as a 0% bar
+        // (see readLatestGrokBilling).
+        const now = new Date();
+        const windows = match.windows.filter((window) => isCachedUsageWindowFresh(window, match.capturedAt, now));
         return {
             snapshot: {
                 source: 'last_seen',
                 sourceLabel: 'last seen in Grok logs',
                 capturedAt: match.capturedAt,
-                windows: match.windows,
+                windows,
                 plan: match.subscriptionTier,
             },
             error: null,
@@ -2028,10 +2017,13 @@ async function readLatestGrokBilling(filePath) {
                 if (parsed.msg === 'billing: fetched credits config' && parsed.ctx?.config) {
                     const config = parsed.ctx.config;
                     const windows = [];
-                    if (config.currentPeriod?.end) {
+                    if (config.currentPeriod?.end && typeof config.creditUsagePercent === 'number') {
                         // `creditUsagePercent` is Grok's weekly credit consumption (0-100);
                         // the billing period's `end` is when that window resets.
-                        const rawPercent = typeof config.creditUsagePercent === 'number' ? config.creditUsagePercent : 0;
+                        // Do NOT coerce a missing percent to 0 — a new period often lands a
+                        // billing line before the gauge is populated, and inventing 0% makes
+                        // `agents view` disagree across devices (and looks like a fresh week).
+                        const rawPercent = config.creditUsagePercent;
                         windows.push({
                             key: 'week',
                             label: 'Current week',

package/dist/lib/version-duplicates.js

@@ -1,7 +1,7 @@
 import chalk from 'chalk';
 import { getAccountInfo, agentLabel } from './agents.js';
 import { compareVersions, getVersionHomePath, listInstalledVersions, } from './versions.js';
-import { getUsageInfoByIdentity, getUsageLookupKey, } from './usage.js';
+import { buildCanonicalUsageContext, getUsageLookupKey, } from './usage.js';
 function duplicateIdentity(info) {
     if (!info)
         return null;
@@ -38,7 +38,7 @@ export async function getNewerDuplicateVersions(agentId, selectedVersion) {
         const info = await getAccountInfo(agentId, home);
         return { version, home, info };
     }));
-    const { canonicalByUsageKey } = await getUsageInfoByIdentity(rows.map(({ version, home, info }) => ({
+    const { canonicalByUsageKey } = buildCanonicalUsageContext(rows.map(({ version, home, info }) => ({
         agentId,
         home,
         cliVersion: version,

package/dist/lib/versions.d.ts

@@ -1,5 +1,6 @@
 import type { AgentId } from './types.js';
 import { compareVersions } from './agent-spec/primitives.js';
+import { type PrunableKind } from './staleness/prune.js';
 /**
  * Resource selection for syncing to a version.
  * Each field can be:
@@ -110,6 +111,24 @@ export declare function parseAgentSpec(spec: string): AgentSpec | null;
  * Get the directory where a specific version is installed.
  */
 export declare function getVersionDir(agent: AgentId, version: string): string;
+/**
+ * Pick the real grok binary among `grok-*` entries in `downloadsDir` when NO
+ * filename carries the pinned version string. Grok self-updates its binary in
+ * place while running under the shim, so a version-home's downloads dir can
+ * accumulate several `grok-*` files whose names have drifted away from that
+ * version-home's pinned version (RUSH-2459: on yosemite-s0, version-home
+ * `0.2.82` held `grok-1.0.0-linux-aarch64` after grok self-updated, plus a
+ * stale, unrelated 99-byte `grok-0.2.118-linux-aarch64` wrapper script that
+ * happened to sort alphabetically first).
+ *
+ * Never blindly take whatever `fs.readdirSync` returns first — that is exactly
+ * the bug this replaces. Instead: exclude anything under
+ * {@link MIN_GROK_BINARY_BYTES} (rejects wrapper/alias artifacts on size
+ * alone, no content sniffing needed) and, among the survivors, prefer the most
+ * recently modified — the file grok's self-updater actually wrote last.
+ * Returns null (fail loud, never guess) when nothing survives the size filter.
+ */
+export declare function resolveGrokFallbackBinary(downloadsDir: string): string | null;
 /**
  * Get the binary path for a specific agent version.
  */
@@ -494,6 +513,12 @@ export interface SyncResult {
      * sync — never one line per file from down here.
      */
     projectSkipped: string[];
+    /**
+     * Resources removed from the version home because they were deleted from
+     * source since the last sync (RUSH-2438), per kind. Populated only on a
+     * repo-scope reconcile that ran the prune pass; empty otherwise.
+     */
+    pruned: Record<PrunableKind, string[]>;
 }
 /**
  * Enumerate the DotAgent repo names that resources can be scoped to:
@@ -501,21 +526,37 @@ export interface SyncResult {
  * repo alias. Used to validate `agents sync <agent> --repo <name>`.
  */
 export declare function listRepoNames(): string[];
+/**
+ * Build a ResourceSelection from source-pattern expansion and an optional
+ * per-kind name filter. Both dimensions are optional and compose:
+ *
+ *   patterns only   → resources from those source layers (all matching names)
+ *   kindFilter only → only those specific kinds / names, no source restriction
+ *   both combined   → patterns scope the source layer; kindFilter further
+ *                     limits which names within each kind are included
+ *
+ * Typical callers:
+ *   `--repo system`   → buildSelection(['system:*'])
+ *   `--plugin`        → buildSelection([], { plugins: 'all' })
+ *   `--plugin fleet`  → buildSelection([], { plugins: ['fleet'] })
+ *   no flags          → buildSelection([]) → full selection
+ *
+ * Memory (`kindFilter.memory`):
+ *   - Always `'all'` when patterns are active (repo scope must recompile the
+ *     composed file from all layers, RUSH-1354).
+ *   - `'all'` when `kindFilter.memory` is set (--rule / --memory flag).
+ *   - Absent (skipped) when kindFilter is given but does not include memory,
+ *     so `--plugin fleet` does NOT trigger a memory recompile.
+ *   - `'all'` when no kindFilter is given (full sync includes everything).
+ */
+export declare function buildSelection(patterns: string[], kindFilter?: ResourceSelection, cwd?: string): ResourceSelection;
 /**
  * Build a ResourceSelection scoped to a single DotAgent repo (`system`,
- * `user`, `project`, or an extra-repo alias). Every resource kind is filtered
- * to the entries whose source layer matches `repo`, reusing the same
- * name→source maps and `source:*` pattern expansion the persisted-pattern
- * sync path uses. Passing the result as an explicit `selection` means the sync
- * touches only that repo's resources — no orphan-sweep of the other layers.
- *
- * `memory` is set to `'all'`, NOT `[]`: the composed rules-memory file is a
- * merge of ALL layers, so scoping the sync to a single repo must still
- * recompile it in the same pass (RUSH-1354). Leaving it out — or using the
- * `[]` skip-sentinel — silently strands the memory file at its old content
- * whenever a repo-scoped sync runs after a rules change. `'all'` makes
- * `syncResourcesToVersion` recompose from every layer via the active preset,
- * exactly as an unscoped full reconcile does.
+ * `user`, `project`, or an extra-repo alias). Delegates to `buildSelection`
+ * so the source-map and pattern-expansion logic stays in one place.
+ *
+ * `memory` is always `'all'`: the composed rules-memory file spans all layers
+ * and must be recompiled in the same pass (RUSH-1354).
  */
 export declare function buildRepoScopedSelection(repo: string, cwd?: string): ResourceSelection;
 /**
@@ -550,6 +591,8 @@ export declare function syncResourcesToVersion(agent: AgentId, version: string,
     cwd?: string;
     force?: boolean;
     available?: AvailableResources;
+    prune?: boolean;
+    allowExecSurfaces?: boolean;
 }): SyncResult;
 /**
  * Get the effective HOME directory for an agent.