codex-multi-auth 2.17.2 → 2.18.0

package/dist/lib/local-client-tokens.js

@@ -1,10 +1,11 @@
-import { createHash, randomBytes, randomUUID } from "node:crypto";
+import { createHash, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
 import { existsSync, promises as fs } from "node:fs";
 import { basename, join } from "node:path";
 import { logWarn } from "./logger.js";
 import { getCodexMultiAuthDir } from "./runtime-paths.js";
 import { isRecord, sleep } from "./utils.js";
 import { tempPathFor } from "./temp-path.js";
+import { assertJsonStoreFileMtimeUnchanged, getJsonStoreFileMtimeMs, withJsonStoreCasRetry, withJsonStoreFileLock, } from "./storage/json-store-lock.js";
 const TOKEN_FILE_NAME = "local-client-tokens.json";
 const TOKEN_PREFIX = "cma_local";
 // Debounce window for persisting a record's lastUsedAt. Bearer verification is
@@ -43,6 +44,27 @@ function normalizeLabel(value) {
 function hashToken(token) {
     return `sha256:${createHash("sha256").update(token).digest("hex")}`;
 }
+/**
+ * Constant-time equality for two `sha256:<hex>` token hashes.
+ *
+ * A `===` on the hex strings returns early at the first differing byte, so a
+ * local process that can spam verify calls could measure the comparison cost
+ * and recover a stored hash prefix byte-by-byte. Comparing the decoded digest
+ * bytes with timingSafeEqual removes the oracle; both inputs are validated to
+ * the fixed 32-byte shape first, so timingSafeEqual never throws.
+ */
+function sha256DigestBytes(hash) {
+    if (!/^sha256:[0-9a-f]{64}$/i.test(hash))
+        return null;
+    return Buffer.from(hash.slice("sha256:".length), "hex");
+}
+function tokenHashEqual(left, right) {
+    const leftDigest = sha256DigestBytes(left);
+    const rightDigest = sha256DigestBytes(right);
+    return (leftDigest !== null &&
+        rightDigest !== null &&
+        timingSafeEqual(leftDigest, rightDigest));
+}
 function createPlainToken() {
     return `${TOKEN_PREFIX}_${randomBytes(32).toString("base64url")}`;
 }
@@ -120,7 +142,46 @@ export async function loadLocalClientTokenStore() {
         return emptyStore();
     }
 }
-async function writeStoreToDisk(store) {
+/**
+ * Merge a caller-supplied store over the freshest on-disk store by token id.
+ * Records the caller does not carry are preserved (this store is append-only:
+ * rotation and revocation mark records in place, nothing deletes them), and
+ * the monotone fields a concurrent process may have advanced — `lastUsedAt`
+ * from verifies, `revokedAt` from revocations/rotations — are kept at their
+ * furthest value so a stale snapshot cannot un-revoke or rewind usage.
+ */
+function mergeTokenStoreRecords(current, incoming) {
+    const indexById = new Map();
+    const tokens = current.tokens.map((record, index) => {
+        indexById.set(record.id, index);
+        return record;
+    });
+    for (const record of incoming.tokens) {
+        const index = indexById.get(record.id);
+        if (index === undefined) {
+            indexById.set(record.id, tokens.length);
+            tokens.push(record);
+            continue;
+        }
+        const existing = tokens[index];
+        if (existing === undefined) {
+            // Unreachable: indexes recorded in indexById always point at a
+            // slot that exists in `tokens`.
+            continue;
+        }
+        tokens[index] = {
+            ...record,
+            lastUsedAt: record.lastUsedAt === null
+                ? existing.lastUsedAt
+                : existing.lastUsedAt === null
+                    ? record.lastUsedAt
+                    : Math.max(record.lastUsedAt, existing.lastUsedAt),
+            revokedAt: record.revokedAt ?? existing.revokedAt,
+        };
+    }
+    return { version: 1, tokens };
+}
+async function writeStoreToDisk(store, expectedMtimeMs) {
     const path = getLocalClientTokenPath();
     const payload = normalizeStore(store);
     const dir = getCodexMultiAuthDir();
@@ -153,6 +214,12 @@ async function writeStoreToDisk(store) {
         finally {
             await handle.close();
         }
+        // Compare-and-swap guard: a writer that did not take the lockfile (or an
+        // expired-lock takeover racing this write) moved the target's mtime; abort
+        // with ESTALE so the caller reloads and re-merges instead of clobbering.
+        if (expectedMtimeMs !== undefined) {
+            await assertJsonStoreFileMtimeUnchanged(path, expectedMtimeMs);
+        }
         for (let attempt = 0; attempt < 5; attempt += 1) {
             try {
                 await fs.rename(tempPath, path);
@@ -177,8 +244,36 @@ async function writeStoreToDisk(store) {
         }
     }
 }
+/**
+ * Run a token-store read→mutate→write inside the write queue (in-process
+ * serialization) AND the cross-process lock directory, with mtime CAS retry:
+ * every attempt re-stats the file, re-reads the freshest on-disk store, and
+ * re-applies `mutate` before writing — so an op whose snapshot raced a
+ * concurrent process's write reloads-and-retries rather than clobbering it.
+ * `mutate` must be re-appliable across retries (apply precomputed work onto
+ * the store it is handed, don't capture mutated state).
+ */
+async function updateLocalClientTokenStore(mutate) {
+    const path = getLocalClientTokenPath();
+    return enqueue(() => withJsonStoreFileLock(path, () => withJsonStoreCasRetry(async () => {
+        const expectedMtimeMs = await getJsonStoreFileMtimeMs(path);
+        const store = await loadLocalClientTokenStore();
+        const { result, dirty } = mutate(store);
+        if (dirty) {
+            await writeStoreToDisk(store, expectedMtimeMs);
+        }
+        return result;
+    })));
+}
 export async function saveLocalClientTokenStore(store) {
-    await enqueue(() => writeStoreToDisk(store));
+    const path = getLocalClientTokenPath();
+    const incoming = normalizeStore(store);
+    await enqueue(() => withJsonStoreFileLock(path, () => withJsonStoreCasRetry(async () => {
+        const expectedMtimeMs = await getJsonStoreFileMtimeMs(path);
+        const current = await loadLocalClientTokenStore();
+        const merged = mergeTokenStoreRecords(current, incoming);
+        await writeStoreToDisk(merged, expectedMtimeMs);
+    })));
 }
 export function createLocalClientTokenRecord(input = {}) {
     const plainToken = createPlainToken();
@@ -194,40 +289,40 @@ export function createLocalClientTokenRecord(input = {}) {
     return { plainToken, record };
 }
 export async function addLocalClientToken(input = {}) {
-    return enqueue(async () => {
-        const store = await loadLocalClientTokenStore();
-        const created = createLocalClientTokenRecord(input);
+    // The token record is created once, outside the CAS retry: re-applying the
+    // same record onto a freshly-reloaded store is what makes each retry safe.
+    const created = createLocalClientTokenRecord(input);
+    return updateLocalClientTokenStore((store) => {
         store.tokens.push(created.record);
-        await writeStoreToDisk(store);
-        return created;
+        return { result: created, dirty: true };
     });
 }
 export async function rotateLocalClientToken(input) {
-    return enqueue(async () => {
-        const store = await loadLocalClientTokenStore();
+    const now = input.now ?? Date.now();
+    let created = null;
+    return updateLocalClientTokenStore((store) => {
         const existing = store.tokens.find((record) => record.id === input.id);
-        if (!existing || existing.revokedAt !== null)
-            return null;
-        const now = input.now ?? Date.now();
+        if (!existing || existing.revokedAt !== null) {
+            return { result: null, dirty: false };
+        }
         existing.revokedAt = now;
-        const created = createLocalClientTokenRecord({
+        // Same record across CAS retries so a retry cannot mint a second token.
+        created ??= createLocalClientTokenRecord({
             label: input.label ?? existing.label,
             now,
         });
         store.tokens.push(created.record);
-        await writeStoreToDisk(store);
-        return created;
+        return { result: created, dirty: true };
     });
 }
 export async function revokeLocalClientToken(id, now = Date.now()) {
-    return enqueue(async () => {
-        const store = await loadLocalClientTokenStore();
+    return updateLocalClientTokenStore((store) => {
         const existing = store.tokens.find((record) => record.id === id);
-        if (!existing || existing.revokedAt !== null)
-            return false;
+        if (!existing || existing.revokedAt !== null) {
+            return { result: false, dirty: false };
+        }
         existing.revokedAt = now;
-        await writeStoreToDisk(store);
-        return true;
+        return { result: true, dirty: true };
     });
 }
 export async function verifyLocalClientBearerToken(authorizationHeader, now = Date.now()) {
@@ -236,11 +331,10 @@ export async function verifyLocalClientBearerToken(authorizationHeader, now = Da
     if (!token)
         return null;
     const tokenHash = hashToken(token);
-    return enqueue(async () => {
-        const store = await loadLocalClientTokenStore();
-        const record = store.tokens.find((entry) => entry.revokedAt === null && entry.tokenHash === tokenHash);
+    return updateLocalClientTokenStore((store) => {
+        const record = store.tokens.find((entry) => entry.revokedAt === null && tokenHashEqual(entry.tokenHash, tokenHash));
         if (!record)
-            return null;
+            return { result: null, dirty: false };
         // Token match (verification correctness) is decided above and never
         // depends on lastUsedAt. Always advance lastUsedAt in-memory so callers
         // see a fresh value, but only flush to disk when it has not been
@@ -249,10 +343,11 @@ export async function verifyLocalClientBearerToken(authorizationHeader, now = Da
         // recent usage on a coarse (>=60s) cadence.
         const persisted = record.lastUsedAt;
         record.lastUsedAt = now;
-        if (persisted === null || now - persisted >= LAST_USED_PERSIST_THRESHOLD_MS) {
-            await writeStoreToDisk(store);
-        }
-        return record;
+        return {
+            result: record,
+            dirty: persisted === null ||
+                now - persisted >= LAST_USED_PERSIST_THRESHOLD_MS,
+        };
     });
 }
 export function resetLocalClientTokenWriteQueueForTests() {

package/dist/lib/logger.d.ts

@@ -45,4 +45,3 @@ export interface ScopedLogger {
 export declare function createLogger(scope: string): ScopedLogger;
 export declare function getRequestId(): number;
 export { formatDuration, maskEmail, maskString, maskToken, sanitizeValue };
-//# sourceMappingURL=logger.d.ts.map

package/dist/lib/logger.js

@@ -21,7 +21,17 @@ const TOKEN_PATTERNS = [
     // line of defense and must recognize the project's own token shape too.
     /cma_local_[A-Za-z0-9_-]{16,}/g,
 ];
-const EMAIL_PATTERN = /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g;
+// Label-shaped domain instead of `[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}`: letting `.`
+// live inside the quantified class makes every dot a candidate split point,
+// which backtracked quadratically (~3.5s) on dotted near-miss input. Labels
+// are dot-free, so each dot has exactly one structural role.
+// The `(?<!...)` lookbehind confines match starts to a run boundary: the
+// unanchored pattern could otherwise begin inside an overlong local part or
+// domain label and leave its leading/trailing edge visible in logs. Interior
+// positions fail the lookbehind in O(1), which is also what keeps the
+// unbounded quantifiers linear — each character run is scanned once from its
+// edge instead of being rescanned from every offset.
+const EMAIL_PATTERN = /(?<![a-zA-Z0-9._%+-])[a-zA-Z0-9._%+-]+@[a-zA-Z0-9-]+(?:\.[a-zA-Z0-9-]+)*\.[a-zA-Z]{2,}/g;
 const SENSITIVE_KEYS = new Set([
     "access",
     "accesstoken",

package/dist/lib/model-capability-matrix.d.ts

@@ -35,4 +35,3 @@ export declare function buildModelCapabilityMatrix(input: {
     quotaCache?: QuotaCacheData | null;
     now?: number;
 }): ModelCapabilityMatrix;
-//# sourceMappingURL=model-capability-matrix.d.ts.map

package/dist/lib/model-route-policy.d.ts

@@ -44,9 +44,8 @@ export declare function modelEntitlements(model: RouteModel): {
     reasoningLevels: string[];
     accessPrograms: string[];
     probes?: {
-        [k: string]: "unsupported" | "verified" | "unverified" | "downgraded";
+        [k: string]: "verified" | "unsupported" | "unverified" | "downgraded";
     } | undefined;
     checkedAt?: number | undefined;
     model: string;
 };
-//# sourceMappingURL=model-route-policy.d.ts.map

package/dist/lib/named-backup-export.d.ts

@@ -66,4 +66,3 @@ export declare function resolveNamedBackupPath(name: string, storagePath: string
 export declare function exportNamedBackupFile(name: string, dependencies: NamedBackupExportDependencies, options?: {
     force?: boolean;
 }): Promise<string>;
-//# sourceMappingURL=named-backup-export.d.ts.map

package/dist/lib/oc-chatgpt-import-adapter.d.ts

@@ -61,4 +61,3 @@ export declare function previewOcChatgptImportMerge(options: {
     destination: AccountStorageV3 | null;
 }): OcChatgptMergePreview;
 export {};
-//# sourceMappingURL=oc-chatgpt-import-adapter.d.ts.map

package/dist/lib/oc-chatgpt-orchestrator.d.ts

@@ -83,4 +83,3 @@ export type RunNamedBackupExportResult = {
 };
 export declare function runNamedBackupExport(options: RunNamedBackupExportOptions): Promise<RunNamedBackupExportResult>;
 export {};
-//# sourceMappingURL=oc-chatgpt-orchestrator.d.ts.map

package/dist/lib/oc-chatgpt-target-detection.d.ts

@@ -35,7 +35,8 @@ export type OcChatgptTargetDetectionResult = OcChatgptTargetFound | OcChatgptTar
 /**
  * Detects the oc-chatgpt multi-auth storage target by evaluating explicit, canonical, and per-project candidate roots.
  *
- * Examines an explicit override (OC_CHATGPT_MULTI_AUTH_DIR or options.explicitRoot), the canonical user store (~/.opencode),
+ * Examines an explicit override (OC_CODEX_MULTI_AUTH_DIR, the legacy OC_CHATGPT_MULTI_AUTH_DIR alias, or
+ * options.explicitRoot), the canonical user store (~/.opencode),
  * and a per-project storage location (derived from options.projectRoot or the current working directory). For each candidate
  * it checks for account artifacts and storage signals and returns a single resolved target, an ambiguity listing multiple
  * matching candidates, or a "none" result with the attempted candidates. This function performs synchronous filesystem checks
@@ -45,7 +46,7 @@ export type OcChatgptTargetDetectionResult = OcChatgptTargetFound | OcChatgptTar
  *
  * @param options - Optional overrides:
  *   - explicitRoot: absolute path to force as the candidate root (use `null` to explicitly disable); if omitted the
- *     OC_CHATGPT_MULTI_AUTH_DIR environment variable is considered.
+ *     OC_CODEX_MULTI_AUTH_DIR environment variable is considered, then the legacy OC_CHATGPT_MULTI_AUTH_DIR alias.
  *   - projectRoot: explicit project root to derive per-project storage; if omitted the current working directory is used to
  *     discover the project root.
  * @returns An OcChatgptTargetDetectionResult describing either a resolved `target` (with `descriptor` and a `resolution`
@@ -56,4 +57,3 @@ export declare function detectOcChatgptMultiAuthTarget(options?: {
     projectRoot?: string | null;
 }): OcChatgptTargetDetectionResult;
 export {};
-//# sourceMappingURL=oc-chatgpt-target-detection.d.ts.map

package/dist/lib/oc-chatgpt-target-detection.js

@@ -2,7 +2,14 @@ import { existsSync, readdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, normalize, relative, resolve, sep, win32 } from "node:path";
 import { findProjectRoot, getProjectStorageKey, resolveProjectStorageIdentityRoot, } from "./storage/paths.js";
-const ACCOUNT_FILE_NAME = "openai-codex-accounts.json";
+// The sibling plugin renamed its account file from `openai-codex-accounts.json`
+// (oc-chatgpt-multi-auth era) to `oc-codex-multi-auth-accounts.json`; both are
+// detected, preferring the current name when a root holds both.
+const ACCOUNT_FILE_NAMES = [
+    "oc-codex-multi-auth-accounts.json",
+    "openai-codex-accounts.json",
+];
+const ACCOUNT_FILE_NAME = ACCOUNT_FILE_NAMES[0];
 const BACKUPS_DIR_NAME = "backups";
 const PROJECTS_DIR_NAME = "projects";
 const CANONICAL_HOME_BASENAME = ".opencode";
@@ -107,17 +114,32 @@ function deduplicatePaths(paths) {
     }
     return result;
 }
+/**
+ * Returns the path of the primary account file under `root`, preferring the
+ * current `oc-codex-multi-auth-accounts.json` name over the legacy
+ * `openai-codex-accounts.json` name when both exist, or `null` when neither
+ * file (nor its `.wal` sidecar) is present.
+ */
+function findPrimaryAccountPath(root) {
+    for (const name of ACCOUNT_FILE_NAMES) {
+        const accountPath = join(root, name);
+        if (existsSync(accountPath) || existsSync(`${accountPath}.wal`)) {
+            return accountPath;
+        }
+    }
+    return null;
+}
 /**
  * Detects whether an account file or rotated account artifacts exist under the specified storage root.
  *
- * Scans for the canonical account file and its WAL variant, rotated/archived files matching the account filename pattern (excluding `.tmp`, `.wal`, and names containing `.rotate.`), and the backups directory. The probe is tolerant of unreadable directories (errors are ignored) and does not read file contents. Callers should be aware of concurrent filesystem changes — a `false` result does not guarantee no artifact will appear shortly after. On Windows, filesystem matching should be considered case-insensitive by callers. This check does not expose or parse any token contents.
+ * Scans for an account file under either known name (`oc-codex-multi-auth-accounts.json` or the legacy `openai-codex-accounts.json`) and its WAL variant, rotated/archived files matching either account filename pattern (excluding `.tmp`, `.wal`, and names containing `.rotate.`), and the backups directory. The probe is tolerant of unreadable directories (errors are ignored) and does not read file contents. Callers should be aware of concurrent filesystem changes — a `false` result does not guarantee no artifact will appear shortly after. On Windows, filesystem matching should be considered case-insensitive by callers. This check does not expose or parse any token contents.
  *
  * @param root - Filesystem path of the storage root to probe
+ * @param primaryAccountPath - Result of `findPrimaryAccountPath(root)`, so callers resolve the descriptor path once
  * @returns `true` if any account file or rotated account artifact exists under `root` or its backups directory, `false` otherwise.
  */
-function hasAccountArtifacts(root) {
-    const accountPath = join(root, ACCOUNT_FILE_NAME);
-    if (existsSync(accountPath) || existsSync(`${accountPath}.wal`)) {
+function hasAccountArtifacts(root, primaryAccountPath) {
+    if (primaryAccountPath !== null) {
         return true;
     }
     const hasRotated = (dir) => {
@@ -126,7 +148,7 @@ function hasAccountArtifacts(root) {
             for (const entry of entries) {
                 if (!entry.isFile())
                     continue;
-                if (!entry.name.startsWith(`${ACCOUNT_FILE_NAME}.`))
+                if (!ACCOUNT_FILE_NAMES.some((name) => entry.name.startsWith(`${name}.`)))
                     continue;
                 if (entry.name.endsWith(".tmp"))
                     continue;
@@ -146,7 +168,7 @@ function hasAccountArtifacts(root) {
         return true;
     }
     const backupsDir = join(root, BACKUPS_DIR_NAME);
-    if (existsSync(join(backupsDir, ACCOUNT_FILE_NAME))) {
+    if (ACCOUNT_FILE_NAMES.some((name) => existsSync(join(backupsDir, name)))) {
         return true;
     }
     if (hasRotated(backupsDir)) {
@@ -191,7 +213,8 @@ function inferScopeFromRoot(root, canonicalRoot) {
 /**
  * Detects the oc-chatgpt multi-auth storage target by evaluating explicit, canonical, and per-project candidate roots.
  *
- * Examines an explicit override (OC_CHATGPT_MULTI_AUTH_DIR or options.explicitRoot), the canonical user store (~/.opencode),
+ * Examines an explicit override (OC_CODEX_MULTI_AUTH_DIR, the legacy OC_CHATGPT_MULTI_AUTH_DIR alias, or
+ * options.explicitRoot), the canonical user store (~/.opencode),
  * and a per-project storage location (derived from options.projectRoot or the current working directory). For each candidate
  * it checks for account artifacts and storage signals and returns a single resolved target, an ambiguity listing multiple
  * matching candidates, or a "none" result with the attempted candidates. This function performs synchronous filesystem checks
@@ -201,14 +224,17 @@ function inferScopeFromRoot(root, canonicalRoot) {
  *
  * @param options - Optional overrides:
  *   - explicitRoot: absolute path to force as the candidate root (use `null` to explicitly disable); if omitted the
- *     OC_CHATGPT_MULTI_AUTH_DIR environment variable is considered.
+ *     OC_CODEX_MULTI_AUTH_DIR environment variable is considered, then the legacy OC_CHATGPT_MULTI_AUTH_DIR alias.
  *   - projectRoot: explicit project root to derive per-project storage; if omitted the current working directory is used to
  *     discover the project root.
  * @returns An OcChatgptTargetDetectionResult describing either a resolved `target` (with `descriptor` and a `resolution`
  *   of `"accounts"` or `"signals"`), an `ambiguous` outcome listing conflicting candidates, or `none` with the tried candidates.
  */
 export function detectOcChatgptMultiAuthTarget(options) {
-    const explicitFromEnv = (process.env.OC_CHATGPT_MULTI_AUTH_DIR ?? "").trim();
+    const explicitFromEnv = (firstNonEmpty([
+        process.env.OC_CODEX_MULTI_AUTH_DIR,
+        process.env.OC_CHATGPT_MULTI_AUTH_DIR,
+    ]) ?? "").trim();
     const hasExplicitRootOption = options !== undefined && "explicitRoot" in options;
     const explicitRoot = (hasExplicitRootOption ? (options.explicitRoot ?? "") : explicitFromEnv).trim();
     const userHome = getResolvedUserHomeDir();
@@ -233,9 +259,10 @@ export function detectOcChatgptMultiAuthTarget(options) {
             : inferredScope === "project"
                 ? "project"
                 : "default-global";
-        const accountPath = join(root, ACCOUNT_FILE_NAME);
+        const primaryAccountPath = findPrimaryAccountPath(root);
+        const accountPath = primaryAccountPath ?? join(root, ACCOUNT_FILE_NAME);
         const backupRoot = join(root, BACKUPS_DIR_NAME);
-        const hasAccountArtifactsFlag = hasAccountArtifacts(root);
+        const hasAccountArtifactsFlag = hasAccountArtifacts(root, primaryAccountPath);
         return {
             scope: inferredScope,
             source,
@@ -314,7 +341,7 @@ export function detectOcChatgptMultiAuthTarget(options) {
     }
     return {
         kind: "none",
-        reason: "No oc-chatgpt-multi-auth target root found; create ~/.opencode or supply OC_CHATGPT_MULTI_AUTH_DIR.",
+        reason: "No oc-chatgpt-multi-auth target root found; create ~/.opencode or supply OC_CODEX_MULTI_AUTH_DIR (legacy OC_CHATGPT_MULTI_AUTH_DIR is still accepted).",
         tried: candidates.map(({ scope, source, root, accountPath, backupRoot }) => ({
             scope,
             source,

package/dist/lib/parallel-probe.d.ts

@@ -32,4 +32,3 @@ export declare function getTopCandidates(accountManager: AccountManager, modelFa
  */
 export declare function probeAccountsInParallel<T>(candidates: ProbeCandidate[], probeFn: (account: ManagedAccount, signal: AbortSignal) => Promise<T>, _options?: Partial<ParallelProbeOptions>): Promise<ProbeResult<T> | null>;
 export declare function createProbeCandidates(accounts: ManagedAccount[]): ProbeCandidate[];
-//# sourceMappingURL=parallel-probe.d.ts.map

package/dist/lib/policy/runtime-policy-cache.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Hot-path caches for the runtime policy stores.
+ *
+ * `loadRuntimePolicyState` runs once per proxied request, and the proxy is a
+ * long-running process while the stores are mutated by separate CLI processes
+ * (`account pause`, `budget`, `routing profile`). The naive path re-read +
+ * re-parsed three JSON files and re-walked the project-root ancestor chain on
+ * every request. These caches keep semantics identical while reducing the
+ * steady-state cost to a handful of `statSync` calls:
+ *
+ * - Store entries are keyed by absolute file path and guarded by an
+ *   `mtimeMs:ctimeMs:size` fingerprint (same approach as
+ *   `lib/runtime/rotation-storage-meta.ts`): the store is only re-read when
+ *   the fingerprint changes. `ctimeMs` is part of the fingerprint because it
+ *   cannot be pinned back the way `mtimeMs` can — on POSIX every write bumps
+ *   it, and on Windows every rename-replacement produces a new file creation
+ *   time — so a rewrite that preserves mtime+size is still caught instead of
+ *   being served stale for the TTL. A fingerprint match is additionally only
+ *   trusted once the file's own mtime has settled past `MTIME_SETTLE_MS` —
+ *   two rapid writes can share a coarse mtime tick on some filesystems (FAT
+ *   2s, ~1s Windows/network volumes), so inside the settle window we always
+ *   re-read. `STORE_CACHE_TTL_MS` bounds staleness for the pathological case
+ *   where a rewrite leaves mtime, ctime and size unchanged, and
+ *   `STORE_CACHE_MAX_ENTRIES` bounds the map (tests rotate through many
+ *   per-test `CODEX_MULTI_AUTH_DIR` temp dirs).
+ *
+ *   Two failure modes get dedicated handling so they cannot poison the cache:
+ *   a file rewritten *while* the loader is reading it is detected by
+ *   re-statting after the load and only caching when the fingerprint is
+ *   stable across the read (an old parse is never stored under the new
+ *   file's fingerprint); and a read that resolves to the empty store while
+ *   bytes still exist on disk — exhausted EBUSY/EPERM retries or corrupt
+ *   JSON both surface as `emptyStore()` from the loaders — is served but
+ *   never cached, so a transient failure cannot hide a real policy for the
+ *   full TTL.
+ *
+ * - Project resolution (`findProjectRoot` + `resolveProjectStorageIdentityRoot`
+ *   + `getProjectStorageKey`) is cached per resolved startDir for
+ *   `PROJECT_RESOLUTION_TTL_MS` and guarded by two fingerprints: an
+ *   mtime/ctime/size fingerprint of the resolved root's `.git` entry — the file
+ *   whose contents drive worktree identity resolution — and the joined
+ *   fingerprints of every ancestor directory that could host a marker, whose
+ *   mtimes change when a marker file is created or deleted. Entries
+ *   therefore invalidate when the project context differs (different
+ *   startDir key, different resolved root), when the `.git` entry changes,
+ *   or when a marker appears/disappears in a watched ancestor — the TTL is
+ *   only the residual bound for coarse-mtime filesystems that report no
+ *   change at all.
+ *
+ * Values held in the caches are shared, mutable objects. Callers must treat
+ * returned values as read-only; `loadRuntimePolicyState` clones what it hands
+ * out.
+ */
+import { type AccountPolicyStore } from "../account-policy.js";
+import { type BudgetGuardStore } from "../budget-guard.js";
+import { type ProjectRoutingProfileContext } from "../routing-profiles.js";
+/**
+ * Cached variant of `loadAccountPolicyStore`. The returned store is shared
+ * cache state — treat as read-only.
+ */
+export declare function loadAccountPolicyStoreCached(): Promise<AccountPolicyStore>;
+/**
+ * Cached variant of `loadBudgetGuardStore`. The returned store is shared
+ * cache state — treat as read-only.
+ */
+export declare function loadBudgetGuardStoreCached(): Promise<BudgetGuardStore>;
+/**
+ * Cached variant of `resolveProjectRoutingProfile` for the per-request path.
+ * The project context (root/identity/key) comes from the bounded resolution
+ * cache; the profile itself is re-derived on every call from the
+ * fingerprint-guarded routing-profiles store, so profile edits are picked up
+ * as soon as the file's mtime/size changes and distinct project contexts can
+ * never observe each other's entries.
+ */
+export declare function resolveProjectRoutingProfileCached(startDir?: string): Promise<ProjectRoutingProfileContext>;
+/**
+ * Test-only: drop every cached store value and project resolution so each
+ * test starts from a clean read-from-disk state.
+ */
+export declare function resetRuntimePolicyCacheForTests(): void;