@epoch-agent/core 1.1.0 → 2.0.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ToolProvider, EpochTool, EpochPlugin, ToolExposure, EpochSkill, HookType, EpochHook, PluginContext, QuestionRequest, QuestionAnswer, ComplianceCategory, ComplianceAction, ToolArtifactInput, ToolArtifact, TrustLevel, TrustManager as TrustManager$1, TokenUsage, EpochConfig, BudgetBreach, NoticeCode, ProviderType, EpochMessage, JsonSchema, ModelSelection, BackgroundTaskInfo, EpochToolCall, Telemetry, HookManager as HookManager$1, Lang, PermissionManager as PermissionManager$1, ApprovalRequest, ApprovalReply, AgentRoleScope, AgentRoleSource, EpochUserContent, EpochContentPart, AgentRole, PermissionLevel, PlanProposal, ScheduleDefinition, DiagnosticSink, CustomCommandDef, ModelRef, ExpandedCommand, CustomCommandSource, ContextBreakdown, WireMcpConnector, AgentEvent, SelectionContext, SetSelectionResult, MoneyDigits, CurrencyDisplay, PermissionRuleLists, KeybindingTable, Diagnostic, KeybindingReport, FileOmitReason, SessionOmitReason, EpochToolResult, EpochTurnFacts, LocalizedDetail, ApprovalScope, OperationType, RuleValue, Operation, ApprovalOutcome, PermissionDecision, ScheduleTrigger, ScheduleAllowlist, ScheduleBackendKind, ScheduleRunStatus, ScheduleRun, SchedulePendingApproval, ScheduleDraft, ScheduleWideningKind, WireAgentEvent, WireAgentEnvelope, ScheduleRunnerSpec, HookEvent, LogFn, HookRegistration, HookHandler, HookContext, VerifyResult, EpochFilePart, EpochSessionPart, MentionSet, EpochImagePart, TrustExecGrant, DecidedTrustLevel, TrustScope, TrustGrant, TrustRecord } from '@epoch-agent/protocol';
+import { ToolProvider, EpochTool, EpochPlugin, ToolExposure, EpochSkill, HookType, EpochHook, PluginContext, QuestionRequest, QuestionAnswer, ComplianceCategory, ComplianceAction, ToolArtifactInput, ToolArtifact, TrustLevel, TrustManager as TrustManager$1, TokenUsage, EpochConfig, BudgetBreach, NoticeCode, ProviderType, EpochMessage, JsonSchema, ModelSelection, BackgroundTaskInfo, EpochToolCall, Telemetry, HookManager as HookManager$1, Lang, PermissionManager as PermissionManager$1, ApprovalRequest, ApprovalReply, AgentRoleScope, AgentRoleSource, EpochUserContent, EpochContentPart, AgentRole, PermissionLevel, PlanProposal, ScheduleDefinition, DiagnosticSink, CustomCommandDef, ModelRef, ExpandedCommand, CustomCommandSource, ContextBreakdown, WireMcpConnector, AgentEvent, SelectionContext, SetSelectionResult, ModelEntry, ReasoningState, ReasoningChoice, PermissionRuleLists, MoneyDigits, CurrencyDisplay, KeybindingTable, Diagnostic, KeybindingReport, FileOmitReason, SessionOmitReason, EpochToolResult, EpochTurnFacts, LocalizedDetail, ApprovalScope, OperationType, RuleValue, Operation, ApprovalOutcome, PermissionDecision, ScheduleTrigger, ScheduleAllowlist, ScheduleBackendKind, ScheduleRunStatus, ScheduleRun, SchedulePendingApproval, ScheduleDraft, ScheduleWideningKind, WireAgentEvent, WireAgentEnvelope, ScheduleRunnerSpec, HookEvent, LogFn, HookRegistration, HookHandler, HookContext, VerifyResult, EpochFilePart, EpochSessionPart, MentionSet, EpochImagePart, TrustExecGrant, DecidedTrustLevel, TrustScope, TrustGrant, TrustRecord } from '@epoch-agent/protocol';
 export { API_KEY_ENV_VARS, AgentEvent, AgentEventOf, AgentEventType, ApprovalAnswer, ApprovalOutcome, ApprovalReply, ApprovalRequest, ApprovalScope, BudgetBreach, COMPLIANCE_ACTIONS, COMPLIANCE_CATEGORIES, ComplianceAction, ComplianceCategory, DecidedTrustLevel, EpochConfig, EpochHook, EpochPlugin, EpochSkill, EpochTool, FinishReason, HookContext, HookEvent, HookHandler, HookRegistration, HookType, HookManager as IHookManager, PermissionManager as IPermissionManager, TrustManager as ITrustManager, JsonSchema, MAX_ATTACH_BYTES, MAX_ATTACH_FILES, MAX_ATTACH_TOTAL_BYTES, MAX_SESSION_ATTACH_BYTES, MAX_SESSION_REFS, OPERATION_TYPES, Operation, OperationType, PERMISSION_LEVELS, PLAN_OUTCOMES, PROVIDER_INFOS, PROVIDER_TYPES, PermissionDecision, PermissionLevel, PlanApprovalOutcome, PlanProposal, PluginContext, ProviderInfo, ProviderType, TokenUsage, ToolContext, ToolDefinition, ToolExposure, ToolResult, TrustExecGrant, TrustGrant, TrustLevel, TrustRecord, TrustScope, TrustTier, VerifyResult, apiKeyEnvVar, extractAllMentions, extractMentions, extractSessionMentions, getProviderInfo, isOperationType, isPermissionLevel, isPlanOutcome, isProviderType, normalizeApproval } from '@epoch-agent/protocol';
 import { IsolationBackend, SqliteDatabase, ParseIssue, ShellFlavor } from '@epoch-agent/infra';
 export { BubblewrapOptions, DangerMatch, IS_WINDOWS, IsolationBackend, IsolationOptions, LogLevel, SeatbeltOptions, WINDOWS_HIDE_FLAGS, buildBwrapArgs, buildProfile, checkDangerousCommand, checkObfuscation, createLogger, detectBackend, getDefaultShell, getPythonCommand, isInWorkspace, isReadOnlyCommand, isolate, maskApiKey, probeBubblewrap, probeSeatbelt, complianceDir as resolveComplianceDir, policiesDir as resolvePoliciesDir, setLogLevel } from '@epoch-agent/infra';
@@ -2250,18 +2250,15 @@ interface GenerateInput {
      */
     signal?: AbortSignal;
     /**
-     * 这一次用哪个 provider（方案 19）。不给 = 配置里的主 provider。
+     * 这一次走「我的模型」里的哪个条目（方案 19 → 2.0.0）。不给 = 当前 selection。
      *
-     * router 内部**本来就是多 provider 的**（`initFactories` 把所有配了 key 的
-     * 家都注册进 `available`，那是为 fallback 建的），这两个字段只是把已经存在的
-     * 能力开一个主动入口。
+     * 点名了就是「就要这个」：压缩器、起标题这类内部杂活拿 `UtilityModelInfo.selection.entry`
+     * 点名副模型。条目不存在或没凭据时**报错，不静默退回当前那条** —— 静默退回会让
+     * 「我明明配了便宜模型怎么账单没降」变成无从排查的事。
      *
-     * 覆盖到一个没配凭据的 provider 会**报错，不静默退回主 provider** ——
-     * 静默退回会让「我明明配了便宜模型怎么账单没降」变成无从排查的事。
+     * 2.0.0 之前还有 `provider` / `model` 两格（点名一家 + 一个裸模型名），随老写法删了。
      */
-    provider?: ProviderType;
-    /** 这一次用哪个模型。不给 = 当前 selection（方案 26 之前是 `config.model`） */
-    model?: string;
+    entry?: string;
     /**
      * 强制结构化输出（方案 59 §2.1）。**provider 无关** —— 底下走 AI SDK 的 `Output`，
      * 由它翻成各家的原生机制，**不是**往请求里塞 `response_format`（那是 OpenAI 的
@@ -2445,7 +2442,7 @@ interface UtilityModelInfo {
     selection: ModelSelection;
     /** 用户显式配过 `models.utility` 吗 */
     configured: boolean;
-    /** 配了但用不了的原因（解析不出来 / 那家没凭据）。此时 selection 已退回主模型 */
+    /** 配了但用不了的原因（解析不出来 / 那一条没凭据）。此时 selection 已退回主模型 */
     issue?: string;
 }
 
@@ -10478,11 +10475,24 @@ declare class ProviderRouter {
      * 不碰任何 SDK —— SDK 到第一次真正要模型时才 import。
      */
     private available;
-    /** 已加载的工厂缓存，key 相同则复用 */
+    /**
+     * 已加载的工厂缓存，key 相同则复用。
+     *
+     * 这两张表的 key 是**路由键**（2026-10-15）：「我的模型」里的条目是 `@<id>` ——
+     * 同一家两套端点（官方 + 中转）就是两个 key。判据在 `entry-route.ts` 的文件头。
+     */
     private factories;
-    private credentialIndex;
-    /** provider 凭据的查找视图（process.env + ~/.epoch/.env），构造时快照一次 */
-    private readonly keyEnv;
+    /**
+     * 「我的模型」条目表。构造时从 config 拿一次；存 / 删之后由 {@link reloadModelEntries}
+     * 整批换掉（开着的会话也要看得见新表）
+     */
+    private entryTable;
+    /**
+     * 这段会话手动选的推理强度（输入框旁那张「选择强度」卡，2026-10-15）。
+     * `undefined` = 没选过，用条目声明的默认档。**换模型就清掉**：档位是对那一条说的，
+     * 换到一条只认「低 / 高」的模型上还拿着「中」，发出去就是一个它不认的值
+     */
+    private effort;
     /**
      * 遥测出口（方案 14）。降级是最值得被观测的一件事 —— 它同时意味着
      * 「主 provider 出问题了」和「这次请求换了个模型、单价可能不一样」。
@@ -10511,7 +10521,7 @@ declare class ProviderRouter {
      * 分家之后「`reset` 会把你送回哪儿」只有这一格答得上，所以它有了一个读口：
      * {@link getConfiguredModel}。
      */
-    private readonly configSelection;
+    private configSelection;
     /** 模型连续失败的节流状态（方案 26 验收 #8）。只在本会话内有效，不落盘 */
     private readonly failures;
     /**
@@ -10526,6 +10536,10 @@ declare class ProviderRouter {
     private readonly notices;
     /** 装配层注入遥测。不注入就是零分配空转 */
     setTelemetry(telemetry: Telemetry): void;
+    /**
+     * @throws {ProviderError} `PROVIDER_NO_CREDENTIAL`：还没有模型（`model` 没配 / 指向的条目不在），
+     *   或者那一条没有可用的 key。装配层据此进「没有可用模型」那一档（Web 只读、引导去加一条）
+     */
     constructor(config: EpochConfig);
     /** 当前生效的选择。回一份拷贝，免得调用方改到内部状态 */
     getSelection(): ModelSelection;
@@ -10540,7 +10554,7 @@ declare class ProviderRouter {
      */
     getConfiguredModel(): string;
     /**
-     * 换模型。`next.provider` 不给就是「同一家换个模型」。
+     * 换模型：换到「我的模型」里的另一条。
      *
      * **换模型不清空上下文**——那正是它的意义所在（对着同一段对话换个更强/更便宜
      * 的脑子）。代价是新模型必须接得住已经积累的东西，所以有 {@link SelectionContext}
@@ -10571,6 +10585,28 @@ declare class ProviderRouter {
      * 比不换更难排查。
      */
     private applySelection;
+    /**
+     * 换一张条目表（2026-10-15）：设置页存 / 删一条之后，**已经开着的会话**也要看得见。
+     *
+     * 不换的话这段会话一直拿着构造那一刻的表：新加的那条切不过去（`unknown-entry`），改过的
+     * key / 地址 / 模型名不生效，删掉的那条还拿着缓存的工厂照打。runtime 存完对每个活着的
+     * router 调一次（`SessionModels.reloadEntries`）。
+     *
+     * - 条目路由和它们的工厂缓存整批撤掉、重新注册（key 现读，同构造时的 `registerEntries`）；
+     * - 选中的、以及「回到配置里那个」那一格落在条目上的，按新表刷新（改了模型名跟着改）；
+     * - 选中的那条被删了：回到配置里那个，留一条通知；
+     * - 手选的强度在新表里不成立了（档位撤了 / 不许关了）就清掉，同 `setEffort` 的判据。
+     */
+    reloadModelEntries(entries: readonly ModelEntry[] | undefined): void;
+    /**
+     * 选择按当前表刷新（改了模型名跟着改）；那条**没了或者这会儿用不了**回 `undefined`。
+     *
+     * ⚠️ 「还在表里」不够，还得在 `available` 里（= 这一轮真有凭据可用）。只看表的话，
+     * 选中那条被清掉 key 之后每一发都在 `startPoint` 当场抛 `cannot_use` —— 那一句在
+     * 重试 / 降级两条循环**之外**，于是降级链一次都走不到、用户也没有任何通知，看起来
+     * 就是「这个模型坏了」。两条成因（删了 / 没 key）由调用处按这张表分句。
+     */
+    private refreshedSelection;
     /**
      * 取走攒下的通知，队列清空（方案 26 验收 #8）。
      *
@@ -10578,6 +10614,19 @@ declare class ProviderRouter {
      * 留着的话下一轮会再报一遍同一件旧事。
      */
     drainNotices(): string[];
+    /** 此刻这段会话的推理强度，形状见 protocol 的 `ReasoningState` */
+    getEffort(): ReasoningState;
+    /**
+     * 选一档。`null` = 回到条目的默认档。不在这一条声明的档位里（或者它不许关）就不动、回 false ——
+     * 发一个端点不认的值出去，换来的是一次计费过的 400
+     */
+    setEffort(choice: ReasoningChoice | null): boolean;
+    /**
+     * 这一发请求带不带强度参数。只有**主循环那种不点名的请求**、而且此刻还落在选中的那一条上才带：
+     * 点名的那几种（压缩 / 起标题这类杂活）不该被用户给主对话选的强度拖慢；
+     * 降级落到别处的那一发也不带 —— 那个档位是对原来那一条说的。
+     */
+    private reasoningFor;
     /**
      * `models.utility` 解析到哪儿了（方案 26 §2.5）。
      *
@@ -10587,20 +10636,53 @@ declare class ProviderRouter {
      * 已经不该用了）。没配 utility 的含义是「跟着主模型走」，不是「跟着启动值走」。
      */
     getUtilityInfo(): UtilityModelInfo;
+    /**
+     * 注册凭据：条目逐个注册 —— 宿主条目也在其中（它的 baseUrl 是网关地址，见 host-preset）。
+     * 配置里那一条（主模型）注册不上 = 没有可用 key，当场抛 —— 装配层据此进「没有可用模型」那一档。
+     */
     private initFactories;
-    /** 记下凭证；换 key 时同时废掉旧工厂缓存 */
-    private register;
-    private resolveKey;
     /**
-     * fallback provider 的凭据。
+     * 「我的模型」里的条目逐个注册，路由键 `@<id>`（2026-10-15）。
      *
-     * 变量名走 protocol 的 `apiKeyEnvVar()` —— 这里原先维护着**第二份** provider →
-     * 环境变量名的映射表。两份副本历史上就不一致过（Moonshot / Together 配了用不了），
-     * 而且 `.env` 里的 key 只有 loader 读得到、这里只读 process.env，
-     * 于是「`epoch model` 配好的 key 引擎看不见」。现在两端查同一份清单，
-     * `.env` 的注入也由 loader 统一负责（见 `applySecretsFromEnv`）。
+     * **key 只有一个来源：条目自己那一把**（`EPOCH_MODEL_KEY_<id>`，设置页存进钥匙串）。
+     * 2026-10-15 之前还会往下退两档 —— 同家时借 `config.provider.apiKey`、不同家时借那家的
+     * 环境变量 key —— 理由是「同一个官方端点，只是换个模型 + 能力声明，不想再粘一遍」。
+     * 那一档取消了：一把 key 是**发给某个端点**的，而「没填地址」只承诺了「那家的官网」，
+     * 主 provider 的地址 / 环境变量却可能指向一个中转站（`DEEPSEEK_API_KEY` 这个名字底下
+     * 完全可以是中转站的 key），借来的那把于是被发到了它不是发给的那个地方。取消之后
+     * 「这条用哪把 key」永远只有条目自己一个答案。
+     *
+     * 没 key 也注册的有三类：自定义端点、ollama、**宿主条目**（`host: true`）。
+     *
+     * - 前两类：本地起的兼容端点多半不要 key；
+     * - ⚠️ 宿主条目是 2026-10-16 用户拍板加的（在那之前它按「别家」处理：没 key 就不注册
+     *   —— 内建 provider 的宿主条目于是**构造就抛**，整台机器一个会话都建不出来）。
+     *   判据是原话：「宿主自定义的模型，可能是不需要 apikey 的，可能调用自己的网关时有
+     *   自己的权限判断，所以这个 key 在宿主这里应该是不是必填的」。宿主条目的凭据本来
+     *   就该由宿主那一侧的 fetch 桥按网关 origin 注入（判据在 `entry-route.ts` 的文件头），
+     *   条目自己一把都没有是**正当形态**，不是缺配置。
+     *   ⚠️ 真打出去没带鉴权头时，provider 会回 401/403 —— 那是**宿主网关那一侧**要说的话，
+     *   我们这一层不预先拦（预先拦会把「宿主网关自己会鉴权」这种配法误杀）。
+     *
+     * 别家用户条目没 key 就是「没凭据」：不注册，换过去时由 `no-credential` 那一档拦住。
+     */
+    private registerEntries;
+    /** 路由键，判据在 `entry-route.ts` 的 `routeKey` 上 */
+    private routeOf;
+    /** 元数据表的结论 + 条目的覆盖。所有「这个模型能做什么」的判断都过这一道 */
+    private capabilityFor;
+    /**
+     * `config.model` 解析成一次选择。
+     *
+     * 没配、或者那一条不在「我的模型」里：**抛 `no_model`**，不造一个模型出来。2.0.0 之前这里退到
+     * 主 provider 的默认模型（`gpt-4o-mini` 那一套），随老写法删了 —— 今天「还没有模型」是一个
+     * 正常状态，装配层接住它、界面引导用户去加一条。
      */
-    private getFallbackKey;
+    private resolveConfigured;
+    /** 用户写的引用 → 一次选择；条目不存在时直接给出拒绝结果（`ok` 字段在就是结果） */
+    private resolveRef;
+    /** `models.utility` 写的是 `@<id>` 时的那一支，形状同 {@link getUtilityInfo} */
+    private entryUtilityInfo;
     /**
      * 取模型实例。第一次用到某个 provider 时才 import 它的 SDK。
      *
@@ -10609,22 +10691,22 @@ declare class ProviderRouter {
      * 装包这件事重试一万次也不会自己好。
      */
     private getModel;
-    private rotateCredential;
-    private fallbackProvider;
     /**
-     * 这次请求从哪个 provider / 模型起步（方案 19）。
+     * 这次请求从哪一条起步（方案 19 → 2.0.0）：点名了条目（压缩器 / 内部杂活）就是它，没点名就是当前选择。
      *
-     * 覆盖只改**起点**，降级链照常生效：覆盖到 ollama 挂了，仍然会按
-     * `fallback.providers` 往下走。
+     * 点名的那一条用不了（不在表里 / 没 key）**抛，不静默退回当前那条** —— 判据在
+     * `GenerateInput.entry` 上。没点名时过一道节流：当前那条被放弃过就从降级那一条起步
+     * （{@link avoidAbandoned}）。
      */
     private startPoint;
     /**
-     * 起点绕开已经放弃的模型（方案 26 验收 #8）。
+     * 起点绕开已经放弃的模型（方案 26 验收 #8）：当前那条被放弃过、而降级那一条（`fallback.model`）
+     * 还没有，就从降级那一条起步。
      *
      * 这就是节流真正省下来的东西：不这么做的话，每一轮都要先拿一个已知挂着的
      * 模型烧一次请求、等一次超时，然后才降级 —— 而结局每轮都一样。
      *
-     * 整条链都被放弃过时**照旧打主模型**：那时候降到哪儿都一样坏，
+     * 降级那一条也被放弃过（或者没配）时**照旧打当前那条**：那时候降到哪儿都一样坏，
      * 不如让用户看到他选的那个模型报的真实错误。
      */
     private avoidAbandoned;
@@ -10638,24 +10720,45 @@ declare class ProviderRouter {
      */
     private recover;
     /**
-     * 沿降级链走一步：先同 provider 换模型，再换 provider（方案 26 §2.4 / 验收 #11）。
+     * 沿降级链走一步：降到 `fallback.model` 那一条（方案 26 §2.4 → 2.0.0）。
      *
-     * 同家优先是因为凭据、限速桶、计价口径都不变；换家意味着这三样同时变，
-     * 而用户多半只是想让这一轮跑完。
+     * 2.0.0 之前降级链有三级（`@<id>` 条目 → 同家内置降级表 → `fallback.providers` 换一家用那家的
+     * 默认模型），后两级都是老写法的产物，随它删了：内置表里是各家**官方端点**上的模型名，拿去打
+     * 一个自建端点必然 404；换一家用「那家的默认模型」等于替用户选了一个他没确认过的模型。
      *
-     * `attempt` 归零而不是累加：新落点值得一份完整的重试预算。不会转圈是因为
-     * `tried` 在涨，候选集有限。
+     * `attempt` 归零：新落点值得一份完整的重试预算。不会转圈是因为 `tried` 在涨。
+     *
+     * 两个调用点：`recover()` 上那些**非重试类**的失败，以及 {@link afterRetries}
+     * —— 而 `afterRetries` 正是「重试类失败也终于降级」的那一处（2026-10-16）。
      */
     private escalate;
     /**
-     * `config.fallback.model` 只对**主 provider** 有效。
+     * 重试预算在一个落点上跑完之后（2026-10-16）：记一笔，沿降级链走一步；没下一条可走时回 `null`。
+     *
+     * ## 为什么预算耗尽也要走降级链
      *
-     * 模型名是 provider 私有的命名空间：`--fallback-model gpt-4.1-mini` 说的是
-     * 「我的 OpenAI 挂了就用它」，一旦降到 deepseek，那个名字就只是一次必然的
-     * 404 —— 和 `fallbackProvider` 里「跨家必须换模型名」是同一条规矩的另一面。
-     * 用户 `/model` 换到别家之后同理，所以判的是**当前落点**而不是配置里那家。
+     * `recover()` 对 `recovery: 'retry'` 只有「留在原地再来一次」一个动作，于是
+     * 「预算耗尽」这一步从来不在它里面发生，而是落在两个循环之外 —— 那儿原来只有
+     * 「记一笔 + 放弃」。后果是降级在**最常见的那一族失败上整个失效**：主条目的端点
+     * 挂了（恒 503 / 恒超时 / 一直限流），整轮把预算烧在同一个落点上，然后直接报
+     * 「重试 N 次后仍然失败」—— 配好的 `fallback.model` 一次都没被打过，而设置页上
+     * 那句「主模型连续出错时换到它」在这种现场里是假的。
+     *
+     * 判据是「**预算耗尽 = 这个落点在这一轮里没什么可试的了**」，和 404 / 401 / 402
+     * 那几档是同一件事，所以出路也走同一条。不会转圈：`escalate()` 把走过的落点记进
+     * `tried`，候选只有 `fallback.model` 那一条，降级那一条再耗尽时这里回 `null`，
+     * 由调用方按各自的方式说「重试 N 次后仍然失败」。
+     *
+     * ⚠️ **记账不挪进 `escalate()`**：跨轮节流的计数单位是「一轮一次」，而两个循环里
+     * 它是那一轮唯一的失败出口。主条目耗尽了记主条目（否则一个稳定 429 的模型永远
+     * 攒不够三次），落到降级条目上再耗尽是另一笔 —— 两次都该记。
+     */
+    private afterRetries;
+    /**
+     * `fallback.model`（`@<id>`）指向的那一条，**不限同一家**：条目自带端点和 key，
+     * 「主模型挂了换我自建的那个」正是它的用途。就是当前那条、已经试过、或者没 key 时回 `undefined`
      */
-    private configuredFallbackModel;
+    private fallbackEntry;
     /**
      * 记一次模型失败，跨过阈值时留一条通知（方案 26 验收 #8）。
      *
@@ -10680,6 +10783,14 @@ declare class ProviderRouter {
     generate(input: GenerateInput): Promise<GenerateOutput>;
     /** 流式生成，带自动重试和降级 */
     stream(input: GenerateInput): AsyncGenerator<ProviderStreamChunk>;
+    /**
+     * 这一次的输出上限：条目声明了 `maxOutputTokens` 时取它和调用方给的那个**较小的**。
+     *
+     * 较小而不是「条目优先」：调用方给得小是有原因的（起标题只要几十个 token），条目那一格
+     * 说的是「这个模型最多能出多少」—— 两个都是上限，同时成立的就是较小的那个。
+     * 调用方没给时用条目的，那是用户在「输出」那一格明说要的。
+     */
+    private maxTokensFor;
     private backoff;
     getModelId(): string;
     getProviderType(): ProviderType;
@@ -10725,1332 +10836,1536 @@ declare class ProviderRouter {
 }
 
 /**
- * 「这个模型认不认图」—— **现问模型本人，不查表**（2026-09-11）。
- *
- * ## 为什么需要它：查表这条路有一个它永远答不出的问题
- *
- * `model-metadata.ts` 的三层（静态表 → OpenRouter 缓存 → 默认值）全都是
- * **别人对这个模型的描述**。上游改一次名字，两层同时失效，第三层的默认值是
- * `supportsImages: false` —— 于是一个认图的模型在我们眼里瞎掉，而且是**静默**
- * 瞎掉：用户得到的是「当前模型不支持图片输入」，一句可核对的理由都没有。
- *
- * 2026-09-11 实测的现场：DeepSeek 把 `deepseek-v4-flash-vision-exp` 改名成
- * `deepseek-flash`，静态表 miss、OpenRouter 那份 872 条里**根本没有这个裸名**，
- * 于是 `epoch -i 图.png` 被我们自己拦死。而同一张图直接发给它，它答得一字不差。
- *
- * ## 判据是 **input token 涨没涨**，而这一格换过两次，两次都是被实测逼的
- *
- * ### 第一版：靠 warning —— 当天就否掉了
- *
- * 最省事的做法是不确定就照发，SDK 报了 warning（`droppedUserContentParts`）
- * 就说明它不认。**走不通**，同一天的 A/B：
- *
- * | 模型              | 出站 body | warnings | 回答        | input token |
- * | ----------------- | --------- | -------- | ----------- | ----------- |
- * | `deepseek-flash`  | 带图      | `[]`     | `"Red"`     | 225         |
- * | `deepseek-v4-pro` | 带图      | `[]`     | `"Unknown"` | 99          |
+ * 「我的模型」条目在 router 里怎么落地（2026-10-15）。
  *
- * 第二行就是那个坑：**它把图无声吞了，一条 warning 都不报**，SDK 和 provider
- * 两侧都认为这次请求很正常。同理「不报错就算认图」「答了话就算认图」也都被这一行
- * 否掉 —— 它不报错，它也答了话。
+ * ## 路由键
  *
- * ### 第二版：靠**回答**（发一张纯红图问颜色，答得出红就算）—— 2026-09-12 否掉
+ * router 的凭据表和工厂缓存按**路由键**存：条目的是 `@<id>`，同一家两套端点（官方 DeepSeek +
+ * 自建中转的 DeepSeek）就是两个键。2.0.0 之前还有一档「老写法的路由键就是 provider 名」，
+ * 随老写法删了 —— 今天只剩钉住网关时那一条 `openai-compatible`（见下）。
+ * 其余按 provider 记的东西（遥测、tool 结果收不收图）照旧按 provider，
+ * 因为它们说的是「这家的协议」，不是「这一套端点」。
  *
- * 它把断言落在了模型的**识图准确率**上，而那个东西既不稳定、也不是我们的责任。
- * 同一张 132 字节的红方块、同一个型号（`deepseek-v4-flash-vision-exp`）、
- * **逐字节相同的出站 body**（钩 `fetch` 抓的，四次都是 `bodyLen=50948`），
- * 连着跑四次的回答是：
+ * ## ⚠️ 宿主钉住端点时，**只有宿主条目**走网关（2026-10-15 收窄）
  *
- * | run | 回答      |
- * | --- | --------- |
- * | 1   | `Red`     |
- * | 2   | `White`   |
- * | 3   | `Magenta` |
- * | 4   | `Blue`    |
+ * 原来的契约是「`config.gateway` 时所有条目一律打网关」，用户拍了收窄：
+ * 钉住钉的是**宿主自己那一组**（`ModelEntry.host`，`hostPreset.models` 物化来的），
+ * 用户添加的条目照常用自己的 provider / 地址 / key 直连自己的端点 —— 不然用户在星云里
+ * 加不了别的提供商。宿主条目的地址由**宿主自己写在条目里**（`hostPreset.models` 每条自带
+ * baseUrl，原样物化、不强制），所以**不需要任何路由特判**：条目永远按自己的字段走。
  *
- * 也就是说这一版探针在这个型号上有约 3/4 的概率把一个**确实收到了图**的模型
- * 判成瞎子，然后把 `false` 写进缓存。
+ * 安全论证（为什么可以收窄）：
+ * - 宿主条目的凭据是宿主的 fetch 桥**按网关 origin**注入的，用户条目的请求不会拿到它；
+ * - 用户条目只用自己存的那把 key（`EPOCH_MODEL_KEY_<id>`，只发往用户自己填的地址）；
+ * - 宿主条目没有特权：它只是被界面锁住的一条普通条目，用户手改 models.json 也
+ *   得不到任何它不该有的凭据。
+ * 守门用例在 `__tests__/entry-route-pinned.test.ts`（宿主条目出站打网关、用户条目打自己的地址）。
+ */
+
+/**
+ * 一个模型引用**此刻**能做什么：`@<id>` 先解析成条目，再在元数据表上叠条目的覆盖。
  *
- * ### 这一版：靠 input token 的**增量**
+ * 给 router 之外的那几处用 —— 启动时的上下文窗口快照（runtime 的 `resolveModelCapability`）、
+ * TUI 的状态栏和贴图闸。它们原来直接 `getCapability(config.model)`，而 `config.model` 是
+ * `@xxx` 时那一句查到的是兜底的默认值：窗口 200k、不认图 —— 一个声明过 32k 的条目会
+ * 一路聊到撞窗口。
  *
- * 同一批运行里，回答四选一，而 `inputTokens` 纹丝不动 ——
- * 带图 21088、不带图 20904（各跑两次，两两分毫不差）。差的那 184 个 token
- * 就是那张图：**模型为它计了费，也就意味着它真的收下并处理了。**
+ * @param ref 缺省是 `config.model`
+ * @returns 引用缺席 / 不是 `@<id>` / 那一条不在表里时 `undefined`（还没有模型）
+ */
+declare function capabilityOfRef(config: Pick<EpochConfig, 'model' | 'homeDir' | 'modelEntries'>, ref?: string | undefined): ModelCapability | undefined;
+
+/**
+ * 「我的模型」弹窗里那两个问句：**这个端点有哪些模型**、**这套配置连不连得上**（2026-10-15）。
  *
- * 于是探针发两发（同一句话，一发带图一发不带），比 `inputTokens`：
+ * ## 为什么不复用 `discoverModels()`
  *
- * - 涨了 → 图被接收（上表第一行，225 vs 99 也正是这个形状）；
- * - 没涨 → 被无声吞了（上表第二行）；
- * - 拿不到 usage → `inconclusive`，**不写缓存**。
+ * 它是给「已经配好的那一家」用的：探到的结果按 **provider** 落盘缓存 24 小时
+ * （`cache/models_<provider>.json`）。弹窗里探的是**还没保存的草稿** —— 用户可能正在
+ * 试一个填错的中转站地址。走它的话，一次草稿探测就会把「DeepSeek 官方有哪些模型」那份
+ * 缓存换成中转站上的那份，而那份缓存同时喂着输入框旁边的模型菜单。所以这里**一个字节
+ * 都不落盘**，每次现问。
  *
- * ⚠️ **这一版探不出「收了图但看不懂」**，这是刻意放弃的：那是模型质量，
- * 不在我们的责任边界内。上面那四次 `White` / `Magenta` / `Blue` 在新判据下
- * 全部算「认图」—— 而它们确实都认图，这正是想要的。
+ * ## 测试连接分两步，第二步才花钱
  *
- * ⚠️ 探针的两发**不共享长前缀、也够不着任何 prompt 缓存**（裸 `generateText`，
- * 没有 system prompt，整条消息一百多 token）。这一条是承重的：provider 一旦
- * 把 `inputTokens` 按「未命中缓存的部分」报，两发的数就不可比了。
+ * 1. `GET <地址>/models`。不花钱，而且 401 / 403 在这一步就能说清楚是 key 的事；
+ * 2. 列表接口不存在（404、或者「自定义协议」那种只有一个地址的端点）时，才真发一次
+ *    `maxOutputTokens: 1` 的请求 —— 那是唯一能回答「这个模型名在这个端点上调不调得通」
+ *    的办法。代价是一次请求的钱，用户按的就是「测试」这个按钮。
  *
- * ## ⚠️ 第三档 `inconclusive` 的含义跟着换了
+ * ## 报错原文里不许带 key
  *
- * 第二版里它指「正文是空的」（推理型号把输出预算花在思考上）。这一版**不看正文**，
- * 所以那一档现在指「**拿不到 usage**」（provider 不报、或基线那一发自己失败了）。
- * 处置没变：这一次按「不认图」走，但**一个字都不写缓存** —— 写进去会把一个
- * 认图的模型钉死（`true` 的缓存是 30 天）。
+ * `detail` 会过网线进浏览器。有的中转站会把收到的 key 回显在报错里，所以出门前把
+ * key 原文替换成脱敏串（{@link redact}）。
  */
 
+/** 测试连接的结论。码是真源，措辞在浏览器的 catalog 里（同 `SelectionRejection`） */
+type EntryProbeCode = 
+/** 连上了 */
+'ok'
+/** 401 / 403：key 不对或没权限 */
+ | 'auth'
+/** 模型名在这个端点上不存在（404 / model not found） */
+ | 'model-not-found'
+/** 连不上：DNS / 拒绝连接 / 超时 / 证书 */
+ | 'network'
+/** 别的错误。`detail` 里是端点的原话 */
+ | 'error'
+/**
+ * 还没选模型、而这个端点又列不出模型清单（没有列表接口 / 列表接口不通但不是 key 的事）——
+ * 只剩「拿一个具体模型真发一次」这条路能验证，得先选模型。**一发都没有失败**，不是报错
+ */
+ | 'need-model'
+/**
+ * 填的东西本地就没过校验（地址格式不对之类），**一发都没出去**。`detail` 是校验的原话。
+ * ⚠️ 2026-10-15 之前这一档报的是 `error`，界面因此说成「接口回了一个错误」—— 那是假话
+ */
+ | 'invalid';
+interface EntryProbeResult {
+    code: EntryProbeCode;
+    /** 顺带探到的模型列表（第一步成功时才有，可能为空） */
+    models: string[];
+    /** 端点回的 HTTP 状态码（有的话） */
+    httpStatus?: number;
+    /** 从发出到拿到结论用了多久 */
+    latencyMs: number;
+    /** 端点的原话（已脱敏）。只在不是 `ok` 时给 */
+    detail?: string;
+}
 /**
- * ⚠️ 2026-09-12 从 1 提到 2：判据从「答不答得出红」换成「input token 涨没涨」
- * （判据全文在文件头）。**旧结论是用另一把尺子量的**，其中的 `false` 有相当一部分
- * 是第二版那个 3/4 误判率产出的 —— 继续信它等于把一次已经作废的实验的结果
- * 当成这次的。整份丢掉，重新探。
+ * 这个（可能还没保存的）条目的端点上有哪些模型。**不落缓存**，判据见文件头。
+ * 探不到就是空数组 —— 模型名那一格本来就允许手敲。
  */
-declare const PROBE_VERSION = 2;
+declare function listEntryModels(entry: ModelEntry, apiKey: string | undefined): Promise<string[]>;
+/** 测试连接。**从不抛**：任何失败都落到一个码上 */
+declare function testModelEntry(entry: ModelEntry, apiKey: string | undefined): Promise<EntryProbeResult>;
 
 /**
- * Provider 错误的分类：一个异常对象 → 「该怎么恢复」。
+ * 模型发现 — Live API → disk cache → static catalog 三层回退 [Hermes models.py]。
  *
- * 从 `router.ts` 拆出来（方案 26 PR-2）。理由不是行数，是**它是纯函数**：
- * 输入一个错误、输出一档恢复动作，不碰状态、不碰网络。留在 router 里的时候，
- * 想验「'maximum context length is 128500 tokens' 会不会被当成 500 服务器错误」
- * 得先造一个有凭据的 router 出来 —— 而那跟这个判断毫无关系。
+ * 改造前只有 6 个 provider 有 base URL，且 URL 拼接只对「用户传进来的」那份做
+ * `/v1` 归一化，内置那份不做——于是 anthropic / google / xai / perplexity 永远
+ * 走不到 live 列表，而用户填 `https://x.com/v1` 会被拼成 `https://x.com/models`。
+ * 现在 base URL 全部与 `@ai-sdk/*` 各 provider 的默认 chat baseURL 对齐（同一
+ * 个域名下发现和调用才可能一致），`/v1` 有无由候选重试决定而不是靠猜。
  */
-/** 恢复动作。降级链的每一档由它决定走到哪 */
-type RecoveryAction = 'retry' | 'rotate_credential' | 'switch_model' | 'switch_provider' | 'abort';
-declare class ProviderError extends Error {
-    readonly code: number;
-    readonly recoverable: boolean;
-    readonly recovery: RecoveryAction;
-    constructor(message: string, code: number, recoverable: boolean, recovery?: RecoveryAction);
+interface DiscoverResult {
+    models: string[];
+    source: 'live' | 'cache' | 'static';
 }
 /**
- * 「没有可用凭证」的错误码。
- *
- * 单独提成常量是因为**装配层要按它分档**：没配 key 是「还没配置」（诊断记
- * `skipped`），不是「模块坏了」（`failed`）—— 后者会让 `epoch doctor` 退非 0，
- * 于是一台刚装完、还没配 key 的机器（以及 CI）会被判成坏的。
- * 见 runtime/src/services.ts 的 Provider 那一段。
+ * 模型列表接口的认证方式。三种都不是我们编的：
+ *   - `bearer`：OpenAI 及一众兼容实现
+ *   - `x-api-key`：Anthropic 原生 API，另外还要 `anthropic-version`
+ *     （见 hermes-agent/plugins/model-providers/anthropic/__init__.py 的 fetch_models）
+ *   - `query`：Google Generative Language API 把 key 放 query string
+ *     （见 hermes-agent/hermes_cli/web_server.py 的 GEMINI_API_KEY 项）
  */
-declare const PROVIDER_NO_CREDENTIAL = 1001;
+type AuthStyle = 'bearer' | 'x-api-key' | 'query';
+interface ProviderDiscovery {
+    /** 模型列表接口的 base URL */
+    baseUrl: string;
+    auth: AuthStyle;
+}
 /**
- * 错误分类。
- *
- * 顺序很关键，而且**语义模式必须排在裸数字之前**：
- * 原来 `/500|502|503/` 排在 context-length 检查前面，任何含 "500" 的消息
- * （"maximum context length is 128500 tokens"、"reduce to 500 tokens"）
- * 都会被当成服务器错误去重试——而 context 超限重试一万次也不会好。
- *
- * 裸状态码只在错误对象本身带 status 时才可靠，所以优先读 status，
- * 再退化到从消息里找**带边界**的状态码。
+ * 这一家的模型列表接口在哪儿、怎么鉴权（给「我的模型」的探测用，2026-10-15）。
+ * 不在表里的（`openai-compatible` / `ollama` / `cohere` …）回 `undefined`。
  */
-declare function classifyProviderError(err: unknown): {
-    code: number;
-    recovery: RecoveryAction;
-};
-
+declare function discoverySpec(provider: string): ProviderDiscovery | undefined;
 /**
- * 换模型的前置判定（方案 26）。
- *
- * 单独一个文件而不是塞进 `router.ts`：
+ * `<base>/models` 的候选列表：原样一个，再一个把结尾 `/v1` 反转过来的。
  *
- * 1. `router.ts` 已经 700 多行（AGENTS.md 铁律 3 的上限是 500），不该再长
- * 2. 这三道检查是**纯函数** —— 给它「有没有凭据」和「模型什么能力」，
- *    它就能算出换不换得成。抽出来之后单测不用造一个 `ProviderRouter`
- *    （那要真凭据、要碰 `readProviderKeyEnv()`），直接喂假事实就行
+ * provider 到底是 `https://api.deepseek.com/models` 还是
+ * `https://api.deepseek.com/v1/models`、用户填的 base 带不带 `/v1`，猜不准也
+ * 没必要猜——第一个不通就试第二个。这个「toggle 而不是 strip」的做法抄的是
+ * hermes-agent/hermes_cli/models.py 的 `alternate_base`。
+ */
+declare function modelListCandidates(baseUrl: string): string[];
+/**
+ * 从响应里取模型 id。两种形状都要认：
+ *   - OpenAI / Anthropic：`{ data: [{ id }] }`
+ *   - Google 原生 ListModels：`{ models: [{ name: "models/gemini-2.5-pro" }] }`
+ *     —— `models/` 前缀要摘掉，配置和用户输入里写的都是裸名
+ *     （hermes models.py:5148 踩过这个坑，注释里挂着 gemini-cli #12532）
+ */
+declare function parseModelList(payload: unknown): string[];
+/**
+ * 发现 provider 可用模型 [Hermes discoverModels]。
  *
- * 判定留在 core 而不是 UI 层：换一个宿主（TUI / web / headless）也得是同一套
- * 判据，放 UI 里就会有第二份、然后两份开始不一致 —— 这个仓库在
- * 「provider → 环境变量名」那张表上已经吃过一次这个亏。
+ * 1. 调 API 拉取 live 模型列表 → 缓存
+ * 2. 失败 → 读磁盘缓存
+ * 3. 空 → 回退到静态目录
  */
+declare function discoverModels(homeDir: string, provider: string, apiKey?: string, baseUrl?: string): Promise<DiscoverResult>;
+/** 清除 provider 的模型缓存 */
+declare function clearModelCache(homeDir: string, provider: string): void;
 
-/** 判定要用到的外部事实，由 router 注入 */
-interface SelectionDeps {
-    /** 这个 provider 有没有可用凭据 */
-    hasCredential: (provider: ProviderType) => boolean;
-    /** 这个模型的能力（窗口 / 视觉 / 工具） */
-    capability: (model: string) => ModelCapability;
-}
 /**
- * 换模型的三道前置检查。
- *
- * 两条拒绝都是「换过去下一轮必然失败」，**在这里拦住比让 provider 报 400 好**：
- * 400 是已经计费的，而且错误消息里不会写「因为你刚才换了模型」。
+ * 设置文件的形状与读取 —— 项目级 / 项目本地 / `--settings` / 企业托管**共用这一份**。
  *
- * 换模型**不清空上下文**——那正是它的意义所在（对着同一段对话换个更强或更便宜
- * 的脑子）。代价就是新模型必须接得住已经积累的东西，所以才有这三道检查。
+ * 从 [sources.ts](./sources.ts) 拆出来的原因很具体：企业托管（第 ∞ 层，§2.6）
+ * 的文件形状是「同样的键 + 三个元开关」，它要复用这里的 schema 和读取逻辑，
+ * 而 `sources.ts` 又要消费托管层的解析结果 —— 两个文件互相 import 就成了环。
+ * 把**共用的下层**摘出来是拆环最省事的一刀。
  */
-declare function evaluateSelection(want: ModelSelection, deps: SelectionDeps, ctx?: SelectionContext): SetSelectionResult;
 
 /**
- * 模型级降级：降到哪儿、以及什么时候不该再降回来（方案 26 PR-2，验收 #8/#10/#11）。
- *
- * 拆出来而不是继续堆在 `router.ts` 里，有两个理由：
+ * 设置文件（`.epoch/settings.json` / `--settings`）的形状。
  *
- *   1. `router.ts` 已经 800 行，铁律 3 的线早就压在上面了
- *   2. 这两件事**都是纯状态**，不碰 SDK、不碰网络。单独放能被用例直接盯，
- *      不用为了验「连续失败三次会怎样」去 mock 一整个 AI SDK
+ * 字段从 `EpochConfigSchema` **摘**出来而不是另写一份：值域约束（`maxTurns`
+ * 是正整数、`permissions` 三张列表都是非空字符串）只能有一处定义，
+ * 抄第二份迟早对不上。
  *
- * 降级分两级，顺序固定（方案 26 §2.4）：
+ * ## `.unwrap()` 不是花活，`.partial()` 在这儿是错的
  *
- *   主模型 → `fallback.model`（**同一个 provider**）→ 内置默认模型（同上）
- *          → `fallback.providers`（换一家，那部分在 router）→ 失败
+ * `EpochConfigSchema` 里 `model` / `maxTurns` 都带 `.default()`，而 zod v4 的
+ * `.partial()` 只是往外面套一层 `ZodOptional`，**里面的默认值照样兑现**：
+ * `pick({model:true}).partial().parse({})` 得到的是 `{model:'gpt-4o-mini'}`，
+ * 不是 `{}`。合并语义是「给了才覆盖」，于是一份只写了 `permissions` 的
+ * `settings.json` 会顺手把用户配的 model 打回内置默认值 —— 而且诊断里
+ * 一个字都不会说。所以必须先 `.unwrap()` 摘掉 default 再 `.optional()`。
  *
- * 同 provider 优先，是因为凭据、限速桶、计价口径全都不变 —— 换家意味着
- * 这三样同时变，而用户多半只是想让这一轮跑完。
+ * 用例里钉了「`parse({})` 必须深等于 `{}`」，它红了就说明这层保护没了。
  */
-
-/** 某家 provider 的默认模型 */
-declare function defaultModelOf(type: ProviderType): string;
+declare const SettingsFileSchema: z.ZodObject<{
+    permissions: z.ZodOptional<z.ZodObject<{
+        allow: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        ask: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        deny: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    model: z.ZodOptional<z.ZodString>;
+    maxTurns: z.ZodOptional<z.ZodInt>;
+}, z.core.$strip>;
+type SettingsFile = z.infer<typeof SettingsFileSchema>;
 /**
- * 同一个 provider 内的下一个候选模型。
+ * `--settings` 指的文件用不了（方案 29 §2.4 / 验收 #16）。
  *
- * @param provider   当前 provider，链条不跨家
- * @param current    此刻用的模型，不会返回它自己
- * @param tried      本次请求里已经试过的 `provider/model`。**它是终止条件** ——
- *                   没有它，「降到默认模型 → 默认模型也 404 → 又降到默认模型」
- *                   会原地转圈，直到重试次数耗尽才报一个驴唇不对马嘴的错
- * @param configured `config.fallback.model`，用户显式指定的同家后备
- * @returns 没有下一个了就是 `undefined`，调用方据此升级到换 provider
- */
-declare function nextFallbackModel(provider: ProviderType, current: string, tried: ReadonlySet<string>, configured?: string): string | undefined;
-/**
- * 连续失败到几次就放弃这个模型（方案 26 验收 #8）。
+ * 单独一个类型的理由同 `ManagedPolicyError`：这**不是故障也不是 bug**，是用户
+ * 显式给的那份文件坏了，CLI 要按「预期内失败」打一行（见 cli 的 `errors.ts`）。
  *
- * 3 而不是 1：偶发 429 / 503 是常态，一次就放弃等于「抖一下就永久换模型」，
- * 用户明明选了强模型却在跑弱的。也不是 10：每一次重试都是真金白银的一次请求，
- * 而一个真的挂了的模型不会在第 7 次突然好。
+ * 为什么只有这一层抛、其余层照旧「整份忽略 + 一条 issue」：见
+ * [sources.ts](./sources.ts) 里 `finishLayer` 那处注释。
  */
-declare const MODEL_GIVE_UP_THRESHOLD = 3;
+declare class SettingsFileError extends Error {
+    /** 下一步做什么。和 message 分开，CLI 排在第二行 */
+    readonly hint: string;
+    constructor(message: string, hint: string);
+}
 /**
- * 模型失败的节流状态（方案 26 验收 #8）。
+ * JSON 解析失败的一句话，**保证带行号**。
  *
- * 解决的是这个形状：主模型挂了，每一轮都先拿它试一次、失败、再降级 ——
- * 于是**每一轮都白烧一次失败请求**，还平白多等一次超时。连续失败到阈值之后
- * 就不再自动打它，直接从降级链起步。
- *
- * ## 计数单位是「请求」不是「重试」
- *
- * 一次 `generate()` 内部为同一个模型重试三次，算 **1** 次失败而不是 3 次。
- * 重试是同一次意图的一部分；把它算成三次，等于第一轮就把模型判死刑。
- *
- * ## 只在本会话内有效，且用户能一句话推翻
+ * Node 22 的 `JSON.parse` 报错里其实已经有 `(line 3 column 7)` 了，但不能靠它：
+ * 一是旧版本只给 `position 18`，二是 `Unexpected end of JSON input` 这类压根没有
+ * 位置。所以按 position 自己数一遍换行 —— 「第几行」是用户唯一能拿去改文件的
+ * 信息，而 position 是个要他打开编辑器去数字节的数。
  *
- * 不落盘：模型挂了通常是分钟级的事，把「这个模型不好使」记到下次启动
- * 会变成一个没人知道怎么解除的诅咒。`/model` 手动切回来会调 {@link clear}，
- * 那是显式的「我要再试一次」——用户的话永远压过引擎的推断。
+ * 数不出来时**原样返回 Node 那句**，不编一个假的行号。
  */
-declare class ModelFailureTracker {
-    private readonly counts;
-    private readonly abandoned;
-    /**
-     * 记一次失败。
-     *
-     * @returns 这一下是不是**刚好**跨过阈值。只在跨过的那一次回 `true`，
-     *   调用方据此发一条通知 —— 之后每次失败都发就成了刷屏
-     */
-    recordFailure(provider: ProviderType, model: string): boolean;
-    /**
-     * 记一次成功 —— 连续计数**清零**，不是减一。
-     *
-     * 「连续」是这里的关键词：跑通了十轮之后再失败一次，和连着失败三次，
-     * 是完全不同的两件事，只有后者说明模型真的不好使了。
-     */
-    recordSuccess(provider: ProviderType, model: string): void;
-    /** 这个模型已经被放弃了吗 */
-    isAbandoned(provider: ProviderType, model: string): boolean;
-    /** 抹掉一个模型的全部记录。用户手动切回它时调 —— 显式意图压过引擎的推断 */
-    clear(provider: ProviderType, model: string): void;
-}
+declare function describeJsonError(err: unknown, text: string): string;
 
 /**
- * Token 估算 —— 真分词，不再是 `chars / 4`（方案 42 §七「运行前 token 估算」）。
- *
- * ## 先量的那一遍
- *
- * 改造前全仓统一走 `Math.ceil(text.length / 4)`。拿**本仓库的真实文件**过一遍
- * （2026-08-15，对照 `o200k_base` 的真实分词结果）：
- *
- * | 样本                                | chars/4 | 真实 | 真 / 估   |
- * | ----------------------------------- | ------- | ---- | --------- |
- * | AGENTS.md 里纯中文的行              |     229 |  616 | **2.69×** |
- * | AGENTS.md 全文（中英混排散文）      |    3008 | 6035 | **2.01×** |
- * | core/README.md（中英混排）          |    2392 | 3333 | 1.39×     |
- * | 三个 `.ts`（代码 + 中文 JSDoc）     |    — | — | 1.29–1.45× |
- * | compressor.ts 里纯 ASCII 的行       |    2741 | 2701 | 0.99×     |
- * | 纯英文散文                          |     107 |   68 | 0.64×     |
- *
- * 读法是：**英文和纯代码场景它一直是准的，中文场景系统性低估 2–2.7 倍**
- * （换成 `cl100k_base` 那种老编码更差，纯中文到 3.66×）。而 `/context` 那张
- * 占用表、路由的「这一轮塞不塞得下」、压缩器的尾部预算全都吃这个数 ——
- * 所以它不是显示精度问题，是三处功能的地基。
- *
- * ## 为什么挑 gpt-tokenizer
- *
- * 三个候选实测（Windows / Node 24，各起**新进程**取 5 次中位数，
- * 量的是「从 import 到算出第一个数」）。判据按这个顺序：
- *
- * 1. **不能拖慢冷启动** —— TUI 和 CLI 每次都要起。
- *    `gpt-tokenizer/encoding/o200k_base` **89 ms**，
- *    `js-tiktoken/lite` + `ranks/o200k_base` **289 ms**，3.2 倍差距。
- *    而且 gpt-tokenizer 按编码分入口，另外五套词表一个字节都不会被解析。
- *    再加上下面的懒加载，进程启动本身**一毫秒都不多花**
- * 2. **不能引入 wasm / native 附件** —— `@dqbd/tiktoken` 是 wasm，直接出局：
- *    `pnpm pack` / `verify:pack` 那条路会变复杂，Windows 上装 native 附件
- *    也是本仓库的已知坑。gpt-tokenizer 是纯 JS、**零运行时依赖**
- * 3. **体积** —— 这一条 gpt-tokenizer 是**输**的：装完 54 MB，js-tiktoken 22 MB。
- *    但真正被 require 进内存的只有 `esm/encoding/o200k_base.js` 那 2.3 MB，
- *    而判据顺序里冷启动排在体积前面，所以认这个亏
- * 4. **许可证** —— MIT。**只是依赖它，没有抄任何一行代码**，所以本文件
- *    不加 `SPDX-License-Identifier` 头（AGENTS.md 铁律 12：那个头在本仓库的
- *    含义是「抄自 gemini-cli」，加了就必须同步登记进 NOTICE）
- *
- * ## 一套编码走天下，这是**有意的近似**
- *
- * 模型不同分词器就不同（GPT 的 o200k / cl100k、Claude 自己的 BPE、DeepSeek
- * 自己的），但今天**所有模型都走 `o200k_base` 这一套**。挑它是因为它是当代
- * 编码里 CJK 合并最充分的，拿来当 Claude / DeepSeek 的代理比 `cl100k_base` 近。
- * 真按模型分套要各家的词表文件，那是另一轮的事 —— 这一轮只把口径统一到一处。
- *
- * 接口上留了 `model` 形参，今天走到 {@link encodingFor} 就被忽略掉；
- * 留着是为了将来加分支时**调用方一行都不用改**。
- *
- * ⚠️ **它仍然是估算。** 真值以 provider 回的 usage 为准（那本来就是准的，
- * 见 `cost/pricing.ts` 的 `promptTokens`）。别拿这个数去断言「等于 usage」。
- *
- * ## 2026-08-15：换了真分词器**不等于**可以摘掉界面上那枚「估算」徽标
- *
- * 这一条写在这儿是因为它已经被读反过一次。`design/web-ui/index.html:744` 那条
- * HTML 注释末尾写着「要拿掉这个徽标得先换真 tokenizer」—— 它是**必要条件**，
- * 不是充分条件，而同一份稿子的 `thread.css` 里 `.est` 那条写死了充分条件：
- * 「token 有三个时刻，只有**运行前那一个**是猜的，所以这个徽标只准出现在
- * `.mhead__sub` 里」。
- *
- * 换句话说：这个文件治好的是**偏差有多大**（中文场景 2–2.7 倍的系统性低估），
- * 治不好的是**它是不是猜的**。后者由两件事钉死，两件都还在：
+ * 企业托管设置 —— 第 ∞ 层（方案 22 §2.6）。
  *
- *   1. 上面「一套编码走天下」那一段 —— 编码是 o200k_base，模型可能是
- *      Claude / DeepSeek，各家 BPE 不同；
- *   2. 更硬的一条：运行前估算算的是**发之前**的载荷，而这一轮跑起来之后还会
- *      插进压缩、后台任务通知、工具结果。
+ * 由 IT 管理员分发到一个**普通用户写不了**的机器级路径
+ * （见 infra 的 `managedSettingsPath()`），压过其余全部五层，且额外带三个
+ * **元开关** —— 它们管的不是「配了什么」，而是「别的层还算不算数」：
  *
- * 运行前那个数的消费方是 `agent/run-estimate.ts`（决定 8 的第一个时刻），
- * 判据全文在那个文件头。
+ * | 开关                             | 作用                                       |
+ * | -------------------------------- | ------------------------------------------ |
+ * | `allowManagedPermissionRulesOnly` | 其余各层的 allow / ask / deny 全部忽略     |
+ * | `allowManagedHooksOnly`          | 用户级 hook 一律不加载                     |
+ * | `disableBypassPermissionsMode`   | `permission: bypass` 拒绝启动              |
  *
- * ## ✅ 「我够不着，你来收」—— **收了**（2026-08-15，`wt/1` 留，合并时结）
+ * ## 这一层**不过信任闸门**，而且不该过
  *
- * 留的是这么一笔：两份文档里还写着这个函数是 `length/4`、而且指着一个它
- * **从来不在**的位置（`model-metadata.ts:371`）。两处都收了，
- * 账在 [30 §13.1](../../../../docs/verify/VERIFY_RECORD-30-web-multi-session.md)：
+ * 闸门问的是「这个仓库的作者可不可信」。托管设置不来自仓库，来自这台机器的
+ * 管理员 —— 拿仓库信任去闸它没有意义，而且方向是反的：托管策略的典型内容是
+ * deny，越是不信任的目录越需要它生效。
  *
- * - `design/web-ui/README.md`「8.2 决定 8」那条 ⚠️ 划掉重写，稿子
- *   `index.html` 那枚「估算」徽标上面那段注释同改（它是同一句话的第二处）。
- * - `.agents/plans/README.md`「42 划出来的底座缺口」里那一条划掉。
+ * ## 三个开关都是「只减不增」，所以缺省一律 false
  *
- * ⚠️ **「要拿掉徽标得先换真 tokenizer」按交代的一个字没动** —— 它是
- * **必要条件**，而充分条件（同一份稿子 `thread.css` 里 `.est` 那条：
- * 「三个时刻里只有运行前是猜的」）今天仍然成立。两处改写都把这句话的
- * 必要 / 充分之分写进去了，因为它已经被读反过一次。
+ * 读不到文件、文件写坏了、字段没写 —— 一律按「没有托管策略」处理。
+ * 反过来（读不到就当全开）会让一次磁盘故障把所有人的 epoch 锁死，
+ * 而托管策略保护的东西并不值这个代价：它挡的是用户给自己提权，
+ * 不是挡攻击者（能改 `C:\ProgramData` 的人早就能改 epoch 本身了）。
  */
+
 /**
- * 估算一段文本的 token 数。**全仓唯一的口径**，别再各写各的。
+ * 托管文件的形状 = 普通设置文件 + 三个元开关。
  *
- * @param model 留给「将来按模型选分词器」的形参，**今天被有意忽略**，
- *   见文件头「一套编码走天下」
+ * 用 `.extend()` 而不是另写一份：托管层能配的普通键必须和其它层完全一致，
+ * 否则「管理员配了 model 但只有托管层不生效」这种事没人查得出来。
  */
-declare function estimateTokens(text: string, model?: string): number;
-
+declare const ManagedSettingsSchema: z.ZodObject<{
+    permissions: z.ZodOptional<z.ZodObject<{
+        allow: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        ask: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        deny: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    model: z.ZodOptional<z.ZodString>;
+    maxTurns: z.ZodOptional<z.ZodInt>;
+    allowManagedPermissionRulesOnly: z.ZodOptional<z.ZodBoolean>;
+    allowManagedHooksOnly: z.ZodOptional<z.ZodBoolean>;
+    disableBypassPermissionsMode: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+type ManagedSettings = z.infer<typeof ManagedSettingsSchema>;
 /**
- * 模型发现 — Live API → disk cache → static catalog 三层回退 [Hermes models.py]。
+ * 托管策略的最终形态 —— 三个开关 + 「这台机器上到底有没有托管设置」。
  *
- * 改造前只有 6 个 provider 有 base URL，且 URL 拼接只对「用户传进来的」那份做
- * `/v1` 归一化，内置那份不做——于是 anthropic / google / xai / perplexity 永远
- * 走不到 live 列表，而用户填 `https://x.com/v1` 会被拼成 `https://x.com/models`。
- * 现在 base URL 全部与 `@ai-sdk/*` 各 provider 的默认 chat baseURL 对齐（同一
- * 个域名下发现和调用才可能一致），`/v1` 有无由候选重试决定而不是靠猜。
+ * `present` 单独留着是因为它和「三个开关全 false」不是一回事：前者是
+ * 「管理员没管这台机器」，后者是「管理员管了但只下发了几条 deny」。
+ * 诊断措辞和 `/permissions` 面板都要区分这两种。
  */
-interface DiscoverResult {
-    models: string[];
-    source: 'live' | 'cache' | 'static';
+interface ManagedPolicy {
+    /** 读的是哪个文件。哪怕不存在也带着 —— 管理员要知道该往哪儿放 */
+    path: string;
+    present: boolean;
+    allowManagedPermissionRulesOnly: boolean;
+    allowManagedHooksOnly: boolean;
+    disableBypassPermissionsMode: boolean;
 }
+/** 没有托管设置时的策略。**三个开关全 false**，理由见文件头 */
+declare function noManagedPolicy(path: string): ManagedPolicy;
 /**
- * `<base>/models` 的候选列表：原样一个，再一个把结尾 `/v1` 反转过来的。
+ * 三个开关里**打开了的**那几个，逐条一句人话。全关时是空数组。
  *
- * provider 到底是 `https://api.deepseek.com/models` 还是
- * `https://api.deepseek.com/v1/models`、用户填的 base 带不带 `/v1`，猜不准也
- * 没必要猜——第一个不通就试第二个。这个「toggle 而不是 strip」的做法抄的是
- * hermes-agent/hermes_cli/models.py 的 `alternate_base`。
+ * 开了的必须逐个说出来 —— 验收 #19 要的就是「诊断里说明」，而「我的 allow
+ * 规则怎么全没了」正是这几个开关最典型的现场表现：不说，用户就只能怀疑是 bug。
+ *
+ * 回数组而不是拼好的字符串：`/permissions` 面板要逐行画，启动诊断要一行 ——
+ * 拼接的活交给各自的呈现方，措辞只有这一处。
  */
-declare function modelListCandidates(baseUrl: string): string[];
+declare function managedSwitchNotes(policy: ManagedPolicy): string[];
 /**
- * 从响应里取模型 id。两种形状都要认：
- *   - OpenAI / Anthropic：`{ data: [{ id }] }`
- *   - Google 原生 ListModels：`{ models: [{ name: "models/gemini-2.5-pro" }] }`
- *     —— `models/` 前缀要摘掉，配置和用户输入里写的都是裸名
- *     （hermes models.py:5148 踩过这个坑，注释里挂着 gemini-cli #12532）
+ * 托管策略挡下了一件事时抛的错。
+ *
+ * 单独一个类型是为了让 CLI 能把它和「模块起不来」区分开：这不是故障，
+ * 是**策略生效了**，退出码和措辞都该不一样（用户要做的是改配置，不是报 bug）。
  */
-declare function parseModelList(payload: unknown): string[];
+declare class ManagedPolicyError extends Error {
+    readonly code = "MANAGED_POLICY";
+    /** 用户接下来该干什么。和 message 分开，宿主可以排在第二行 */
+    readonly hint: string;
+    constructor(message: string, hint: string);
+}
 /**
- * 发现 provider 可用模型 [Hermes discoverModels]。
+ * `disableBypassPermissionsMode` 的执行点（验收 #20）。
  *
- * 1. 调 API 拉取 live 模型列表 → 缓存
- * 2. 失败 → 读磁盘缓存
- * 3. 空 → 回退到静态目录
+ * ## 为什么是**拒绝启动**而不是静默降级到 default
+ *
+ * 降级是「更安全」的那一侧，但它会让用户以为自己在 bypass 里 —— 然后每一次
+ * 审批弹窗都成了怪现象，而真正的原因（IT 禁掉了这个级别）一个字都看不见。
+ * 权限级别是用户**显式**要的东西（`--permission bypass` 或 config.yaml 里那一行），
+ * 显式请求被策略挡下必须当面说，这跟「配了个不认识的级别回退到 default」
+ * 那种笔误不是一回事。
+ *
+ * 挡的是级别本身，不区分它从哪一层来 —— `--permission`、`EPOCH_PERMISSION`、
+ * `~/.epoch/config.yaml` 最后都汇进同一个 `config.permission`，
+ * 在这里分叉等于把「哪个来源算数」这个问题又答一遍。
  */
-declare function discoverModels(homeDir: string, provider: string, apiKey?: string, baseUrl?: string): Promise<DiscoverResult>;
-/** 清除 provider 的模型缓存 */
-declare function clearModelCache(homeDir: string, provider: string): void;
+declare function assertLevelAllowed(level: PermissionLevel, policy: ManagedPolicy): void;
 
 /**
- * 预算闸门 —— 累加用量、判断是否该停。
+ * 设置来源分层 —— 五层发现、合并、信任闸门（方案 22 §2.4 / §2.5）。
  *
- * 判定时机由调用方（agent/loop.ts）决定，但契约是明确的：
- * **每轮拿到 usage 之后、发起下一轮请求之前**检查。预算的意义是阻止
- * 下一次花钱；请求发出去之后再检查只能事后记账，钱已经花掉了。
+ * ```
+ * ① 内置默认        schema 默认值           ┐
+ * ①ᐟ⁵ 插件         ~/.epoch/plugins/<插件>/settings.json ← **只有 deny 生效**（方案 32）
+ * ② 用户级          ~/.epoch/config.yaml    ┘ 这两层由 loader.ts 交出来，是本文件的入参 base
+ * ③ 项目级          <项目根>/.epoch/settings.json        ← 信任闸门
+ * ④ 项目本地        <项目根>/.epoch/settings.local.json  ← 信任闸门
+ * ⑤ 命令行          --settings <file>
+ * ∞ 企业托管        机器级 managed-settings.json         ← 不过闸门，见 managed.ts
+ * ```
  *
- * 语义要点：
- *   - token 上限与成本上限**任一**触顶即触顶
- *   - 无定价数据时看 `onUnknownPricing`：
- *       'warn'（默认）token 上限照常生效、成本上限跳过，并且只告警一次
- *       'block'          当作触顶（前提是用户确实配了 maxCostUsd，
- *                        否则「没配预算」不该因为查不到定价就把人拦下来）
- *   - 一个 budget 字段都没配 → 永不触顶，此时闸门退化成纯记账器
+ * ## 合并语义只有两条
  *
- * ## 两把尺子：跨会话累计 vs 本次调用（方案 28）
+ * - `permissions.allow/ask/deny` 三张列表**取并集**（去重，保序）。
+ *   项目想加一条 deny，不该被迫把用户那张 deny 抄一遍
+ * - 其余键**覆盖**，高层级赢
  *
- * `budget.maxCostUsd` 是「这个月别超」—— 它的计数器 `micros` 会从 `BudgetStore`
- * 恢复，跨进程、跨会话累加。`maxCallCostUsd`（`--max-budget-usd`）是「这一次别超」，
- * 计的是 `callMicros`：**从这个闸门实例被造出来那一刻起算，永不恢复、永不持久化**。
+ * ## 为什么不写在 loader.ts 里
  *
- * 两把尺子叠加，谁先触到听谁的。同一轮同时触到时报跨会话那条 —— 它是更硬的墙
- * （调高单次上限不解决问题），先说更硬的那个才不会让用户白试一次。
+ * 项目级要过信任闸门，而闸门要 `config.homeDir`（信任记录存那儿）和
+ * `config.trust.enabled` —— 两者都得先把用户级配置解析完才有。塞进 `loadConfig()`
+ * 就成了「加载配置需要先加载配置」。所以做成**加载后的第二相**：
+ * 装配层拿到 base config、判完信任，再调这里。
+ *
+ * ## 只放行三个键，不是偷懒
+ *
+ * `permissions` / `model` / `maxTurns`。刻意排除的：
+ *
+ * - **`permission`（级别）** —— 让仓库能写 `permission: bypass` 的话，
+ *   `epoch trust add` 就从「允许读这个仓库的指令文件」变成了一个隐式的提权开关，
+ *   正是 [trust/gate.ts](../trust/gate.ts) 文件头写着要避免的事
+ * - **`shell`** —— 它在装配之前就被 `applyShell()` 消费掉了，放进来只会得到
+ *   一个「配了但不生效」的键
+ * - **`hooks` / `provider`** —— hook 会 spawn 子进程，等价于任意代码执行；
+ *   provider 里有凭据。这两个哪怕已信任也不该由仓库说了算
+ * - **`compression`（2026-08-16 加这一段时判的）** —— 见下面那一节
+ *
+ * 想加键就往 {@link SettingsFileSchema} 里加，并且必须回答「仓库作者拿它能做什么」。
+ *
+ * ## 一次真的照这条判据走了一遍：`compression` 判**不进**白名单
+ *
+ * 2026-08-16 给 `EpochConfig` 补了 `compression.enabled` / `compression.threshold`
+ * （设计稿「设置 › 记忆与上下文」那个连着两轮记「只记不改」的空壳开关）。
+ * 那一轮顺手要回答的问题是：这两个键要不要也放进白名单。**判不进**，三条：
+ *
+ * 1. **上面那个问题有答案，而答案是坏的。** 仓库作者拿 `compression.enabled: false`
+ *    能做的是：让**别人**在这个仓库里开的长会话悄悄撞满上下文窗口。症状是 provider
+ *    回 400，而现场离这个键十万八千里 —— 用户会以为是我们坏了。
+ *    拿 `threshold: 1` 能做同一件事，而且更隐蔽（开关还写着「开」）。
+ *    反过来 `threshold: 0.01` 是让每一轮都调一次 utility 模型，**花的是用户的钱**。
+ *    ⚠️ 注意这条和 `permission` 那一条**不是**同一种坏：那一条是提权，这一条是
+ *    「让别人的会话以一种查不出来的方式变坏」。两者都够格排除，理由要分开写 ——
+ *    合成一句「不安全」的话，下一个人判新键时没有可比的先例
+ * 2. **它和它的两个邻居同级。** `contextLength` 和 `maxTurns` 是设置页
+ *    「记忆与上下文」那一节里紧挨着的两行，而 `contextLength` **也不在白名单里**。
+ *    压缩阈值是 `contextLength` 的一个系数（乘出来才是那条线），
+ *    让系数比被乘数更容易被仓库改，是个说不出理由的口子
+ * 3. **写路径今天也接不住它。** `compression.enabled` 是**嵌套键**，而
+ *    [write.ts](./write.ts) 的 `writeUserYaml()` 只认不带缩进的顶层 `key:`
+ *    （`spliceTopLevel`）。放进白名单等于让设置页画出一个保存按钮，
+ *    按下去回 `unwritable-file` —— 决定 20 ① 骂的正是这个形状。
+ *    ⚠️ 这一条**是三条里最弱的**：它描述的是今天的实现，不是设计判断。
+ *    真要收它，前两条才是要被推翻的东西；只把 `spliceTopLevel` 改成认嵌套键
+ *    并不足以让这个键进白名单
+ *
+ * 于是这两行在设置页上是**只读**的（`overridable: false` / `chain: []` /
+ * `writes: []`），和 `contextLength` / `budget.*` 逐字同一种形态：
+ * 如实印出值和来源层，然后说出改它的真正路径（`~/.epoch/config.yaml`）。
  */
 
-interface BudgetGuardOptions {
-    /** 预算配置。缺省 = 不限制 */
-    budget?: BudgetOptions;
-    /** 当前模型单价。查不到就别传——**不要传 0 冒充免费** */
-    pricing?: ModelPricing;
-    /** 跨会话累计存储。配合 sessionId 才生效 */
-    store?: BudgetStore;
-    /** 会话 ID。给了才做持久化，否则只在内存里算单次 run */
-    sessionId?: string;
+/**
+ * 由**文件**提供的那几层，**顺序即优先级**（`managed` 最高）。反查来源层的两处
+ * （`buildPermissionsControl` 的规则表、`explainSetting` 的标量链条）都照这个顺序
+ * 从后往前取「最高的那一层」。
+ *
+ * **这个数组就是那张顺序表本身，别再抄第二份。** 2026-08-15 之前是「这里一个联合
+ * 类型 + `buildPermissionsControl` 里一个字面量数组」，靠两句注释要求同步；现在
+ * {@link SettingsLayer} 由它派生 —— 加一层而漏了这张表，那个新值压根不在联合类型
+ * 里，**当场编译不过**。漏一层的后果是那层的规则 / 标量被反查成 `unknown`，
+ * 于是面板告诉用户「不知道这个值从哪来」，正好是它存在的理由本身。
+ */
+declare const SETTINGS_LAYER_ORDER: readonly ["plugin", "user", "project", "projectLocal", "cli", "managed"];
+/** 由**文件**提供的那几层（用户级由 loader 负责，内置默认在 schema 里） */
+type SettingsLayer = (typeof SETTINGS_LAYER_ORDER)[number];
+/**
+ * 这一层最后怎么了。
+ *
+ * `gated` 是本方案独有的一档：文件读到了、也解析了，但目录没被信任，
+ * 于是**只有 deny 被采纳**。它既不是 `loaded` 也不是 `missing`，
+ * 混进任何一档都会让启动诊断说谎。
+ */
+type LayerStatus = 'loaded' | 'gated' | 'missing' | 'failed';
+/**
+ * 设置文件里的**标量**键 —— `permissions` 不在这里，它走并集不走覆盖。
+ *
+ * 这两个加上 `permissions` 就是 {@link SettingsFileSchema} 的全部（白名单的判据
+ * 见文件头），所以「哪些键能被项目级压回去」这个问题的答案是**闭的** ——
+ * 设置页据此决定哪几行挂得起六层链条，剩下的行只可能有 ① 和 ②。
+ */
+declare const SCALAR_KEYS: readonly ["model", "maxTurns"];
+type ScalarKey = (typeof SCALAR_KEYS)[number];
+/** 一层写进去的标量。没写的键**整个缺席**，不是 `undefined` —— 两者在链条上是两行 */
+type LayerScalars = {
+    readonly [K in ScalarKey]?: SettingsFile[K];
+};
+interface LayerOutcome {
+    layer: SettingsLayer;
+    /** 文件路径。`user` 层是 `~/.epoch/config.yaml` */
+    path: string;
+    status: LayerStatus;
+    /** 这一层**最终采纳**的规则（`gated` 时只剩 deny），PR-4 的来源标注要用 */
+    lists: PermissionRuleLists;
     /**
-     * **本次调用**的金额上限（美元）。对应 `--max-budget-usd`。
+     * 这一层**实际覆盖掉**的标量键（方案 43 §七的来源标注要用）。真源是
+     * {@link applyScalars} 的返回值 —— 那是全流程唯一往 `config` 上写标量的地方，
+     * 所以「这一层贡献了什么」和「这一层真的写进去了什么」不可能分叉。未信任的 ③④
+     * 过完闸门已经没有标量了，插件层（①ᐟ⁵）压根不调 `applyScalars`，两者都是空对象。
      *
-     * 不放进 `budget`（那是 `EpochConfig.budget` 的形状，语义是跨会话累计），
-     * 也不做成配置项：它是一次性的，配进 yaml 里等于变成第二条长期预算。
+     * ⚠️ **`user` 层这里恒为空**，那不是漏了：用户级是 loader 交出来的 base，它已经
+     * 把 schema 默认值和 `config.yaml` 合并过了，`resolveSettings` 手上分不出 ① 和
+     * ②。那一刀由 loader 的 `getConfigOrigins()` 切，见 [provenance.ts](./provenance.ts)。
      */
-    maxCallCostUsd?: number;
+    scalars: LayerScalars;
+    /** 可直接写进 diagnostics 的一句话；`missing` 时是 undefined —— 没配过不用说 */
+    detail?: string;
 }
-declare class BudgetGuard {
-    private readonly budget;
-    private readonly defaultPricing;
-    private readonly store;
-    private readonly sessionId;
-    /** 本次调用的金额上限（微美元）。没给就是 undefined = 不限 */
-    private readonly callCapMicros;
-    private usage;
-    /** 已知定价部分的累计花费（微美元）。从没拿到过定价时为 undefined */
-    private micros;
-    /**
-     * 造出来那一刻的累计花费（微美元），本次调用的**起算线**。
-     *
-     * 取差值而不是另记一个「本次加了多少」的计数器，是为了把 `delegate_task`
-     * 派出去的那笔算进来：子 agent 是另一个闸门、只往 `BudgetStore` 里写，
-     * 父这边靠 `syncFromStore()` 采纳。自己单独累加就只看得见父进程发的请求，
-     * 而那笔钱**确实是这一次调用花的**。
-     */
-    private readonly baselineMicros;
-    /** 是否出现过「有用量但查不到定价」的轮次 */
-    private sawUnknownPricing;
-    private warned;
-    private unknownPricingWarned;
-    constructor(opts?: BudgetGuardOptions);
-    /**
-     * 本次调用花掉的（微美元）。
-     *
-     * 从没拿到过定价时是 0 —— 「不知道花了多少」不构成拦人的理由，
-     * 和 `breachReason()` 里成本上限遇到未知定价的处置完全一致
-     * （那条路归 `onUnknownPricing` 管，不在这里另开一套语义）。
-     */
-    private callSpentMicros;
-    /**
-     * 累加一次用量，返回累加后的状态。
-     *
-     * 第二个参数有三种形态，**三种语义各不相同**（方案 19 PR-1）：
-     *
-     * | 调用形态                          | 用哪个单价        | 为什么                                    |
-     * | --------------------------------- | ----------------- | ----------------------------------------- |
-     * | `add(usage)`                      | `defaultPricing`  | 没说用了哪个模型 = 就是配置里那个         |
-     * | `add(usage, { model, pricing })`  | `pricing`         | 明确知道用了谁、也知道多少钱              |
-     * | `add(usage, { model })`           | **不回落，记未知** | 知道用了谁，但查不到它的价                |
-     *
-     * 第三行是这个签名存在的全部理由。改造前的形态是
-     * `add(usage, pricing?: ModelPricing)`，`pricing ?? this.defaultPricing`
-     * 会把「查不到」悄悄换成「主模型的价」—— 而降级之后主模型的价是**错的**，
-     * 且错得很有说服力（能算出一个像样的数字，闸门照常运转，只是永远拦不住）。
-     *
-     * 拿一个已知是错的数字继续算，比承认不知道更危险。
-     */
-    add(usage: TokenUsage, rate?: {
-        model: string;
-        pricing?: ModelPricing;
-    }): BudgetStatus;
-    /** 是否已触顶。触顶后不该再发起下一次模型请求 */
-    exceeded(): boolean;
-    /**
-     * 从存储重新同步累计，只在持久化的数字**更大**时采纳。
-     *
-     * 为什么需要：`delegate_task` 的子 agent 是另一个 `AgentLoop`、另一个
-     * `BudgetGuard`，只是共用同一个 sessionId。父 guard 内存里持着自己那份累计，
-     * 子任务跑完往文件里写了「父 + 子」，父的下一次 `persist()` 会拿旧的内存值
-     * 盖回去——子任务的花费凭空消失，上限被稀释。
-     *
-     * 取「更大者」而不是无条件采纳：同一个会话里累计只增不减，所以更大的那份
-     * 一定是更新的。这样也顺带扛住了别的进程同时在写同一个会话（虽然正常不该发生）。
-     *
-     * 调用点在**发起请求之前**，和触顶判定同一个位置——同步完再判，才判得准。
-     */
-    syncFromStore(): void;
-    /**
-     * 触顶原因，没触顶就是 undefined。
-     *
-     * 单独暴露而不是让调用方去读 status()：status() 会消费掉「只报一次」的
-     * 标记，只想问一句「能不能继续」的地方不该有副作用。
-     *
-     * **跨会话那三条判在前，`call-cost` 判在最后**：同一轮两把尺子都触到时，
-     * 跨会话那条是更硬的墙（调高单次上限也过不去），先说更硬的那个。
-     */
-    breachReason(): BudgetBreach | undefined;
-    /** 跨会话累计那三条 */
-    private sessionBreach;
-    /** 本次调用那一条（`--max-budget-usd`） */
-    private callBreach;
-    /**
-     * **预检**：再加 `extraTokens` 个 input token 会不会触顶。不会就是 undefined。
-     *
-     * `breachReason()` 回答的是「已经花超了吗」，只看得见 provider 事后报回来的
-     * 数字。而图片是唯一一种**发出去之前就能估出量级**的开销（见
-     * `context/image-tokens.ts`），所以它值得单独有个预检点：一张 4K 截图动辄
-     * 上千 token，等 usage 回来再说，钱已经花了。
-     *
-     * 三条刻意的取舍：
-     *   - `extraTokens <= 0` 直接放行 —— 估不出来的输入在上游已经折成 0，
-     *     「不知道」不构成拦人的理由
-     *   - 定价查不到时**不拦**成本上限：那条路归 `onUnknownPricing` 管
-     *     （见 `breachReason()`），预检不该另开一套「查不到就拦」的语义
-     *   - 只按 input 单价折算：图片进的是 input 侧，输出多少这里无从知道
-     */
-    projectedBreach(extraTokens: number): BudgetBreach | undefined;
-    /**
-     * 预检不通过时给用户的一句人话。
-     *
-     * 和 `describeBreach()` 分开写，因为要说的不是同一件事：那边是「已经花超了，
-     * 停」，这边是「**还没发**，发了才会超，所以没发」。把「未发送、未计费」写进
-     * 文案是必须的 —— 否则用户看到预算提示的第一反应是「我这次的钱白花了」。
-     */
-    describeProjectedBreach(breach: BudgetBreach, extraTokens: number): string;
-    /**
-     * 剩余额度。对应上限没配就是 undefined。
-     *
-     * 两把尺子都配了时 `costUsd` 报**更紧的那一份** —— 宿主拿它画进度条，
-     * 显示一个先到不了的数字等于没显示。
-     */
-    remaining(): {
-        costUsd?: number;
-        tokens?: number;
-    };
+interface SettingsResolution {
+    /** 合并后的配置。入参 `base` 不会被改动 */
+    config: EpochConfig;
+    layers: LayerOutcome[];
+    issues: ParseIssue[];
     /**
-     * 累计用量快照。有定价数据时带上 costUsd。
-     *
-     * ⚠️ 算术**借 {@link persistedUsage}**，不在这儿再写一遍：没有 guard 的时候
-     * （上一个进程留下的会话）同一个数要从落盘那条记录里重建，两处必须逐字相同。
-     * 判据全文在那个函数上。
+     * 第 ∞ 层的三个元开关（§2.6）。**永远非空** —— 没有托管文件时是
+     * `noManagedPolicy()`，三个开关全 false。调用方因此不用为「有没有托管」分支
      */
-    snapshot(): TokenUsage;
+    managed: ManagedPolicy;
+}
+/** 一个插件带来的 `settings.json`（方案 32）。`plugin` 只用于诊断措辞 */
+interface PluginSettingsFile {
+    plugin: string;
+    path: string;
+}
+interface ResolveSettingsOptions {
+    /** 第 5 层：`--settings <file>`。用户在命令行显式给的，**不过信任闸门** */
+    settingsPath?: string;
     /**
-     * 当前状态。
+     * 第 1.5 层：插件的 `settings.json`，来自 `loadPlugins().settingsPaths`。
      *
-     * 注意 `justWarned` / `justWarnedUnknownPricing` 是**一次性**的：读到 true
-     * 的同时标记就被消费掉了，再调用一次就是 false。告警是给人看的，
-     * 每轮刷一遍屏就没人看了。
+     * 优先级在用户级**之下**，且只有 `deny` 生效 —— 见 {@link loadPluginLayer}。
      */
-    status(): BudgetStatus;
-    /** 触顶时给用户的一句人话 */
-    describeBreach(breach: BudgetBreach): string;
+    pluginSettings?: readonly PluginSettingsFile[];
     /**
-     * 把一次 add 的结果翻译成给宿主的事件。
-     *
-     * 放在闸门里而不是循环里：`justWarned` 是一次性标记，翻译逻辑跟着标记走
-     * 才不会出现「某条路径忘了发告警」的漂移。
+     * 第 ∞ 层：企业托管设置文件。不给就用 `managedSettingsPath()` 的机器级默认值。
      *
-     * `run` 是**这一次 run 到此刻为止**的用量（方案 42 PR-2）。闸门自己算不出它 ——
-     * 闸门的账本是累计的，而「这一次 run」的边界只有调用方知道（同一个闸门实例
-     * 可以被 `BudgetStore` 恢复成带着上次会话的余额）。所以由 `loop.ts` 传进来，
-     * 没有就不带这个键。
+     * **这个参数存在的唯一理由是可测性和嵌入宿主**，不是给用户的开关：它没有
+     * 对应的环境变量、也没有对应的命令行参数，理由见 infra 的 `managedSettingsPath()`。
      */
-    toEvents(status: BudgetStatus, run?: TokenUsage): AgentEvent[];
-    /** 告警文案。status().justWarned* 为 true 时给宿主拿去展示 */
-    describeWarning(status: BudgetStatus): string;
-    /** 已用比例，取金额（两把尺子）和 token 三个维度里更紧张的那个 */
-    private usedRatio;
-    private warnThreshold;
-    private restore;
-    private persist;
+    managedPath?: string;
+}
+/** 三张列表的总条数 */
+declare function countRules(lists: PermissionRuleLists | undefined): number;
+/**
+ * 合并 ③④⑤∞ 四层文件设置到已加载的配置上。
+ *
+ * **会抛**：`opts.settingsPath` 指的文件不是合法 JSON 时抛 `SettingsFileError`
+ * （方案 29 验收 #16，理由见 `finishLayer`）。其余任何一层坏了都不抛。
+ *
+ * @param base       `loadConfig()` 的产物（第 ①② 层）。**不会被修改**
+ * @param projectRoot 项目根，取自 `resolveProjectRoot()` —— 必须和信任判定用的是
+ *                    同一个答案，否则会出现「诊断说未信任、实际却加载了」
+ * @param execTrusted 工作区授过**执行类**吗（`TrustDecision.exec`），取自
+ *                    `decideTrust()`。本文件不自己判
+ *
+ * ## ⚠️ ③④ 两层**整份**归执行类，不按字段拆（2026-09-11）
+ *
+ * 拆档之后有一个看着更细的选法：`permissions.allow` 归执行类，`model` /
+ * `maxTurns` 那两个标量跟着读类回来。**不这么做**，判据是这一层的 `gated`
+ * 语义已经是「读到了、也解析了，但只有 deny 被采纳」——再按字段切一刀，
+ * 这一层就有了三种半生不熟的状态，而设置页那条六层来源链要为每一格分别解释
+ * 「这一格为什么在、隔壁那格为什么不在」。
+ *
+ * 代价如实写着：只授了读类的工作区，它 `.epoch/settings.json` 里的 `model`
+ * 不生效 —— 和拆档之前「未信任」那一档的行为**逐字节相同**，不是新增的限制。
+ */
+declare function resolveSettings(base: EpochConfig, projectRoot: string, execTrusted: boolean, opts?: ResolveSettingsOptions): SettingsResolution;
+
+/**
+ * 「为什么是这个值」—— 一个配置键赢在哪一层，以及被压住的层各自写了什么。
+ *
+ * ```
+ * ① 内置默认        schema 的 `.default()`              ┐
+ * ② 用户级          ~/.epoch/config.yaml                ├ loader 那一相，合成 `base`
+ * 环境变量          EPOCH_* / provider 的 API key 变量   ┘
+ * ③ 项目级          <项目根>/.epoch/settings.json        ┐
+ * ④ 项目本地        <项目根>/.epoch/settings.local.json  ├ resolveSettings 那一相
+ * ⑤ 命令行          --settings <file>                    │
+ * ∞ 企业托管        机器级 managed-settings.json         ┘
+ * ```
+ *
+ * ## 为什么要单独一相，而不是让 `resolveSettings` 顺手交出来
+ *
+ * `resolveSettings` 拿到的 `base` 已经是 loader 合并完的产物 —— schema 默认值、
+ * `config.yaml`、环境变量全拍在了一起。它分不出 ① 和 ②，而**分不出的代价是
+ * 撒谎**：一个用户从没配过的键会被标成「② 用户级」，于是他去翻一个根本没写
+ * 这一行的文件。所以 ①／② 那一刀由 loader 的 `getConfigOrigins()` 来切，
+ * 本文件只负责把两相拼成一条链。
+ *
+ * ## 三条口径，写在这儿免得下一个人各猜一遍
+ *
+ * 1. **链条只有六格，`plugin`（第 ①ᐟ⁵ 层）不在里面。** 那一层只认
+ *    `permissions.deny`，标量键它一个都碰不到（判据在 `loadPluginLayer`）。
+ *    摆一格永远是「—」的行，等于告诉用户「装个插件也许能换掉你的模型」。
+ * 2. **不在白名单里的键压根不产出链条**（`chain: []`）。`SettingsFileSchema`
+ *    只放行 `permissions` / `model` / `maxTurns`，别的键 ③④⑤∞ 碰不到 ——
+ *    给它们画一条六层链条，就是在暗示「这一行也可能被项目级压回去」，
+ *    而用户会照着这个暗示去 `.epoch/settings.json` 里写一个永远不生效的键。
+ * 3. **`unknown` 是留给「分不出」的，不是给「没配过」的。** 没配过是
+ *    `builtin`，那是个确切答案。`unknown` 只在「base 里的值和内置默认不一样、
+ *    却没有任何一处记账说是谁写的」时出现 —— 今天它够不到（loader 把
+ *    `config.yaml` 和每一个环境变量覆盖都记了账），留着是为了哪天多一条
+ *    没记账的来路时，它显示成一个陌生的词，而不是被悄悄归到「② 用户级」。
+ */
+
+/**
+ * 一个配置键的值。
+ *
+ * 收数组是给**有序的链**这种值留的形态（2.0.0 之前就是 `fallback.providers`
+ * 那一行，随老写法删了；今天名单里一个都没有，形态留着）—— **不在这里 join 成
+ * 字符串**：分隔符是排版，两份 catalog 里未必一样，而服务端拼一次就等于把一个
+ * 界面决定钉死在网线上。
+ */
+type SettingValue = string | number | boolean | readonly string[];
+/**
+ * 一个配置项的来源层。编号与叫法逐字照 [docs/SETTINGS.md](../../../../docs/SETTINGS.md)
+ * 那张层表，**不另起一套** —— 用户在文档里读到的「③ 项目级」和界面上看到的
+ * 必须是同一个词。
+ *
+ * `env` 不在那张层表里，因为它不是一个「设置层」：环境变量是在 loader 那一相
+ * 覆盖 `config.yaml` 的，位置和用户级同一格（于是它**会被项目级压回去**，
+ * 这条反直觉的事实正是这条链要说出来的东西之一）。
+ */
+type SettingLayer = 'builtin' | 'user' | 'env' | 'project' | 'projectLocal' | 'cli' | 'managed' | 'unknown';
+/** 链条上的一格。这一层没写这个键时**整个不带 `value`** —— 界面画成「—」 */
+interface SettingStep {
+    layer: SettingLayer;
+    value?: SettingValue;
+}
+interface SettingChain {
+    /** 点分路径，与 `config.yaml` 里的写法逐字一致（`budget.maxCostUsd`） */
+    key: string;
+    /** 生效值。谁都没写、又没有内置默认时**整个不带这个键** */
+    value?: SettingValue;
+    /** 赢的那一层 */
+    layer: SettingLayer;
+    /** 六层链条，低 → 高。不在白名单里的键是**空数组**（判据见文件头第 2 条） */
+    chain: readonly SettingStep[];
 }
+/** loader 那一相里，一个键的值是谁写的 */
+type BaseOrigin = 'builtin' | 'user' | 'env';
+/**
+ * 一次 `loadConfig()` 里，哪些键是**用户自己写的**，以及写在哪儿。
+ *
+ * 键是点分路径（`model` / `budget.maxCostUsd`），和 `config.yaml` 里的写法一致 ——
+ * 界面上那一行的标题就是拿它当 catalog key 的后缀，两边对不上会显示成一个空格子。
+ */
+interface ConfigOrigins {
+    /** `~/.epoch/config.yaml` 里真的出现过、而且**真的生效了**的键 */
+    readonly file: ReadonlySet<string>;
+    /** 被环境变量覆盖掉的键（`EPOCH_MODEL` / provider 的 API key 变量等） */
+    readonly env: ReadonlySet<string>;
+}
+/** 空账。用户级什么都没写时的形状，也是 loader 起不来时的诚实答案 */
+declare function noConfigOrigins(): ConfigOrigins;
+/**
+ * 这个键在 loader 那一相是谁写的。
+ *
+ * **环境变量优先于文件**，因为解析链就是这个顺序（loader 第 5 层压第 2 层）：
+ * 两处都写了时生效的是环境变量，说成「② 用户级」会让用户去改一个改了也不管用
+ * 的地方。
+ */
+declare function originOf(origins: ConfigOrigins, key: string): BaseOrigin;
+/** loader 那一相交出来的一格 */
+interface BaseSlot {
+    /** `loadConfig()` 产物里这个键的值 */
+    value?: SettingValue;
+    /** `defaultConfig()` 里这个键的值 —— ① 那一格 */
+    builtin?: SettingValue;
+    /** 谁写的，来自 {@link originOf} */
+    origin: BaseOrigin;
+}
+/** 白名单键才给得出的那一半：这个键在 `LayerScalars` 里叫什么、各层结果是什么 */
+interface FileSlots {
+    key: ScalarKey;
+    layers: readonly LayerOutcome[];
+}
+/**
+ * 拼一条链。
+ *
+ * @param key   点分路径，原样带进结果里（本函数不解析它，取值是调用方的事）
+ * @param base  loader 那一相的结论
+ * @param file  ③④⑤∞ 那一相。**不给 = 这个键不在白名单里**，于是 `chain` 是空数组
+ *
+ * 赢的那一层 = 链条上**最后一个写了值**的格子；一个都没写就是 ①（那时值要么是
+ * 内置默认，要么这个键压根没有默认值 —— 后者的诚实答案仍然是「① 内置默认，
+ * 而它是空的」，不是「不知道」）。
+ */
+declare function explainSetting(key: string, base: BaseSlot, file?: FileSlots): SettingChain;
 
 /**
- * 计价 —— 把一次用量折算成钱。
+ * 配置系统 — 10 层解析链 [Hermes config.py]。
  *
- * 两个刻意的设计：
+ * 1. schema 默认值（[config/schema.ts](./schema.ts) 是**唯一**真源）
+ * 2. config.yaml（zod 逐字段补默认值，等价于原来的 deep-merge）
+ * 3. ${ENV_VAR} 模板展开（递归，最多 10 层）
+ * 3.5 SecretStore（系统钥匙串，装配层预取后注入 —— 见 `readProviderKeyEnv`）
+ * 4. .env 文件（secrets）
+ * 5. process.env 直接覆盖（最高优先级）—— `EPOCH_BASE_URL` / `EPOCH_PROVIDER` 两个例外：
+ *    它们**什么都不改**，只各报一条诊断（`reportDroppedEnv`）
+ * 6. 损坏回退（last-known-good → 默认值）
+ * 7. 损坏备份（config.yaml.corrupt.<ts>.bak）
+ * 8. 缓存（mtime + size + env_snapshot）
+ * 9. 多 Profile（~/.epoch/profiles/<name>/）
+ * 10. load() / loadReadonly() 双接口
  *
- * 1. **无定价数据返回 undefined，不返回 0**。0 的意思是「免费」，undefined 的
- *    意思是「不知道」。闸门对这两者的处理完全不同：免费可以随便跑，不知道
- *    要么告警放行、要么直接拦（见 budget-guard 的 onUnknownPricing）。
+ * 校验：全程 zod（`parseLenient`），**失败不抛异常**——单个配置文件写错不该让
+ * agent 起不来（safeInit 语义）。代价是必须把 issues 交出去：`loadConfig(diags)`
+ * 的可选参数，或事后 `getConfigIssues()`。静默吞掉等于没校验。
  *
- * 2. **内部一律用「微美元整数」累加**。金额是浮点数最容易出事的地方：
- *    0.1 + 0.2 !== 0.3，几千轮累加下来会漂移到小数点后好几位都对不上。
- *    micro-USD（1e-6 美元）对任何现实用量都是整数级精度，累加无损，
- *    只在对外暴露时除回美元。
+ * 模板展开在校验**之前**做：`maxTurns: ${MAX_TURNS}` 这种写法在展开前是字符串，
+ * 先校验会把合法配置判成类型错误。[Gemini resolveEnvVarsInObject → validateSettings]
  *
- * ## 各字段的口径（方案 42 PR-0 之后是**真的**在用）
+ * ## 2.0.0：老写法读到就忽略
  *
- * - `cacheHitTokens` / `cacheWriteTokens` 与 `inputTokens` **不重叠**，各自单独计价。
- *   这条契约以前是空的 —— ProviderRouter 只上报 in/out 两个数，缓存字段恒为 0，
- *   不是 provider 不给，是 `provider/types.ts` 把 usage 写死成两个字段截断了。
- *   现在 `toTokenUsage()` 按同一个口径逐字段接了进来（`inputTokens` 取的是
- *   SDK 的 `noCacheTokens`），所以 `computeCostMicros` 里那两行缓存乘法
- *   从这版起是真在算钱，不再恒等于 0。
- * - `reasoningTokens` **包含在** `outputTokens` 里，**不单独计价、也不加进总数** ——
- *   加了就是把输出侧算两遍。
+ * `provider:` 段和裸模型名（`model: gpt-4o` / `deepseek/deepseek-chat`）删了，模型只认
+ * 「我的模型」条目（`@<id>`）。旧文件里还有它们时**不报错、不迁移**（用户拍的板：唯一的真实
+ * 用户是星云，它跟着出一版），只是剥掉 + 每处一条 `legacy_ignored` —— 剥在 zod **之前**，
+ * 判据在 {@link stripLegacyModelConfig} 上。
  */
 
+/** 加载配置时的覆盖项 */
+interface LoadConfigOptions {
+    /**
+     * 家目录覆盖 —— 嵌入宿主用（Electron 的 `app.getPath('userData')`）。不给时
+     * （CLI / TUI 的常态）行为与改造前完全一致；给了就**压过**环境
+     * （`EPOCH_HOME` / `EPOCH_PROFILE`）和 yaml 里的 `homeDir` / `dbPath`：这个选项的
+     * 契约是「这个 runtime 实例的数据全落在这里」，让 yaml 能反过来改掉它就会出现
+     * 「嵌入方指定了目录、引擎却写回 `~/.epoch`」。`dbPath` 必须跟着一起换 ——
+     * SessionManager / MemoryManager / TrackerDB 都吃它，只改 homeDir 的话
+     * 两个实例照样共用同一个 SQLite 文件。
+     */
+    homeDir?: string;
+}
 /**
- * 折算一次用量的花费，单位微美元（整数）。
+ * 完整加载（深拷贝），适合 CLI 入口。
  *
- * 无定价数据返回 undefined。每个维度各自取整：单价可能是 0.0028 这种
- * 小数，逐维取整的误差上限是 0.5 微美元 / 维 / 次，且是确定性的，
- * 累加一万次也不会像浮点那样越滚越偏。
+ * @param diags 传进来就把校验问题按「一个问题一行」追加进去（宿主的启动诊断）。
+ *              不传也不会静默：问题存在 `getConfigIssues()` 里。
  */
-declare function computeCostMicros(usage: TokenUsage, pricing?: ModelPricing): number | undefined;
+declare function loadConfig(diags?: DiagnosticSink, opts?: LoadConfigOptions): EpochConfig;
+/** 最近一次加载的校验问题（带字段路径），空数组表示配置全合法 */
+declare function getConfigIssues(): ParseIssue[];
 /**
- * 折算一次用量的花费，单位美元。无定价数据返回 undefined，**不是 0**。
+ * 最近一次加载里，**哪些键是用户自己写的**（方案 43 §七的来源标注）。
+ *
+ * ## 这个函数存在的理由只有一句话
+ *
+ * `loadConfig()` 交出来的那份配置已经把 ①（schema 默认值）、②（`config.yaml`）
+ * 和环境变量拍在了一起，分不出来。而设置页每一行都要挂来源层徽标 ——
+ * 分不出的话，一个用户从没配过的键会被标成「② 用户级」，于是他去翻一个根本
+ * 没写这一行的文件。**那是这一屏最不该出的一句假话**（判据全文在
+ * [provenance.ts](./provenance.ts) 的文件头）。
+ *
+ * ## 两条口径
+ *
+ * - **`file` 记的是「真的生效了」，不是「文件里写了」。** 整份 zod 校验失败时
+ *   loader 是**整体退回默认值**（见 `parseRawConfig` 的注释），那时用户写的一个键
+ *   都没生效，所以 `file` 是空集 —— 不是空集的话，设置页会把一屏默认值挨个标成
+ *   「② 用户级」。未知键同理不记：它们被 `z.object()` 丢掉了。
+ * - **`LoadConfigOptions.homeDir` 覆盖掉的 `homeDir` / `dbPath` 不记账。**
+ *   那是嵌入宿主在装配期定的，既不是 ① 也不是 ②，而这两个键设置页不显示。
+ *   哪天要显示了，它需要的是自己的一档（「宿主」），不是硬塞进现有的三档。
+ *
+ * 配置损坏退到 last-known-good 时，交出来的是**那一份的账**，不是空账 ——
+ * 生效的配置是它，账也该是它的。
  */
-declare function computeCost(usage: TokenUsage, pricing?: ModelPricing): number | undefined;
-/** 微美元 → 美元 */
-declare function microsToUsd(micros: number): number;
-/** 美元 → 微美元（用于把用户配的 maxCostUsd 转进同一套整数体系） */
-declare function usdToMicros(usd: number): number;
+declare function getConfigOrigins(): ConfigOrigins;
 /**
- * 金额的人类可读形式。
+ * 「我的模型」某个条目自己的 key（2026-10-15）。三层的优先级同 {@link readSecret}。
  *
- * 不到 1 分钱的时候 `$0.00` 等于没说，所以小额多给两位有效数字 ——
- * 那条规则现在是 protocol 里 `formatMoney()` 的 `'adaptive'` 档，行为一字未改。
+ * 名字由 protocol 的 `entrySecretName(id)` 算出来。没有就是 `undefined` ——
+ * 2.0.0 起**不再退到那家 provider 的环境变量 key**：条目的 key 只认它自己那把。
+ */
+declare function readEntryKey(id: string, homeDir?: string): string | undefined;
+/**
+ * 这台机器**跑得起来吗**：至少有一条能注册进路由的条目。
  *
- * ## ⚠️ 名字里的 `Usd` 说的是**入参**，不是输出
+ * 两条道：任一条凭据（{@link hasProviderCredentials}），或者一条**不吃 key 的条目** ——
+ * 本地 Ollama、自建 OpenAI 兼容端点。后一条是 2026-10-15 补的，判据在 core router 的
+ * `registerEntries` 上（那两类没 key 也注册）。
  *
- * 入参恒为美元（全仓的算术都是），而印出来的那一串跟着
- * `display.currency` 走 —— 配了人民币就是 `¥6.10`。这两件事的分界全文在
- * [protocol/src/money.ts](../../../protocol/src/money.ts) 文件头那张表。
+ * ⚠️ **它和 `hasProviderCredentials` 是两个问题，别合并**：那条答的是「凭据配了没」
+ * （`epoch status` 那一行「凭证」用它），这条答的是「这台机器现在能不能跑一个模型」。
+ * 一台只挂了本地 Ollama 的机器，前者是 false、后者是 true —— 拿前者当「能不能跑」用，
+ * 那台机器只会收到一句「run epoch model to set a model and API key」然后**什么都不跑**
+ * （2026-10-15 的现场）。
+ */
+declare function hasUsableModel(homeDir?: string): boolean;
+/**
+ * 是否已配置任一条凭据：「我的模型」里任一条的 key（`EPOCH_MODEL_KEY_<id>`）。
  *
- * 名字**刻意没改成 `formatMoney`**：这个仓里 `Usd` 后缀的一贯含义就是
- * 「这一格装的是美元」（`costUsd`、`maxCostUsd`、`microUsd`），而它的入参正是。
- * 改名会让调用点看起来像是可以传别的币种进来 —— 那是这里最不想要的误解。
+ * 2.0.0 起不再看各家 provider 的环境变量 key（`DEEPSEEK_API_KEY` 之类）——零配置自动认领
+ * 随老写法删了，那些变量今天不让任何一个模型跑起来，算进来就是假话。
  *
- * @param digits 定死几位。缺省 `'adaptive'` = 这个函数的历史行为。
- *   闸门那几句文案给的是 `4`（**不是**口味：那几句印的是单轮 / 累计成本，
- *   常在 $0.003 这一档，两位会印成一个「免费」的假象）
+ * 钥匙串只看**名字**（`listStoredSecretNames()`，纯文件读）：这个函数是同步的，而它要回答的
+ * 正是「要不要提示用户去加一条模型」，名字这一层足够。
  */
-declare function formatUsd(usd: number, digits?: MoneyDigits): string;
+declare function hasProviderCredentials(homeDir?: string): boolean;
+
 /**
- * 累加两份用量（含缓存 / 思考 / 总数四个可选维度），返回新对象。
+ * 「我的模型」的落盘：`<homeDir>/models.json`（2026-10-15）。
  *
- * 可选维度加完仍是 0 就不写进结果 —— 保住「0 是真的零，undefined 是不知道」：
- * 两轮都没缓存命中，累计里就不该冒出一个 `cacheHitTokens: 0` 让人以为
- * 这个 provider 支持缓存只是没命中。
+ * 形状、引用写法（`@<id>`）和「为什么单独一份 JSON 而不是 config.yaml 的一节」
+ * 在 protocol 的 `model-entry.ts` 文件头，这里只管读写。
  *
- * ## ⚠️ `totalTokens` **不是**可加的维度，别照着上面三项写
+ * ## 坏一条只丢那一条
  *
- * 上面三项缺席当 0 加是对的（0 是加法的单位元）；`totalTokens` 不是，它是一个
- * **总量**。`(a.totalTokens ?? 0) + (b.totalTokens ?? 0)` 在「一边报了、另一边
- * 没报」时收到的只有报了的那一份，而 `inputTokens` / `outputTokens` 两侧是加全
- * 了的 —— 于是这份累计**自相矛盾**：`totalTokens < promptTokens + outputTokens`。
+ * `config.yaml` 是「一个字段校验不过就整份回退默认值」（loader 的 `parseLenient`）。
+ * 这份文件**不照那个做**：它是一张列表，条目之间互不依赖，而用户手改坏一条时
+ * 把另外五条一起丢掉、主模型跟着退回默认，是一个远比「那一条不见了」更难懂的结局。
+ * 丢掉的那条进 `issues`，装配层把它打进诊断。
  *
- * 这一档不是假想：`toTokenUsage` 明确放行了「两个总量都在、`totalTokens` 缺席」
- * 的 usage（OpenAI 兼容端点不带 `stream_options` 的那一家就这样），而同一段会话
- * 里换 provider（降级、或压缩那一发走别的模型）就会把两种 usage 加到一起。
+ * ## 文件里没有 key
  *
- * 症状有两层，**第二层不是显示问题**：
+ * key 进 SecretStore（名字是 `entrySecretName(id)`）。这份文件因此可以被用户
+ * 打开、复制、发给别人看，而不会顺手把凭据带出去。
+ */
+
+/** 文件名。和 `config.yaml` 同一个目录 */
+declare const MODEL_ENTRIES_FILE = "models.json";
+declare function modelEntriesPath(homeDir: string): string;
+/**
+ * 把一条**已经校验过**的条目收成规范形状。读和写都过这一道，所以盘上的永远是同一种写法。
  *
- * 1. 屏幕上「共 X token」比旁边 `↑ + ↓` 还小（两处都读 `totalUsageTokens()`，
- *    而它优先信 `totalTokens`）；
- * 2. `budget.maxTokens` 那道闸门读的是同一个数（`budget-guard.ts` 的
- *    `sessionBreach()`），偏小 = **上限拦不住**，多跑的那几轮是真花钱的。
+ * - `protocol` / `rawUrl` 只对自定义端点（`openai-compatible`）有意义，别家的丢掉 ——
+ *   留着的话界面上会读出一个「这条走 Anthropic 协议」，而它其实走 DeepSeek 自己的 SDK；
+ * - `rawUrl` 只对 `openai-chat` 有意义（它省掉的正是 `/chat/completions` 那一段）；
+ * - 档位去重并按 {@link REASONING_EFFORTS} 的顺序排，滑块从左到右就是这个顺序；
+ *   `default` 不在档位里就丢掉，免得默认值指向一个滑块上没有的刻度；
+ * - 空串一律视为没填。
+ */
+declare function normalizeModelEntry(entry: ModelEntry): ModelEntry;
+/** 校验一条外来的（网线上的、用户手写的）条目。不合格返回 null + 原因 */
+declare function parseModelEntry(raw: unknown): {
+    ok: true;
+    entry: ModelEntry;
+} | {
+    ok: false;
+    reason: string;
+};
+interface LoadedModelEntries {
+    entries: ModelEntry[];
+    /** 被丢掉的条目和原因（坏 JSON / 某一条校验不过 / id 重复），给诊断用 */
+    issues: string[];
+    /** 宿主那一组的显示名（`hostPreset.label` 落在这里，2026-10-15）。没有宿主就是 undefined */
+    hostLabel?: string;
+}
+/**
+ * 读 `models.json`。文件不在是常态（没用过这个功能），返回空表、没有 issue。
  *
- * 所以没报的那一侧按我们自己的口径折算一份（`totalUsageTokens()` 的兜底那一支，
- * 对那一侧来说是精确值），再相加。两边都没报时仍然整个不写 —— 那时
- * `totalUsageTokens()` 自己算出来的和这里能算出来的是同一个数，凭空多一个字段
- * 只会让「provider 报过」和「我们替它算的」变得分不出来。
+ * 判据见文件头「坏一条只丢那一条」。id 重复时**留第一条**：引用按 id 解析，
+ * 留哪条都会让另一条的引用指错，而第一条是文件里先写的那一条、最可能是用户本来的意思。
  */
-declare function addUsage(a: TokenUsage, b: TokenUsage): TokenUsage;
+declare function loadModelEntries(homeDir: string): LoadedModelEntries;
 /**
- * 估算一张图片占多少 input token。
+ * 整份写回。写 `<path>.<pid>.tmp` 再 rename，形状照 `config/write.ts` 的 `commit()`。
  *
- * **为什么需要它**：`usage` 事件里的数字是 provider 上报的，本来就含图片 token，
- * 那部分不缺。缺的是**发请求之前**的估算 —— 预算闸门的检查点在请求发出前
- * （见 loop.ts 的注释），而 `estimateTokens()` 只按字符数算，压根看不见图片。
- * 于是「点一下截图，钱没了」这件事只能事后才发现。
+ * 新建时给 0o600：它和凭据住在同一个 `~/.epoch/` 下，而且里面有用户的自建端点地址
+ * （内网地址本身就是一种不该随手给同机别的用户读的信息）。
  *
- * 用 OpenAI 的公式当统一口径：epoch-agent 的 provider 全是 OpenAI 兼容协议
- * （见 config/schema.ts），各家实际切法有出入，但这是个**估算**，量级对得上
- * 就够预算闸门用。宽高读不出来时返回 undefined —— **不是 0**。
- * 0 意味着「免费」，undefined 意味着「不知道」，闸门对这两者的处理必须不同
- * （与 `TokenUsage.costUsd` 同一条约定）。
+ * 盘上那份有读不进来的部分（整份坏 / 某几条不合法）时，先原样留一份
+ * `<path>.corrupt.<时间>.bak` 再写：调用方拿到的 `entries` 里本来就没有那几条，
+ * 不留的话「坏一条只丢那一条」这一写就变成真丢了（整份坏时是全丢）。
+ * 形状照 `loader.ts` 的 `backupCorruptConfig`。
+ *
+ * @throws 写不进去时原样抛 —— 调用方（runtime）决定怎么告诉用户
  */
-declare function estimateImageTokens(width?: number, height?: number): number | undefined;
 /**
- * 用量里计入预算的 token 总数。
+ * 写回。第三个参数是新加的：宿主那一组的显示名（只在宿主预设时传；不传 = 保留盘上的，见下）。
  *
- * 实现住在 protocol（`totalUsageTokens`）—— TUI 的 ctx% 要用同一套口径，
- * 而 tui 不许 import core。这里保留这个名字只是为了不惊动 core 里既有的调用点。
+ * ⚠️ 用户这一侧（设置页保存）**永远不带 hostLabel** —— 盘上那份是宿主写的，原样保留；
+ * 只有宿主预置（`host-preset.ts`）才动它。
  */
-declare function totalTokens(usage: TokenUsage): number;
+declare function saveModelEntries(homeDir: string, entries: readonly ModelEntry[], hostLabel?: string): void;
 
 /**
- * 进程级的展示币种（2026-09-13）。
+ * 「这个模型认不认图」—— **现问模型本人，不查表**（2026-09-11）。
  *
- * ## 为什么是模块级插槽，而不是逐处穿参
+ * ## 为什么需要它：查表这条路有一个它永远答不出的问题
  *
- * 判据逐条借 infra 的 `setLang()`，在这儿是原样成立的：金额的格式化点散在
- * core / runtime / cli / tui / web **五个包十几处**，而币种对它们中的每一个都是
- * **同一个进程级的一次性决定** —— 一个进程不会一半印美元一半印人民币。
- * 逐处穿参等于把一个显示偏好变成一次全仓签名改造，而 infra 里 `setLogLevel` /
- * `setShell` / `setSecretStore` 早就是这个形态。
+ * `model-metadata.ts` 的三层（静态表 → OpenRouter 缓存 → 默认值）全都是
+ * **别人对这个模型的描述**。上游改一次名字，两层同时失效，第三层的默认值是
+ * `supportsImages: false` —— 于是一个认图的模型在我们眼里瞎掉，而且是**静默**
+ * 瞎掉：用户得到的是「当前模型不支持图片输入」，一句可核对的理由都没有。
+ *
+ * 2026-09-11 实测的现场：DeepSeek 把 `deepseek-v4-flash-vision-exp` 改名成
+ * `deepseek-flash`，静态表 miss、OpenRouter 那份 872 条里**根本没有这个裸名**，
+ * 于是 `epoch -i 图.png` 被我们自己拦死。而同一张图直接发给它，它答得一字不差。
+ *
+ * ## 判据是 **input token 涨没涨**，而这一格换过两次，两次都是被实测逼的
+ *
+ * ### 第一版：靠 warning —— 当天就否掉了
+ *
+ * 最省事的做法是不确定就照发，SDK 报了 warning（`droppedUserContentParts`）
+ * 就说明它不认。**走不通**，同一天的 A/B：
+ *
+ * | 模型              | 出站 body | warnings | 回答        | input token |
+ * | ----------------- | --------- | -------- | ----------- | ----------- |
+ * | `deepseek-flash`  | 带图      | `[]`     | `"Red"`     | 225         |
+ * | `deepseek-v4-pro` | 带图      | `[]`     | `"Unknown"` | 99          |
+ *
+ * 第二行就是那个坑：**它把图无声吞了，一条 warning 都不报**，SDK 和 provider
+ * 两侧都认为这次请求很正常。同理「不报错就算认图」「答了话就算认图」也都被这一行
+ * 否掉 —— 它不报错，它也答了话。
+ *
+ * ### 第二版：靠**回答**（发一张纯红图问颜色，答得出红就算）—— 2026-09-12 否掉
+ *
+ * 它把断言落在了模型的**识图准确率**上，而那个东西既不稳定、也不是我们的责任。
+ * 同一张 132 字节的红方块、同一个型号（`deepseek-v4-flash-vision-exp`）、
+ * **逐字节相同的出站 body**（钩 `fetch` 抓的，四次都是 `bodyLen=50948`），
+ * 连着跑四次的回答是：
+ *
+ * | run | 回答      |
+ * | --- | --------- |
+ * | 1   | `Red`     |
+ * | 2   | `White`   |
+ * | 3   | `Magenta` |
+ * | 4   | `Blue`    |
+ *
+ * 也就是说这一版探针在这个型号上有约 3/4 的概率把一个**确实收到了图**的模型
+ * 判成瞎子，然后把 `false` 写进缓存。
  *
- * ## ⚠️ 它住在 core，不是 infra —— 因为 `CurrencyDisplay` 住在 protocol
+ * ### 这一版：靠 input token 的**增量**
  *
- * infra 是**零内部依赖包**（`check-layers.mjs` 的 `ALLOWED` 里它的内部依赖是空的），
- * import 不了 protocol，而这个插槽装的正是一个 protocol 类型。放 infra 就得在
- * infra 里再声明一遍那个形状 —— 那是 `LANGS` 在两边各写一份的老问题，而那一份
- * 有一条「两边行为逐项相等」的门禁兜着，这一份不值得再开一条。
+ * 同一批运行里，回答四选一，而 `inputTokens` 纹丝不动 ——
+ * 带图 21088、不带图 20904（各跑两次，两两分毫不差）。差的那 184 个 token
+ * 就是那张图：**模型为它计了费，也就意味着它真的收下并处理了。**
  *
- * 代价是 **tui 够不着**（它不许 import core）。那一侧走宿主注入，形状和它那份
- * `t()` 逐字一样 —— 判据在 [tui/src/money.ts](../../../tui/src/money.ts)。
+ * 于是探针发两发（同一句话，一发带图一发不带），比 `inputTokens`：
  *
- * ## 没设过的时候：`undefined` = 美元
+ * - 涨了 → 图被接收（上表第一行，225 vs 99 也正是这个形状）；
+ * - 没涨 → 被无声吞了（上表第二行）；
+ * - 拿不到 usage → `inconclusive`，**不写缓存**。
  *
- * 这不是兜底的敷衍，它是**默认路径本身**：绝大多数用户没配 `display.currency`，
- * 而 `formatMoney()` 在 `currency` 缺席时的输出与 2026-09-13 之前逐字节相同
- * （判据在 protocol 的 `money.ts` 文件头最后一节）。
+ * ⚠️ **这一版探不出「收了图但看不懂」**，这是刻意放弃的：那是模型质量，
+ * 不在我们的责任边界内。上面那四次 `White` / `Magenta` / `Blue` 在新判据下
+ * 全部算「认图」—— 而它们确实都认图，这正是想要的。
  *
- * ⚠️ 所以这里**不给一个 `{code:'USD', rate:1}` 的默认值**。给了的话「没配过」和
- * 「配了美元」在下游就分不出来了，而 `WireConfigResponse.currency` 那一格的语义
- * 恰恰是「没配就没有这个键」。
- */
-
-/**
- * 钉住这个进程的展示币种。装配层读完配置后调一次。
+ * ⚠️ 探针的两发**不共享长前缀、也够不着任何 prompt 缓存**（裸 `generateText`，
+ * 没有 system prompt，整条消息一百多 token）。这一条是承重的：provider 一旦
+ * 把 `inputTokens` 按「未命中缓存的部分」报，两发的数就不可比了。
  *
- * **生产路径上只有 `cli/src/language.ts` 的 `applyConfiguredCurrency()` 调它**，
- * 和 `setLang()` 在同两个入口、同一个位置 —— 理由也一样：它必须跑在**任何一句
- * 带金额的文案之前**，而最早那几句是启动诊断里的预算行（`boot.budget_cost`）。
+ * ## ⚠️ 第三档 `inconclusive` 的含义跟着换了
  *
- * 传 `undefined` 可以把它清回美元 —— 用例需要这条（进程是复用的，
- * 一个用例设过币种之后不还原，下一个用例会莫名其妙拿到人民币）。
+ * 第二版里它指「正文是空的」（推理型号把输出预算花在思考上）。这一版**不看正文**，
+ * 所以那一档现在指「**拿不到 usage**」（provider 不报、或基线那一发自己失败了）。
+ * 处置没变：这一次按「不认图」走，但**一个字都不写缓存** —— 写进去会把一个
+ * 认图的模型钉死（`true` 的缓存是 30 天）。
  */
-declare function setDisplayCurrency(next: CurrencyDisplay | undefined): void;
+
 /**
- * 当前展示币种，没设过就是 `undefined`（= 美元）。
- *
- * ⚠️ **现读，别存成模块级常量。** 常量在 `setDisplayCurrency()` 之前就求值完了，
- * 币种会被永久钉在「没设过」那一档 —— 同 tui 那份 `t()` 文件头「别在模块级调
- * `t()`」那条，失败形态一模一样：不报错，只是永远印美元。
+ * ⚠️ 2026-09-12 从 1 提到 2：判据从「答不答得出红」换成「input token 涨没涨」
+ * （判据全文在文件头）。**旧结论是用另一把尺子量的**，其中的 `false` 有相当一部分
+ * 是第二版那个 3/4 误判率产出的 —— 继续信它等于把一次已经作废的实验的结果
+ * 当成这次的。整份丢掉，重新探。
  */
-declare function displayCurrency(): CurrencyDisplay | undefined;
+declare const PROBE_VERSION = 2;
 
 /**
- * 设置文件的形状与读取 —— 项目级 / 项目本地 / `--settings` / 企业托管**共用这一份**。
+ * Provider 错误的分类：一个异常对象 → 「该怎么恢复」。
  *
- * 从 [sources.ts](./sources.ts) 拆出来的原因很具体：企业托管（第 ∞ 层，§2.6）
- * 的文件形状是「同样的键 + 三个元开关」，它要复用这里的 schema 和读取逻辑，
- * 而 `sources.ts` 又要消费托管层的解析结果 —— 两个文件互相 import 就成了环。
- * 把**共用的下层**摘出来是拆环最省事的一刀。
+ * 从 `router.ts` 拆出来（方案 26 PR-2）。理由不是行数，是**它是纯函数**：
+ * 输入一个错误、输出一档恢复动作，不碰状态、不碰网络。留在 router 里的时候，
+ * 想验「'maximum context length is 128500 tokens' 会不会被当成 500 服务器错误」
+ * 得先造一个有凭据的 router 出来 —— 而那跟这个判断毫无关系。
  */
-
+/** 恢复动作。降级链的每一档由它决定走到哪 */
+type RecoveryAction = 'retry' | 'rotate_credential' | 'switch_model' | 'switch_provider' | 'abort';
+declare class ProviderError extends Error {
+    readonly code: number;
+    readonly recoverable: boolean;
+    readonly recovery: RecoveryAction;
+    constructor(message: string, code: number, recoverable: boolean, recovery?: RecoveryAction);
+}
 /**
- * 设置文件（`.epoch/settings.json` / `--settings`）的形状。
- *
- * 字段从 `EpochConfigSchema` **摘**出来而不是另写一份：值域约束（`maxTurns`
- * 是正整数、`permissions` 三张列表都是非空字符串）只能有一处定义，
- * 抄第二份迟早对不上。
+ * 「没有可用凭证」的错误码。
  *
- * ## `.unwrap()` 不是花活，`.partial()` 在这儿是错的
+ * 单独提成常量是因为**装配层要按它分档**：没配 key 是「还没配置」（诊断记
+ * `skipped`），不是「模块坏了」（`failed`）—— 后者会让 `epoch doctor` 退非 0，
+ * 于是一台刚装完、还没配 key 的机器（以及 CI）会被判成坏的。
+ * 见 runtime/src/services.ts 的 Provider 那一段。
+ */
+declare const PROVIDER_NO_CREDENTIAL = 1001;
+/**
+ * 错误分类。
  *
- * `EpochConfigSchema` 里 `model` / `maxTurns` 都带 `.default()`，而 zod v4 的
- * `.partial()` 只是往外面套一层 `ZodOptional`，**里面的默认值照样兑现**：
- * `pick({model:true}).partial().parse({})` 得到的是 `{model:'gpt-4o-mini'}`，
- * 不是 `{}`。合并语义是「给了才覆盖」，于是一份只写了 `permissions` 的
- * `settings.json` 会顺手把用户配的 model 打回内置默认值 —— 而且诊断里
- * 一个字都不会说。所以必须先 `.unwrap()` 摘掉 default 再 `.optional()`。
+ * 顺序很关键，而且**语义模式必须排在裸数字之前**：
+ * 原来 `/500|502|503/` 排在 context-length 检查前面，任何含 "500" 的消息
+ * （"maximum context length is 128500 tokens"、"reduce to 500 tokens"）
+ * 都会被当成服务器错误去重试——而 context 超限重试一万次也不会好。
  *
- * 用例里钉了「`parse({})` 必须深等于 `{}`」，它红了就说明这层保护没了。
+ * 裸状态码只在错误对象本身带 status 时才可靠，所以优先读 status，
+ * 再退化到从消息里找**带边界**的状态码。
  */
-declare const SettingsFileSchema: z.ZodObject<{
-    permissions: z.ZodOptional<z.ZodObject<{
-        allow: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        ask: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        deny: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    }, z.core.$strip>>;
-    model: z.ZodOptional<z.ZodString>;
-    maxTurns: z.ZodOptional<z.ZodInt>;
-}, z.core.$strip>;
-type SettingsFile = z.infer<typeof SettingsFileSchema>;
+declare function classifyProviderError(err: unknown): {
+    code: number;
+    recovery: RecoveryAction;
+};
+
 /**
- * `--settings` 指的文件用不了（方案 29 §2.4 / 验收 #16）。
+ * 换模型的前置判定（方案 26）。
  *
- * 单独一个类型的理由同 `ManagedPolicyError`：这**不是故障也不是 bug**，是用户
- * 显式给的那份文件坏了，CLI 要按「预期内失败」打一行（见 cli 的 `errors.ts`）。
+ * 单独一个文件而不是塞进 `router.ts`：
  *
- * 为什么只有这一层抛、其余层照旧「整份忽略 + 一条 issue」：见
- * [sources.ts](./sources.ts) 里 `finishLayer` 那处注释。
+ * 1. `router.ts` 已经 700 多行（AGENTS.md 铁律 3 的上限是 500），不该再长
+ * 2. 这三道检查是**纯函数** —— 给它「有没有凭据」和「模型什么能力」，
+ *    它就能算出换不换得成。抽出来之后单测不用造一个 `ProviderRouter`
+ *    （那要真凭据、要碰 `readProviderKeyEnv()`），直接喂假事实就行
+ *
+ * 判定留在 core 而不是 UI 层：换一个宿主（TUI / web / headless）也得是同一套
+ * 判据，放 UI 里就会有第二份、然后两份开始不一致 —— 这个仓库在
+ * 「provider → 环境变量名」那张表上已经吃过一次这个亏。
  */
-declare class SettingsFileError extends Error {
-    /** 下一步做什么。和 message 分开，CLI 排在第二行 */
-    readonly hint: string;
-    constructor(message: string, hint: string);
+
+/** 判定要用到的外部事实，由 router 注入 */
+interface SelectionDeps {
+    /** 这个 provider 有没有可用凭据 */
+    hasCredential: (provider: ProviderType) => boolean;
+    /** 这个模型的能力（窗口 / 视觉 / 工具） */
+    capability: (model: string) => ModelCapability;
 }
 /**
- * JSON 解析失败的一句话，**保证带行号**。
+ * 换模型的三道前置检查。
  *
- * Node 22 的 `JSON.parse` 报错里其实已经有 `(line 3 column 7)` 了，但不能靠它：
- * 一是旧版本只给 `position 18`，二是 `Unexpected end of JSON input` 这类压根没有
- * 位置。所以按 position 自己数一遍换行 —— 「第几行」是用户唯一能拿去改文件的
- * 信息，而 position 是个要他打开编辑器去数字节的数。
+ * 两条拒绝都是「换过去下一轮必然失败」，**在这里拦住比让 provider 报 400 好**：
+ * 400 是已经计费的，而且错误消息里不会写「因为你刚才换了模型」。
  *
- * 数不出来时**原样返回 Node 那句**，不编一个假的行号。
+ * 换模型**不清空上下文**——那正是它的意义所在（对着同一段对话换个更强或更便宜
+ * 的脑子）。代价就是新模型必须接得住已经积累的东西，所以才有这三道检查。
  */
-declare function describeJsonError(err: unknown, text: string): string;
+declare function evaluateSelection(want: ModelSelection, deps: SelectionDeps, ctx?: SelectionContext): SetSelectionResult;
 
 /**
- * 企业托管设置 —— 第 ∞ 层（方案 22 §2.6）。
- *
- * 由 IT 管理员分发到一个**普通用户写不了**的机器级路径
- * （见 infra 的 `managedSettingsPath()`），压过其余全部五层，且额外带三个
- * **元开关** —— 它们管的不是「配了什么」，而是「别的层还算不算数」：
- *
- * | 开关                             | 作用                                       |
- * | -------------------------------- | ------------------------------------------ |
- * | `allowManagedPermissionRulesOnly` | 其余各层的 allow / ask / deny 全部忽略     |
- * | `allowManagedHooksOnly`          | 用户级 hook 一律不加载                     |
- * | `disableBypassPermissionsMode`   | `permission: bypass` 拒绝启动              |
- *
- * ## 这一层**不过信任闸门**，而且不该过
+ * 模型级降级：降到哪儿、以及什么时候不该再降回来（方案 26 PR-2，验收 #8/#10/#11）。
  *
- * 闸门问的是「这个仓库的作者可不可信」。托管设置不来自仓库，来自这台机器的
- * 管理员 —— 拿仓库信任去闸它没有意义，而且方向是反的：托管策略的典型内容是
- * deny，越是不信任的目录越需要它生效。
+ * 拆出来而不是继续堆在 `router.ts` 里，有两个理由：
  *
- * ## 三个开关都是「只减不增」，所以缺省一律 false
+ *   1. `router.ts` 已经 800 行，铁律 3 的线早就压在上面了
+ *   2. 这两件事**都是纯状态**，不碰 SDK、不碰网络。单独放能被用例直接盯，
+ *      不用为了验「连续失败三次会怎样」去 mock 一整个 AI SDK
  *
- * 读不到文件、文件写坏了、字段没写 —— 一律按「没有托管策略」处理。
- * 反过来（读不到就当全开）会让一次磁盘故障把所有人的 epoch 锁死，
- * 而托管策略保护的东西并不值这个代价：它挡的是用户给自己提权，
- * 不是挡攻击者（能改 `C:\ProgramData` 的人早就能改 epoch 本身了）。
+ * ⚠️ **2.0.0 起降级只剩一级**：主模型 → `fallback.model` 指向的那一条（`@<id>`，在 router）→ 失败。
+ * 原来这里还有「同家内置默认模型表」（`DEFAULT_MODELS` / `nextFallbackModel` / `defaultModelOf`）
+ * 和 `fallback.providers`（换一家用那家的默认模型）两级，都是老写法的产物，随它删了 ——
+ * 判据在 router 的 `escalate` 上。这个文件今天只剩节流那一半。
  */
 
 /**
- * 托管文件的形状 = 普通设置文件 + 三个元开关。
+ * 连续失败到几次就放弃这个模型（方案 26 验收 #8）。
  *
- * 用 `.extend()` 而不是另写一份：托管层能配的普通键必须和其它层完全一致，
- * 否则「管理员配了 model 但只有托管层不生效」这种事没人查得出来。
+ * 3 而不是 1：偶发 429 / 503 是常态，一次就放弃等于「抖一下就永久换模型」，
+ * 用户明明选了强模型却在跑弱的。也不是 10：每一次重试都是真金白银的一次请求，
+ * 而一个真的挂了的模型不会在第 7 次突然好。
  */
-declare const ManagedSettingsSchema: z.ZodObject<{
-    permissions: z.ZodOptional<z.ZodObject<{
-        allow: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        ask: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        deny: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    }, z.core.$strip>>;
-    model: z.ZodOptional<z.ZodString>;
-    maxTurns: z.ZodOptional<z.ZodInt>;
-    allowManagedPermissionRulesOnly: z.ZodOptional<z.ZodBoolean>;
-    allowManagedHooksOnly: z.ZodOptional<z.ZodBoolean>;
-    disableBypassPermissionsMode: z.ZodOptional<z.ZodBoolean>;
-}, z.core.$strip>;
-type ManagedSettings = z.infer<typeof ManagedSettingsSchema>;
+declare const MODEL_GIVE_UP_THRESHOLD = 3;
 /**
- * 托管策略的最终形态 —— 三个开关 + 「这台机器上到底有没有托管设置」。
+ * 模型失败的节流状态（方案 26 验收 #8）。
  *
- * `present` 单独留着是因为它和「三个开关全 false」不是一回事：前者是
- * 「管理员没管这台机器」，后者是「管理员管了但只下发了几条 deny」。
- * 诊断措辞和 `/permissions` 面板都要区分这两种。
+ * 解决的是这个形状：主模型挂了，每一轮都先拿它试一次、失败、再降级 ——
+ * 于是**每一轮都白烧一次失败请求**，还平白多等一次超时。连续失败到阈值之后
+ * 就不再自动打它，直接从降级链起步。
+ *
+ * ## 键是**路由键**（`provider:entry`），不是 `provider/model`
+ *
+ * 2026-10-16 修的（跨轮节流按条目化改造时漏掉的那一把尺）：两个条目可以是**同一家
+ * 同一个模型名、不同端点**（官方 + 中转站，「我的模型」明说要支持的用法）—— 按
+ * `provider/model` 记，这两条共用一本账，于是：
+ *
+ *   - 主条目（中转，恒挂）攒的失败，被降级条目（官方，好的）每轮的成功**一笔清零**，
+ *     阈值永远跨不过去 —— 「连续失败 3 次就不再自动用它」这条通知一次都不会出现，
+ *     每一轮都先在坏端点上空烧满重试预算再降级；
+ *   - 反过来 `avoidAbandoned` 会把**好的**降级条目也当成「放弃过」，主条目挂掉之后
+ *     不从它起步（表现是等一个多余的超时）。
+ *
+ * 键的口径和 `router.ts` 的 `entryTried`（`@<id>`）是同一条判据：**条目**才是用户
+ * 配置的那个东西，同家同名但不同端点的两条是两种命运。跨家同名（azure / openai 的
+ * `gpt-4o-mini`）不在这个键里区分 —— 它们在路由键里天然就不同（entry 不同）。
+ *
+ * ## 计数单位是「请求」不是「重试」
+ *
+ * 一次 `generate()` 内部为同一个模型重试三次，算 **1** 次失败而不是 3 次。
+ * 重试是同一次意图的一部分；把它算成三次，等于第一轮就把模型判死刑。
+ *
+ * ## 只在本会话内有效，且用户能一句话推翻
+ *
+ * 不落盘：模型挂了通常是分钟级的事，把「这个模型不好使」记到下次启动
+ * 会变成一个没人知道怎么解除的诅咒。`/model` 手动切回来会调 {@link clear}，
+ * 那是显式的「我要再试一次」——用户的话永远压过引擎的推断。
+ *
+ * ⚠️ 这个类**不认识 provider / model / 条目**，只收发不透明字符串：键怎么算由
+ * router 一处决定（`routeOf`），两边各算一次就又会长出第二把尺。
  */
-interface ManagedPolicy {
-    /** 读的是哪个文件。哪怕不存在也带着 —— 管理员要知道该往哪儿放 */
-    path: string;
-    present: boolean;
-    allowManagedPermissionRulesOnly: boolean;
-    allowManagedHooksOnly: boolean;
-    disableBypassPermissionsMode: boolean;
+declare class ModelFailureTracker {
+    private readonly counts;
+    private readonly abandoned;
+    /**
+     * 记一次失败。
+     *
+     * @param key 路由键（`routeKey`：`provider:entry`）
+     * @returns 这一下是不是**刚好**跨过阈值。只在跨过的那一次回 `true`，
+     *   调用方据此发一条通知 —— 之后每次失败都发就成了刷屏
+     */
+    recordFailure(key: string): boolean;
+    /**
+     * 记一次成功 —— 连续计数**清零**，不是减一。
+     *
+     * 「连续」是这里的关键词：跑通了十轮之后再失败一次，和连着失败三次，
+     * 是完全不同的两件事，只有后者说明模型真的不好使了。
+     */
+    recordSuccess(key: string): void;
+    /** 这个落点已经被放弃了吗 */
+    isAbandoned(key: string): boolean;
+    /** 抹掉一个落点的全部记录。用户手动切回它时调 —— 显式意图压过引擎的推断 */
+    clear(key: string): void;
 }
-/** 没有托管设置时的策略。**三个开关全 false**，理由见文件头 */
-declare function noManagedPolicy(path: string): ManagedPolicy;
+
 /**
- * 三个开关里**打开了的**那几个，逐条一句人话。全关时是空数组。
+ * Token 估算 —— 真分词，不再是 `chars / 4`（方案 42 §七「运行前 token 估算」）。
+ *
+ * ## 先量的那一遍
  *
- * 开了的必须逐个说出来 —— 验收 #19 要的就是「诊断里说明」，而「我的 allow
- * 规则怎么全没了」正是这几个开关最典型的现场表现：不说，用户就只能怀疑是 bug。
+ * 改造前全仓统一走 `Math.ceil(text.length / 4)`。拿**本仓库的真实文件**过一遍
+ * （2026-08-15，对照 `o200k_base` 的真实分词结果）：
  *
- * 回数组而不是拼好的字符串：`/permissions` 面板要逐行画，启动诊断要一行 ——
- * 拼接的活交给各自的呈现方，措辞只有这一处。
- */
-declare function managedSwitchNotes(policy: ManagedPolicy): string[];
-/**
- * 托管策略挡下了一件事时抛的错。
+ * | 样本                                | chars/4 | 真实 | 真 / 估   |
+ * | ----------------------------------- | ------- | ---- | --------- |
+ * | AGENTS.md 里纯中文的行              |     229 |  616 | **2.69×** |
+ * | AGENTS.md 全文（中英混排散文）      |    3008 | 6035 | **2.01×** |
+ * | core/README.md（中英混排）          |    2392 | 3333 | 1.39×     |
+ * | 三个 `.ts`（代码 + 中文 JSDoc）     |    — | — | 1.29–1.45× |
+ * | compressor.ts 里纯 ASCII 的行       |    2741 | 2701 | 0.99×     |
+ * | 纯英文散文                          |     107 |   68 | 0.64×     |
  *
- * 单独一个类型是为了让 CLI 能把它和「模块起不来」区分开：这不是故障，
- * 是**策略生效了**，退出码和措辞都该不一样（用户要做的是改配置，不是报 bug）。
- */
-declare class ManagedPolicyError extends Error {
-    readonly code = "MANAGED_POLICY";
-    /** 用户接下来该干什么。和 message 分开，宿主可以排在第二行 */
-    readonly hint: string;
-    constructor(message: string, hint: string);
-}
-/**
- * `disableBypassPermissionsMode` 的执行点（验收 #20）。
+ * 读法是：**英文和纯代码场景它一直是准的，中文场景系统性低估 2–2.7 倍**
+ * （换成 `cl100k_base` 那种老编码更差，纯中文到 3.66×）。而 `/context` 那张
+ * 占用表、路由的「这一轮塞不塞得下」、压缩器的尾部预算全都吃这个数 ——
+ * 所以它不是显示精度问题，是三处功能的地基。
  *
- * ## 为什么是**拒绝启动**而不是静默降级到 default
+ * ## 为什么挑 gpt-tokenizer
  *
- * 降级是「更安全」的那一侧，但它会让用户以为自己在 bypass 里 —— 然后每一次
- * 审批弹窗都成了怪现象，而真正的原因（IT 禁掉了这个级别）一个字都看不见。
- * 权限级别是用户**显式**要的东西（`--permission bypass` 或 config.yaml 里那一行），
- * 显式请求被策略挡下必须当面说，这跟「配了个不认识的级别回退到 default」
- * 那种笔误不是一回事。
+ * 三个候选实测（Windows / Node 24，各起**新进程**取 5 次中位数，
+ * 量的是「从 import 到算出第一个数」）。判据按这个顺序：
  *
- * 挡的是级别本身，不区分它从哪一层来 —— `--permission`、`EPOCH_PERMISSION`、
- * `~/.epoch/config.yaml` 最后都汇进同一个 `config.permission`，
- * 在这里分叉等于把「哪个来源算数」这个问题又答一遍。
- */
-declare function assertLevelAllowed(level: PermissionLevel, policy: ManagedPolicy): void;
-
-/**
- * 设置来源分层 —— 五层发现、合并、信任闸门（方案 22 §2.4 / §2.5）。
+ * 1. **不能拖慢冷启动** —— TUI 和 CLI 每次都要起。
+ *    `gpt-tokenizer/encoding/o200k_base` **89 ms**，
+ *    `js-tiktoken/lite` + `ranks/o200k_base` **289 ms**，3.2 倍差距。
+ *    而且 gpt-tokenizer 按编码分入口，另外五套词表一个字节都不会被解析。
+ *    再加上下面的懒加载，进程启动本身**一毫秒都不多花**
+ * 2. **不能引入 wasm / native 附件** —— `@dqbd/tiktoken` 是 wasm，直接出局：
+ *    `pnpm pack` / `verify:pack` 那条路会变复杂，Windows 上装 native 附件
+ *    也是本仓库的已知坑。gpt-tokenizer 是纯 JS、**零运行时依赖**
+ * 3. **体积** —— 这一条 gpt-tokenizer 是**输**的：装完 54 MB，js-tiktoken 22 MB。
+ *    但真正被 require 进内存的只有 `esm/encoding/o200k_base.js` 那 2.3 MB，
+ *    而判据顺序里冷启动排在体积前面，所以认这个亏
+ * 4. **许可证** —— MIT。**只是依赖它，没有抄任何一行代码**，所以本文件
+ *    不加 `SPDX-License-Identifier` 头（AGENTS.md 铁律 12：那个头在本仓库的
+ *    含义是「抄自 gemini-cli」，加了就必须同步登记进 NOTICE）
  *
- * ```
- * ① 内置默认        schema 默认值           ┐
- * ①ᐟ⁵ 插件         ~/.epoch/plugins/<插件>/settings.json ← **只有 deny 生效**（方案 32）
- * ② 用户级          ~/.epoch/config.yaml    ┘ 这两层由 loader.ts 交出来，是本文件的入参 base
- * ③ 项目级          <项目根>/.epoch/settings.json        ← 信任闸门
- * ④ 项目本地        <项目根>/.epoch/settings.local.json  ← 信任闸门
- * ⑤ 命令行          --settings <file>
- * ∞ 企业托管        机器级 managed-settings.json         ← 不过闸门，见 managed.ts
- * ```
+ * ## 一套编码走天下，这是**有意的近似**
  *
- * ## 合并语义只有两条
+ * 模型不同分词器就不同（GPT 的 o200k / cl100k、Claude 自己的 BPE、DeepSeek
+ * 自己的），但今天**所有模型都走 `o200k_base` 这一套**。挑它是因为它是当代
+ * 编码里 CJK 合并最充分的，拿来当 Claude / DeepSeek 的代理比 `cl100k_base` 近。
+ * 真按模型分套要各家的词表文件，那是另一轮的事 —— 这一轮只把口径统一到一处。
  *
- * - `permissions.allow/ask/deny` 三张列表**取并集**（去重，保序）。
- *   项目想加一条 deny，不该被迫把用户那张 deny 抄一遍
- * - 其余键**覆盖**，高层级赢
+ * 接口上留了 `model` 形参，今天走到 {@link encodingFor} 就被忽略掉；
+ * 留着是为了将来加分支时**调用方一行都不用改**。
  *
- * ## 为什么不写在 loader.ts 里
+ * ⚠️ **它仍然是估算。** 真值以 provider 回的 usage 为准（那本来就是准的，
+ * 见 `cost/pricing.ts` 的 `promptTokens`）。别拿这个数去断言「等于 usage」。
  *
- * 项目级要过信任闸门，而闸门要 `config.homeDir`（信任记录存那儿）和
- * `config.trust.enabled` —— 两者都得先把用户级配置解析完才有。塞进 `loadConfig()`
- * 就成了「加载配置需要先加载配置」。所以做成**加载后的第二相**：
- * 装配层拿到 base config、判完信任，再调这里。
+ * ## 2026-08-15：换了真分词器**不等于**可以摘掉界面上那枚「估算」徽标
  *
- * ## 只放行三个键，不是偷懒
+ * 这一条写在这儿是因为它已经被读反过一次。`design/web-ui/index.html:744` 那条
+ * HTML 注释末尾写着「要拿掉这个徽标得先换真 tokenizer」—— 它是**必要条件**，
+ * 不是充分条件，而同一份稿子的 `thread.css` 里 `.est` 那条写死了充分条件：
+ * 「token 有三个时刻，只有**运行前那一个**是猜的，所以这个徽标只准出现在
+ * `.mhead__sub` 里」。
  *
- * `permissions` / `model` / `maxTurns`。刻意排除的：
+ * 换句话说：这个文件治好的是**偏差有多大**（中文场景 2–2.7 倍的系统性低估），
+ * 治不好的是**它是不是猜的**。后者由两件事钉死，两件都还在：
  *
- * - **`permission`（级别）** —— 让仓库能写 `permission: bypass` 的话，
- *   `epoch trust add` 就从「允许读这个仓库的指令文件」变成了一个隐式的提权开关，
- *   正是 [trust/gate.ts](../trust/gate.ts) 文件头写着要避免的事
- * - **`shell`** —— 它在装配之前就被 `applyShell()` 消费掉了，放进来只会得到
- *   一个「配了但不生效」的键
- * - **`hooks` / `provider`** —— hook 会 spawn 子进程，等价于任意代码执行；
- *   provider 里有凭据。这两个哪怕已信任也不该由仓库说了算
- * - **`compression`（2026-08-16 加这一段时判的）** —— 见下面那一节
+ *   1. 上面「一套编码走天下」那一段 —— 编码是 o200k_base，模型可能是
+ *      Claude / DeepSeek，各家 BPE 不同；
+ *   2. 更硬的一条：运行前估算算的是**发之前**的载荷，而这一轮跑起来之后还会
+ *      插进压缩、后台任务通知、工具结果。
  *
- * 想加键就往 {@link SettingsFileSchema} 里加，并且必须回答「仓库作者拿它能做什么」。
+ * 运行前那个数的消费方是 `agent/run-estimate.ts`（决定 8 的第一个时刻），
+ * 判据全文在那个文件头。
  *
- * ## 一次真的照这条判据走了一遍：`compression` 判**不进**白名单
+ * ## ✅ 「我够不着，你来收」—— **收了**（2026-08-15，`wt/1` 留，合并时结）
  *
- * 2026-08-16 给 `EpochConfig` 补了 `compression.enabled` / `compression.threshold`
- * （设计稿「设置 › 记忆与上下文」那个连着两轮记「只记不改」的空壳开关）。
- * 那一轮顺手要回答的问题是：这两个键要不要也放进白名单。**判不进**，三条：
+ * 留的是这么一笔：两份文档里还写着这个函数是 `length/4`、而且指着一个它
+ * **从来不在**的位置（`model-metadata.ts:371`）。两处都收了，
+ * 账在 [30 §13.1](../../../../docs/verify/VERIFY_RECORD-30-web-multi-session.md)：
  *
- * 1. **上面那个问题有答案，而答案是坏的。** 仓库作者拿 `compression.enabled: false`
- *    能做的是：让**别人**在这个仓库里开的长会话悄悄撞满上下文窗口。症状是 provider
- *    回 400，而现场离这个键十万八千里 —— 用户会以为是我们坏了。
- *    拿 `threshold: 1` 能做同一件事，而且更隐蔽（开关还写着「开」）。
- *    反过来 `threshold: 0.01` 是让每一轮都调一次 utility 模型，**花的是用户的钱**。
- *    ⚠️ 注意这条和 `permission` 那一条**不是**同一种坏：那一条是提权，这一条是
- *    「让别人的会话以一种查不出来的方式变坏」。两者都够格排除，理由要分开写 ——
- *    合成一句「不安全」的话，下一个人判新键时没有可比的先例
- * 2. **它和它的两个邻居同级。** `contextLength` 和 `maxTurns` 是设置页
- *    「记忆与上下文」那一节里紧挨着的两行，而 `contextLength` **也不在白名单里**。
- *    压缩阈值是 `contextLength` 的一个系数（乘出来才是那条线），
- *    让系数比被乘数更容易被仓库改，是个说不出理由的口子
- * 3. **写路径今天也接不住它。** `compression.enabled` 是**嵌套键**，而
- *    [write.ts](./write.ts) 的 `writeUserYaml()` 只认不带缩进的顶层 `key:`
- *    （`spliceTopLevel`）。放进白名单等于让设置页画出一个保存按钮，
- *    按下去回 `unwritable-file` —— 决定 20 ① 骂的正是这个形状。
- *    ⚠️ 这一条**是三条里最弱的**：它描述的是今天的实现，不是设计判断。
- *    真要收它，前两条才是要被推翻的东西；只把 `spliceTopLevel` 改成认嵌套键
- *    并不足以让这个键进白名单
+ * - `design/web-ui/README.md`「8.2 决定 8」那条 ⚠️ 划掉重写，稿子
+ *   `index.html` 那枚「估算」徽标上面那段注释同改（它是同一句话的第二处）。
+ * - `.agents/plans/README.md`「42 划出来的底座缺口」里那一条划掉。
  *
- * 于是这两行在设置页上是**只读**的（`overridable: false` / `chain: []` /
- * `writes: []`），和 `contextLength` / `budget.*` 逐字同一种形态：
- * 如实印出值和来源层，然后说出改它的真正路径（`~/.epoch/config.yaml`）。
+ * ⚠️ **「要拿掉徽标得先换真 tokenizer」按交代的一个字没动** —— 它是
+ * **必要条件**，而充分条件（同一份稿子 `thread.css` 里 `.est` 那条：
+ * 「三个时刻里只有运行前是猜的」）今天仍然成立。两处改写都把这句话的
+ * 必要 / 充分之分写进去了，因为它已经被读反过一次。
  */
-
 /**
- * 由**文件**提供的那几层，**顺序即优先级**（`managed` 最高）。反查来源层的两处
- * （`buildPermissionsControl` 的规则表、`explainSetting` 的标量链条）都照这个顺序
- * 从后往前取「最高的那一层」。
+ * 估算一段文本的 token 数。**全仓唯一的口径**，别再各写各的。
  *
- * **这个数组就是那张顺序表本身，别再抄第二份。** 2026-08-15 之前是「这里一个联合
- * 类型 + `buildPermissionsControl` 里一个字面量数组」，靠两句注释要求同步；现在
- * {@link SettingsLayer} 由它派生 —— 加一层而漏了这张表，那个新值压根不在联合类型
- * 里，**当场编译不过**。漏一层的后果是那层的规则 / 标量被反查成 `unknown`，
- * 于是面板告诉用户「不知道这个值从哪来」，正好是它存在的理由本身。
+ * @param model 留给「将来按模型选分词器」的形参，**今天被有意忽略**，
+ *   见文件头「一套编码走天下」
  */
-declare const SETTINGS_LAYER_ORDER: readonly ["plugin", "user", "project", "projectLocal", "cli", "managed"];
-/** 由**文件**提供的那几层（用户级由 loader 负责，内置默认在 schema 里） */
-type SettingsLayer = (typeof SETTINGS_LAYER_ORDER)[number];
+declare function estimateTokens(text: string, model?: string): number;
+
 /**
- * 这一层最后怎么了。
+ * 预算闸门 —— 累加用量、判断是否该停。
  *
- * `gated` 是本方案独有的一档：文件读到了、也解析了，但目录没被信任，
- * 于是**只有 deny 被采纳**。它既不是 `loaded` 也不是 `missing`，
- * 混进任何一档都会让启动诊断说谎。
- */
-type LayerStatus = 'loaded' | 'gated' | 'missing' | 'failed';
-/**
- * 设置文件里的**标量**键 —— `permissions` 不在这里，它走并集不走覆盖。
+ * 判定时机由调用方（agent/loop.ts）决定，但契约是明确的：
+ * **每轮拿到 usage 之后、发起下一轮请求之前**检查。预算的意义是阻止
+ * 下一次花钱；请求发出去之后再检查只能事后记账，钱已经花掉了。
  *
- * 这两个加上 `permissions` 就是 {@link SettingsFileSchema} 的全部（白名单的判据
- * 见文件头），所以「哪些键能被项目级压回去」这个问题的答案是**闭的** ——
- * 设置页据此决定哪几行挂得起六层链条，剩下的行只可能有 ① 和 ②。
+ * 语义要点：
+ *   - token 上限与成本上限**任一**触顶即触顶
+ *   - 无定价数据时看 `onUnknownPricing`：
+ *       'warn'（默认）token 上限照常生效、成本上限跳过，并且只告警一次
+ *       'block'          当作触顶（前提是用户确实配了 maxCostUsd，
+ *                        否则「没配预算」不该因为查不到定价就把人拦下来）
+ *   - 一个 budget 字段都没配 → 永不触顶，此时闸门退化成纯记账器
+ *
+ * ## 两把尺子：跨会话累计 vs 本次调用（方案 28）
+ *
+ * `budget.maxCostUsd` 是「这个月别超」—— 它的计数器 `micros` 会从 `BudgetStore`
+ * 恢复，跨进程、跨会话累加。`maxCallCostUsd`（`--max-budget-usd`）是「这一次别超」，
+ * 计的是 `callMicros`：**从这个闸门实例被造出来那一刻起算，永不恢复、永不持久化**。
+ *
+ * 两把尺子叠加，谁先触到听谁的。同一轮同时触到时报跨会话那条 —— 它是更硬的墙
+ * （调高单次上限不解决问题），先说更硬的那个才不会让用户白试一次。
  */
-declare const SCALAR_KEYS: readonly ["model", "maxTurns"];
-type ScalarKey = (typeof SCALAR_KEYS)[number];
-/** 一层写进去的标量。没写的键**整个缺席**，不是 `undefined` —— 两者在链条上是两行 */
-type LayerScalars = {
-    readonly [K in ScalarKey]?: SettingsFile[K];
-};
-interface LayerOutcome {
-    layer: SettingsLayer;
-    /** 文件路径。`user` 层是 `~/.epoch/config.yaml` */
-    path: string;
-    status: LayerStatus;
-    /** 这一层**最终采纳**的规则（`gated` 时只剩 deny），PR-4 的来源标注要用 */
-    lists: PermissionRuleLists;
+
+interface BudgetGuardOptions {
+    /** 预算配置。缺省 = 不限制 */
+    budget?: BudgetOptions;
+    /** 当前模型单价。查不到就别传——**不要传 0 冒充免费** */
+    pricing?: ModelPricing;
+    /** 跨会话累计存储。配合 sessionId 才生效 */
+    store?: BudgetStore;
+    /** 会话 ID。给了才做持久化，否则只在内存里算单次 run */
+    sessionId?: string;
+    /**
+     * **本次调用**的金额上限（美元）。对应 `--max-budget-usd`。
+     *
+     * 不放进 `budget`（那是 `EpochConfig.budget` 的形状，语义是跨会话累计），
+     * 也不做成配置项：它是一次性的，配进 yaml 里等于变成第二条长期预算。
+     */
+    maxCallCostUsd?: number;
+}
+declare class BudgetGuard {
+    private readonly budget;
+    private readonly defaultPricing;
+    private readonly store;
+    private readonly sessionId;
+    /** 本次调用的金额上限（微美元）。没给就是 undefined = 不限 */
+    private readonly callCapMicros;
+    private usage;
+    /** 已知定价部分的累计花费（微美元）。从没拿到过定价时为 undefined */
+    private micros;
+    /**
+     * 造出来那一刻的累计花费（微美元），本次调用的**起算线**。
+     *
+     * 取差值而不是另记一个「本次加了多少」的计数器，是为了把 `delegate_task`
+     * 派出去的那笔算进来：子 agent 是另一个闸门、只往 `BudgetStore` 里写，
+     * 父这边靠 `syncFromStore()` 采纳。自己单独累加就只看得见父进程发的请求，
+     * 而那笔钱**确实是这一次调用花的**。
+     */
+    private readonly baselineMicros;
+    /** 是否出现过「有用量但查不到定价」的轮次 */
+    private sawUnknownPricing;
+    private warned;
+    private unknownPricingWarned;
+    constructor(opts?: BudgetGuardOptions);
     /**
-     * 这一层**实际覆盖掉**的标量键（方案 43 §七的来源标注要用）。真源是
-     * {@link applyScalars} 的返回值 —— 那是全流程唯一往 `config` 上写标量的地方，
-     * 所以「这一层贡献了什么」和「这一层真的写进去了什么」不可能分叉。未信任的 ③④
-     * 过完闸门已经没有标量了，插件层（①ᐟ⁵）压根不调 `applyScalars`，两者都是空对象。
+     * 本次调用花掉的（微美元）。
      *
-     * ⚠️ **`user` 层这里恒为空**，那不是漏了：用户级是 loader 交出来的 base，它已经
-     * 把 schema 默认值和 `config.yaml` 合并过了，`resolveSettings` 手上分不出 ① 和
-     * ②。那一刀由 loader 的 `getConfigOrigins()` 切，见 [provenance.ts](./provenance.ts)。
+     * 从没拿到过定价时是 0 —— 「不知道花了多少」不构成拦人的理由，
+     * 和 `breachReason()` 里成本上限遇到未知定价的处置完全一致
+     * （那条路归 `onUnknownPricing` 管，不在这里另开一套语义）。
      */
-    scalars: LayerScalars;
-    /** 可直接写进 diagnostics 的一句话；`missing` 时是 undefined —— 没配过不用说 */
-    detail?: string;
-}
-interface SettingsResolution {
-    /** 合并后的配置。入参 `base` 不会被改动 */
-    config: EpochConfig;
-    layers: LayerOutcome[];
-    issues: ParseIssue[];
+    private callSpentMicros;
     /**
-     * 第 ∞ 层的三个元开关（§2.6）。**永远非空** —— 没有托管文件时是
-     * `noManagedPolicy()`，三个开关全 false。调用方因此不用为「有没有托管」分支
+     * 累加一次用量，返回累加后的状态。
+     *
+     * 第二个参数有三种形态，**三种语义各不相同**（方案 19 PR-1）：
+     *
+     * | 调用形态                          | 用哪个单价        | 为什么                                    |
+     * | --------------------------------- | ----------------- | ----------------------------------------- |
+     * | `add(usage)`                      | `defaultPricing`  | 没说用了哪个模型 = 就是配置里那个         |
+     * | `add(usage, { model, pricing })`  | `pricing`         | 明确知道用了谁、也知道多少钱              |
+     * | `add(usage, { model })`           | **不回落，记未知** | 知道用了谁，但查不到它的价                |
+     *
+     * 第三行是这个签名存在的全部理由。改造前的形态是
+     * `add(usage, pricing?: ModelPricing)`，`pricing ?? this.defaultPricing`
+     * 会把「查不到」悄悄换成「主模型的价」—— 而降级之后主模型的价是**错的**，
+     * 且错得很有说服力（能算出一个像样的数字，闸门照常运转，只是永远拦不住）。
+     *
+     * 拿一个已知是错的数字继续算，比承认不知道更危险。
      */
-    managed: ManagedPolicy;
-}
-/** 一个插件带来的 `settings.json`（方案 32）。`plugin` 只用于诊断措辞 */
-interface PluginSettingsFile {
-    plugin: string;
-    path: string;
-}
-interface ResolveSettingsOptions {
-    /** 第 5 层：`--settings <file>`。用户在命令行显式给的，**不过信任闸门** */
-    settingsPath?: string;
+    add(usage: TokenUsage, rate?: {
+        model: string;
+        pricing?: ModelPricing;
+    }): BudgetStatus;
+    /** 是否已触顶。触顶后不该再发起下一次模型请求 */
+    exceeded(): boolean;
     /**
-     * 第 1.5 层：插件的 `settings.json`，来自 `loadPlugins().settingsPaths`。
+     * 从存储重新同步累计，只在持久化的数字**更大**时采纳。
      *
-     * 优先级在用户级**之下**，且只有 `deny` 生效 —— 见 {@link loadPluginLayer}。
+     * 为什么需要：`delegate_task` 的子 agent 是另一个 `AgentLoop`、另一个
+     * `BudgetGuard`，只是共用同一个 sessionId。父 guard 内存里持着自己那份累计，
+     * 子任务跑完往文件里写了「父 + 子」，父的下一次 `persist()` 会拿旧的内存值
+     * 盖回去——子任务的花费凭空消失，上限被稀释。
+     *
+     * 取「更大者」而不是无条件采纳：同一个会话里累计只增不减，所以更大的那份
+     * 一定是更新的。这样也顺带扛住了别的进程同时在写同一个会话（虽然正常不该发生）。
+     *
+     * 调用点在**发起请求之前**，和触顶判定同一个位置——同步完再判，才判得准。
      */
-    pluginSettings?: readonly PluginSettingsFile[];
+    syncFromStore(): void;
     /**
-     * 第 ∞ 层：企业托管设置文件。不给就用 `managedSettingsPath()` 的机器级默认值。
+     * 触顶原因，没触顶就是 undefined。
      *
-     * **这个参数存在的唯一理由是可测性和嵌入宿主**，不是给用户的开关：它没有
-     * 对应的环境变量、也没有对应的命令行参数，理由见 infra 的 `managedSettingsPath()`。
+     * 单独暴露而不是让调用方去读 status()：status() 会消费掉「只报一次」的
+     * 标记，只想问一句「能不能继续」的地方不该有副作用。
+     *
+     * **跨会话那三条判在前，`call-cost` 判在最后**：同一轮两把尺子都触到时，
+     * 跨会话那条是更硬的墙（调高单次上限也过不去），先说更硬的那个。
      */
-    managedPath?: string;
+    breachReason(): BudgetBreach | undefined;
+    /** 跨会话累计那三条 */
+    private sessionBreach;
+    /** 本次调用那一条（`--max-budget-usd`） */
+    private callBreach;
+    /**
+     * **预检**：再加 `extraTokens` 个 input token 会不会触顶。不会就是 undefined。
+     *
+     * `breachReason()` 回答的是「已经花超了吗」，只看得见 provider 事后报回来的
+     * 数字。而图片是唯一一种**发出去之前就能估出量级**的开销（见
+     * `context/image-tokens.ts`），所以它值得单独有个预检点：一张 4K 截图动辄
+     * 上千 token，等 usage 回来再说，钱已经花了。
+     *
+     * 三条刻意的取舍：
+     *   - `extraTokens <= 0` 直接放行 —— 估不出来的输入在上游已经折成 0，
+     *     「不知道」不构成拦人的理由
+     *   - 定价查不到时**不拦**成本上限：那条路归 `onUnknownPricing` 管
+     *     （见 `breachReason()`），预检不该另开一套「查不到就拦」的语义
+     *   - 只按 input 单价折算：图片进的是 input 侧，输出多少这里无从知道
+     */
+    projectedBreach(extraTokens: number): BudgetBreach | undefined;
+    /**
+     * 预检不通过时给用户的一句人话。
+     *
+     * 和 `describeBreach()` 分开写，因为要说的不是同一件事：那边是「已经花超了，
+     * 停」，这边是「**还没发**，发了才会超，所以没发」。把「未发送、未计费」写进
+     * 文案是必须的 —— 否则用户看到预算提示的第一反应是「我这次的钱白花了」。
+     */
+    describeProjectedBreach(breach: BudgetBreach, extraTokens: number): string;
+    /**
+     * 剩余额度。对应上限没配就是 undefined。
+     *
+     * 两把尺子都配了时 `costUsd` 报**更紧的那一份** —— 宿主拿它画进度条，
+     * 显示一个先到不了的数字等于没显示。
+     */
+    remaining(): {
+        costUsd?: number;
+        tokens?: number;
+    };
+    /**
+     * 累计用量快照。有定价数据时带上 costUsd。
+     *
+     * ⚠️ 算术**借 {@link persistedUsage}**，不在这儿再写一遍：没有 guard 的时候
+     * （上一个进程留下的会话）同一个数要从落盘那条记录里重建，两处必须逐字相同。
+     * 判据全文在那个函数上。
+     */
+    snapshot(): TokenUsage;
+    /**
+     * 当前状态。
+     *
+     * 注意 `justWarned` / `justWarnedUnknownPricing` 是**一次性**的：读到 true
+     * 的同时标记就被消费掉了，再调用一次就是 false。告警是给人看的，
+     * 每轮刷一遍屏就没人看了。
+     */
+    status(): BudgetStatus;
+    /** 触顶时给用户的一句人话 */
+    describeBreach(breach: BudgetBreach): string;
+    /**
+     * 把一次 add 的结果翻译成给宿主的事件。
+     *
+     * 放在闸门里而不是循环里：`justWarned` 是一次性标记，翻译逻辑跟着标记走
+     * 才不会出现「某条路径忘了发告警」的漂移。
+     *
+     * `run` 是**这一次 run 到此刻为止**的用量（方案 42 PR-2）。闸门自己算不出它 ——
+     * 闸门的账本是累计的，而「这一次 run」的边界只有调用方知道（同一个闸门实例
+     * 可以被 `BudgetStore` 恢复成带着上次会话的余额）。所以由 `loop.ts` 传进来，
+     * 没有就不带这个键。
+     */
+    toEvents(status: BudgetStatus, run?: TokenUsage): AgentEvent[];
+    /** 告警文案。status().justWarned* 为 true 时给宿主拿去展示 */
+    describeWarning(status: BudgetStatus): string;
+    /** 已用比例，取金额（两把尺子）和 token 三个维度里更紧张的那个 */
+    private usedRatio;
+    private warnThreshold;
+    private restore;
+    private persist;
 }
-/** 三张列表的总条数 */
-declare function countRules(lists: PermissionRuleLists | undefined): number;
-/**
- * 合并 ③④⑤∞ 四层文件设置到已加载的配置上。
- *
- * **会抛**：`opts.settingsPath` 指的文件不是合法 JSON 时抛 `SettingsFileError`
- * （方案 29 验收 #16，理由见 `finishLayer`）。其余任何一层坏了都不抛。
- *
- * @param base       `loadConfig()` 的产物（第 ①② 层）。**不会被修改**
- * @param projectRoot 项目根，取自 `resolveProjectRoot()` —— 必须和信任判定用的是
- *                    同一个答案，否则会出现「诊断说未信任、实际却加载了」
- * @param execTrusted 工作区授过**执行类**吗（`TrustDecision.exec`），取自
- *                    `decideTrust()`。本文件不自己判
- *
- * ## ⚠️ ③④ 两层**整份**归执行类，不按字段拆（2026-09-11）
- *
- * 拆档之后有一个看着更细的选法：`permissions.allow` 归执行类，`model` /
- * `maxTurns` 那两个标量跟着读类回来。**不这么做**，判据是这一层的 `gated`
- * 语义已经是「读到了、也解析了，但只有 deny 被采纳」——再按字段切一刀，
- * 这一层就有了三种半生不熟的状态，而设置页那条六层来源链要为每一格分别解释
- * 「这一格为什么在、隔壁那格为什么不在」。
- *
- * 代价如实写着：只授了读类的工作区，它 `.epoch/settings.json` 里的 `model`
- * 不生效 —— 和拆档之前「未信任」那一档的行为**逐字节相同**，不是新增的限制。
- */
-declare function resolveSettings(base: EpochConfig, projectRoot: string, execTrusted: boolean, opts?: ResolveSettingsOptions): SettingsResolution;
 
 /**
- * 「为什么是这个值」—— 一个配置键赢在哪一层，以及被压住的层各自写了什么。
- *
- * ```
- * ① 内置默认        schema 的 `.default()`              ┐
- * ② 用户级          ~/.epoch/config.yaml                ├ loader 那一相，合成 `base`
- * 环境变量          EPOCH_* / provider 的 API key 变量   ┘
- * ③ 项目级          <项目根>/.epoch/settings.json        ┐
- * ④ 项目本地        <项目根>/.epoch/settings.local.json  ├ resolveSettings 那一相
- * ⑤ 命令行          --settings <file>                    │
- * ∞ 企业托管        机器级 managed-settings.json         ┘
- * ```
- *
- * ## 为什么要单独一相，而不是让 `resolveSettings` 顺手交出来
+ * 计价 —— 把一次用量折算成钱。
  *
- * `resolveSettings` 拿到的 `base` 已经是 loader 合并完的产物 —— schema 默认值、
- * `config.yaml`、环境变量全拍在了一起。它分不出 ① 和 ②，而**分不出的代价是
- * 撒谎**：一个用户从没配过的键会被标成「② 用户级」，于是他去翻一个根本没写
- * 这一行的文件。所以 ①／② 那一刀由 loader 的 `getConfigOrigins()` 来切，
- * 本文件只负责把两相拼成一条链。
+ * 两个刻意的设计：
  *
- * ## 三条口径，写在这儿免得下一个人各猜一遍
+ * 1. **无定价数据返回 undefined，不返回 0**。0 的意思是「免费」，undefined 的
+ *    意思是「不知道」。闸门对这两者的处理完全不同：免费可以随便跑，不知道
+ *    要么告警放行、要么直接拦（见 budget-guard 的 onUnknownPricing）。
  *
- * 1. **链条只有六格，`plugin`（第 ①ᐟ⁵ 层）不在里面。** 那一层只认
- *    `permissions.deny`，标量键它一个都碰不到（判据在 `loadPluginLayer`）。
- *    摆一格永远是「—」的行，等于告诉用户「装个插件也许能换掉你的模型」。
- * 2. **不在白名单里的键压根不产出链条**（`chain: []`）。`SettingsFileSchema`
- *    只放行 `permissions` / `model` / `maxTurns`，别的键 ③④⑤∞ 碰不到 ——
- *    给它们画一条六层链条，就是在暗示「这一行也可能被项目级压回去」，
- *    而用户会照着这个暗示去 `.epoch/settings.json` 里写一个永远不生效的键。
- * 3. **`unknown` 是留给「分不出」的，不是给「没配过」的。** 没配过是
- *    `builtin`，那是个确切答案。`unknown` 只在「base 里的值和内置默认不一样、
- *    却没有任何一处记账说是谁写的」时出现 —— 今天它够不到（loader 把
- *    `config.yaml` 和每一个环境变量覆盖都记了账），留着是为了哪天多一条
- *    没记账的来路时，它显示成一个陌生的词，而不是被悄悄归到「② 用户级」。
- */
-
-/**
- * 一个配置键的值。
+ * 2. **内部一律用「微美元整数」累加**。金额是浮点数最容易出事的地方：
+ *    0.1 + 0.2 !== 0.3，几千轮累加下来会漂移到小数点后好几位都对不上。
+ *    micro-USD（1e-6 美元）对任何现实用量都是整数级精度，累加无损，
+ *    只在对外暴露时除回美元。
  *
- * 收数组是为了 `fallback.providers` 那一行（降级链是有序的一串 provider）——
- * **不在这里 join 成字符串**：分隔符是排版，两份 catalog 里未必一样，
- * 而服务端拼一次就等于把一个界面决定钉死在网线上。
- */
-type SettingValue = string | number | boolean | readonly string[];
-/**
- * 一个配置项的来源层。编号与叫法逐字照 [docs/SETTINGS.md](../../../../docs/SETTINGS.md)
- * 那张层表，**不另起一套** —— 用户在文档里读到的「③ 项目级」和界面上看到的
- * 必须是同一个词。
+ * ## 各字段的口径（方案 42 PR-0 之后是**真的**在用）
  *
- * `env` 不在那张层表里，因为它不是一个「设置层」：环境变量是在 loader 那一相
- * 覆盖 `config.yaml` 的，位置和用户级同一格（于是它**会被项目级压回去**，
- * 这条反直觉的事实正是这条链要说出来的东西之一）。
- */
-type SettingLayer = 'builtin' | 'user' | 'env' | 'project' | 'projectLocal' | 'cli' | 'managed' | 'unknown';
-/** 链条上的一格。这一层没写这个键时**整个不带 `value`** —— 界面画成「—」 */
-interface SettingStep {
-    layer: SettingLayer;
-    value?: SettingValue;
-}
-interface SettingChain {
-    /** 点分路径，与 `config.yaml` 里的写法逐字一致（`budget.maxCostUsd`） */
-    key: string;
-    /** 生效值。谁都没写、又没有内置默认时**整个不带这个键** */
-    value?: SettingValue;
-    /** 赢的那一层 */
-    layer: SettingLayer;
-    /** 六层链条，低 → 高。不在白名单里的键是**空数组**（判据见文件头第 2 条） */
-    chain: readonly SettingStep[];
-}
-/** loader 那一相里，一个键的值是谁写的 */
-type BaseOrigin = 'builtin' | 'user' | 'env';
+ * - `cacheHitTokens` / `cacheWriteTokens` 与 `inputTokens` **不重叠**，各自单独计价。
+ *   这条契约以前是空的 —— ProviderRouter 只上报 in/out 两个数，缓存字段恒为 0，
+ *   不是 provider 不给，是 `provider/types.ts` 把 usage 写死成两个字段截断了。
+ *   现在 `toTokenUsage()` 按同一个口径逐字段接了进来（`inputTokens` 取的是
+ *   SDK 的 `noCacheTokens`），所以 `computeCostMicros` 里那两行缓存乘法
+ *   从这版起是真在算钱，不再恒等于 0。
+ * - `reasoningTokens` **包含在** `outputTokens` 里，**不单独计价、也不加进总数** ——
+ *   加了就是把输出侧算两遍。
+ */
+
 /**
- * 一次 `loadConfig()` 里，哪些键是**用户自己写的**，以及写在哪儿。
+ * 折算一次用量的花费，单位微美元（整数）。
  *
- * 键是点分路径（`model` / `budget.maxCostUsd`），和 `config.yaml` 里的写法一致 ——
- * 界面上那一行的标题就是拿它当 catalog key 的后缀，两边对不上会显示成一个空格子。
+ * 无定价数据返回 undefined。每个维度各自取整：单价可能是 0.0028 这种
+ * 小数，逐维取整的误差上限是 0.5 微美元 / 维 / 次，且是确定性的，
+ * 累加一万次也不会像浮点那样越滚越偏。
  */
-interface ConfigOrigins {
-    /** `~/.epoch/config.yaml` 里真的出现过、而且**真的生效了**的键 */
-    readonly file: ReadonlySet<string>;
-    /** 被环境变量覆盖掉的键（`EPOCH_MODEL` / provider 的 API key 变量等） */
-    readonly env: ReadonlySet<string>;
-}
-/** 空账。用户级什么都没写时的形状，也是 loader 起不来时的诚实答案 */
-declare function noConfigOrigins(): ConfigOrigins;
+declare function computeCostMicros(usage: TokenUsage, pricing?: ModelPricing): number | undefined;
 /**
- * 这个键在 loader 那一相是谁写的。
- *
- * **环境变量优先于文件**，因为解析链就是这个顺序（loader 第 5 层压第 2 层）：
- * 两处都写了时生效的是环境变量，说成「② 用户级」会让用户去改一个改了也不管用
- * 的地方。
+ * 折算一次用量的花费，单位美元。无定价数据返回 undefined，**不是 0**。
  */
-declare function originOf(origins: ConfigOrigins, key: string): BaseOrigin;
-/** loader 那一相交出来的一格 */
-interface BaseSlot {
-    /** `loadConfig()` 产物里这个键的值 */
-    value?: SettingValue;
-    /** `defaultConfig()` 里这个键的值 —— ① 那一格 */
-    builtin?: SettingValue;
-    /** 谁写的，来自 {@link originOf} */
-    origin: BaseOrigin;
-}
-/** 白名单键才给得出的那一半：这个键在 `LayerScalars` 里叫什么、各层结果是什么 */
-interface FileSlots {
-    key: ScalarKey;
-    layers: readonly LayerOutcome[];
-}
+declare function computeCost(usage: TokenUsage, pricing?: ModelPricing): number | undefined;
+/** 微美元 → 美元 */
+declare function microsToUsd(micros: number): number;
+/** 美元 → 微美元（用于把用户配的 maxCostUsd 转进同一套整数体系） */
+declare function usdToMicros(usd: number): number;
 /**
- * 拼一条链。
+ * 金额的人类可读形式。
  *
- * @param key   点分路径，原样带进结果里（本函数不解析它，取值是调用方的事）
- * @param base  loader 那一相的结论
- * @param file  ③④⑤∞ 那一相。**不给 = 这个键不在白名单里**，于是 `chain` 是空数组
+ * 不到 1 分钱的时候 `$0.00` 等于没说，所以小额多给两位有效数字 ——
+ * 那条规则现在是 protocol 里 `formatMoney()` 的 `'adaptive'` 档，行为一字未改。
  *
- * 赢的那一层 = 链条上**最后一个写了值**的格子；一个都没写就是 ①（那时值要么是
- * 内置默认，要么这个键压根没有默认值 —— 后者的诚实答案仍然是「① 内置默认，
- * 而它是空的」，不是「不知道」）。
+ * ## ⚠️ 名字里的 `Usd` 说的是**入参**，不是输出
+ *
+ * 入参恒为美元（全仓的算术都是），而印出来的那一串跟着
+ * `display.currency` 走 —— 配了人民币就是 `¥6.10`。这两件事的分界全文在
+ * [protocol/src/money.ts](../../../protocol/src/money.ts) 文件头那张表。
+ *
+ * 名字**刻意没改成 `formatMoney`**：这个仓里 `Usd` 后缀的一贯含义就是
+ * 「这一格装的是美元」（`costUsd`、`maxCostUsd`、`microUsd`），而它的入参正是。
+ * 改名会让调用点看起来像是可以传别的币种进来 —— 那是这里最不想要的误解。
+ *
+ * @param digits 定死几位。缺省 `'adaptive'` = 这个函数的历史行为。
+ *   闸门那几句文案给的是 `4`（**不是**口味：那几句印的是单轮 / 累计成本，
+ *   常在 $0.003 这一档，两位会印成一个「免费」的假象）
  */
-declare function explainSetting(key: string, base: BaseSlot, file?: FileSlots): SettingChain;
-
+declare function formatUsd(usd: number, digits?: MoneyDigits): string;
 /**
- * 配置系统 — 10 层解析链 [Hermes config.py]。
+ * 累加两份用量（含缓存 / 思考 / 总数四个可选维度），返回新对象。
  *
- * 1. schema 默认值（[config/schema.ts](./schema.ts) 是**唯一**真源）
- * 2. config.yaml（zod 逐字段补默认值，等价于原来的 deep-merge）
- * 3. ${ENV_VAR} 模板展开（递归，最多 10 层）
- * 3.5 SecretStore（系统钥匙串，装配层预取后注入 —— 见 `readProviderKeyEnv`）
- * 4. .env 文件（secrets）
- * 5. process.env 直接覆盖（最高优先级）—— `EPOCH_PROVIDER` / `EPOCH_BASE_URL`
- *    这两个例外：它们**读一次、落两次**（第 3.5~4 层取 secrets 的前后各一次），
- *    理由见 `readProviderOverride` / `applyProviderOverride`
- * 6. 损坏回退（last-known-good → 默认值）
- * 7. 损坏备份（config.yaml.corrupt.<ts>.bak）
- * 8. 缓存（mtime + size + env_snapshot）
- * 9. 多 Profile（~/.epoch/profiles/<name>/）
- * 10. load() / loadReadonly() 双接口
+ * 可选维度加完仍是 0 就不写进结果 —— 保住「0 是真的零，undefined 是不知道」：
+ * 两轮都没缓存命中，累计里就不该冒出一个 `cacheHitTokens: 0` 让人以为
+ * 这个 provider 支持缓存只是没命中。
  *
- * 校验：全程 zod（`parseLenient`），**失败不抛异常**——单个配置文件写错不该让
- * agent 起不来（safeInit 语义）。代价是必须把 issues 交出去：`loadConfig(diags)`
- * 的可选参数，或事后 `getConfigIssues()`。静默吞掉等于没校验。
+ * ## ⚠️ `totalTokens` **不是**可加的维度，别照着上面三项写
  *
- * 模板展开在校验**之前**做：`maxTurns: ${MAX_TURNS}` 这种写法在展开前是字符串，
- * 先校验会把合法配置判成类型错误。[Gemini resolveEnvVarsInObject → validateSettings]
+ * 上面三项缺席当 0 加是对的（0 是加法的单位元）；`totalTokens` 不是，它是一个
+ * **总量**。`(a.totalTokens ?? 0) + (b.totalTokens ?? 0)` 在「一边报了、另一边
+ * 没报」时收到的只有报了的那一份，而 `inputTokens` / `outputTokens` 两侧是加全
+ * 了的 —— 于是这份累计**自相矛盾**：`totalTokens < promptTokens + outputTokens`。
+ *
+ * 这一档不是假想：`toTokenUsage` 明确放行了「两个总量都在、`totalTokens` 缺席」
+ * 的 usage（OpenAI 兼容端点不带 `stream_options` 的那一家就这样），而同一段会话
+ * 里换 provider（降级、或压缩那一发走别的模型）就会把两种 usage 加到一起。
+ *
+ * 症状有两层，**第二层不是显示问题**：
+ *
+ * 1. 屏幕上「共 X token」比旁边 `↑ + ↓` 还小（两处都读 `totalUsageTokens()`，
+ *    而它优先信 `totalTokens`）；
+ * 2. `budget.maxTokens` 那道闸门读的是同一个数（`budget-guard.ts` 的
+ *    `sessionBreach()`），偏小 = **上限拦不住**，多跑的那几轮是真花钱的。
+ *
+ * 所以没报的那一侧按我们自己的口径折算一份（`totalUsageTokens()` 的兜底那一支，
+ * 对那一侧来说是精确值），再相加。两边都没报时仍然整个不写 —— 那时
+ * `totalUsageTokens()` 自己算出来的和这里能算出来的是同一个数，凭空多一个字段
+ * 只会让「provider 报过」和「我们替它算的」变得分不出来。
  */
-
-/** 加载配置时的覆盖项 */
-interface LoadConfigOptions {
-    /**
-     * 家目录覆盖 —— 嵌入宿主用（Electron 的 `app.getPath('userData')`）。不给时
-     * （CLI / TUI 的常态）行为与改造前完全一致；给了就**压过**环境
-     * （`EPOCH_HOME` / `EPOCH_PROFILE`）和 yaml 里的 `homeDir` / `dbPath`：这个选项的
-     * 契约是「这个 runtime 实例的数据全落在这里」，让 yaml 能反过来改掉它就会出现
-     * 「嵌入方指定了目录、引擎却写回 `~/.epoch`」。`dbPath` 必须跟着一起换 ——
-     * SessionManager / MemoryManager / TrackerDB 都吃它，只改 homeDir 的话
-     * 两个实例照样共用同一个 SQLite 文件。
-     */
-    homeDir?: string;
-}
+declare function addUsage(a: TokenUsage, b: TokenUsage): TokenUsage;
 /**
- * 完整加载（深拷贝），适合 CLI 入口。
+ * 估算一张图片占多少 input token。
  *
- * @param diags 传进来就把校验问题按「一个问题一行」追加进去（宿主的启动诊断）。
- *              不传也不会静默：问题存在 `getConfigIssues()` 里。
+ * **为什么需要它**：`usage` 事件里的数字是 provider 上报的，本来就含图片 token，
+ * 那部分不缺。缺的是**发请求之前**的估算 —— 预算闸门的检查点在请求发出前
+ * （见 loop.ts 的注释），而 `estimateTokens()` 只按字符数算，压根看不见图片。
+ * 于是「点一下截图，钱没了」这件事只能事后才发现。
+ *
+ * 用 OpenAI 的公式当统一口径：epoch-agent 的 provider 全是 OpenAI 兼容协议
+ * （见 config/schema.ts），各家实际切法有出入，但这是个**估算**，量级对得上
+ * 就够预算闸门用。宽高读不出来时返回 undefined —— **不是 0**。
+ * 0 意味着「免费」，undefined 意味着「不知道」，闸门对这两者的处理必须不同
+ * （与 `TokenUsage.costUsd` 同一条约定）。
  */
-declare function loadConfig(diags?: DiagnosticSink, opts?: LoadConfigOptions): EpochConfig;
-/** 最近一次加载的校验问题（带字段路径），空数组表示配置全合法 */
-declare function getConfigIssues(): ParseIssue[];
+declare function estimateImageTokens(width?: number, height?: number): number | undefined;
 /**
- * 最近一次加载里，**哪些键是用户自己写的**（方案 43 §七的来源标注）。
- *
- * ## 这个函数存在的理由只有一句话
+ * 用量里计入预算的 token 总数。
  *
- * `loadConfig()` 交出来的那份配置已经把 ①（schema 默认值）、②（`config.yaml`）
- * 和环境变量拍在了一起，分不出来。而设置页每一行都要挂来源层徽标 ——
- * 分不出的话，一个用户从没配过的键会被标成「② 用户级」，于是他去翻一个根本
- * 没写这一行的文件。**那是这一屏最不该出的一句假话**（判据全文在
- * [provenance.ts](./provenance.ts) 的文件头）。
+ * 实现住在 protocol（`totalUsageTokens`）—— TUI 的 ctx% 要用同一套口径，
+ * 而 tui 不许 import core。这里保留这个名字只是为了不惊动 core 里既有的调用点。
+ */
+declare function totalTokens(usage: TokenUsage): number;
+
+/**
+ * 进程级的展示币种（2026-09-13）。
  *
- * ## 两条口径
+ * ## 为什么是模块级插槽，而不是逐处穿参
  *
- * - **`file` 记的是「真的生效了」，不是「文件里写了」。** 整份 zod 校验失败时
- *   loader 是**整体退回默认值**（见 `parseRawConfig` 的注释），那时用户写的一个键
- *   都没生效，所以 `file` 是空集 —— 不是空集的话，设置页会把一屏默认值挨个标成
- *   「② 用户级」。未知键同理不记：它们被 `z.object()` 丢掉了。
- * - **`LoadConfigOptions.homeDir` 覆盖掉的 `homeDir` / `dbPath` 不记账。**
- *   那是嵌入宿主在装配期定的，既不是 ① 也不是 ②，而这两个键设置页不显示。
- *   哪天要显示了，它需要的是自己的一档（「宿主」），不是硬塞进现有的三档。
+ * 判据逐条借 infra 的 `setLang()`，在这儿是原样成立的：金额的格式化点散在
+ * core / runtime / cli / tui / web **五个包十几处**，而币种对它们中的每一个都是
+ * **同一个进程级的一次性决定** —— 一个进程不会一半印美元一半印人民币。
+ * 逐处穿参等于把一个显示偏好变成一次全仓签名改造，而 infra 里 `setLogLevel` /
+ * `setShell` / `setSecretStore` 早就是这个形态。
  *
- * 配置损坏退到 last-known-good 时，交出来的是**那一份的账**，不是空账 ——
- * 生效的配置是它，账也该是它的。
- */
-declare function getConfigOrigins(): ConfigOrigins;
-/**
- * provider 凭据的统一查找视图：`process.env` 优先于 `~/.epoch/.env`。
+ * ## ⚠️ 它住在 core，不是 infra —— 因为 `CurrencyDisplay` 住在 protocol
  *
- * 导出它是因为**判据必须只有一份**：loader 用它解析配置，`ProviderRouter` 用它
- * 找 fallback 的 key，CLI 用它判断「凭据是否已配置」。改造前这三处各有一套
- * （loader 认三个变量、router 只读 process.env、CLI 对 .env 做 `/API_KEY/`
- * 正则），结果 `epoch status` 说「凭证 ✓」而引擎报「无可用凭证」。
+ * infra 是**零内部依赖包**（`check-layers.mjs` 的 `ALLOWED` 里它的内部依赖是空的），
+ * import 不了 protocol，而这个插槽装的正是一个 protocol 类型。放 infra 就得在
+ * infra 里再声明一遍那个形状 —— 那是 `LANGS` 在两边各写一份的老问题，而那一份
+ * 有一条「两边行为逐项相等」的门禁兜着，这一份不值得再开一条。
  *
- * 只收 protocol 清单里的变量名，不把整个 .env 灌进来 —— 那个文件里还可能有
- * 用户自己的东西，没必要进这个视图。
+ * 代价是 **tui 够不着**（它不许 import core）。那一侧走宿主注入，形状和它那份
+ * `t()` 逐字一样 —— 判据在 [tui/src/money.ts](../../../tui/src/money.ts)。
  *
- * ## 三层的优先级
+ * ## 没设过的时候：`undefined` = 美元
  *
- * `process.env` > `.env` 文件 > SecretStore 预取值（第 3.5 层）。
+ * 这不是兜底的敷衍，它是**默认路径本身**：绝大多数用户没配 `display.currency`，
+ * 而 `formatMoney()` 在 `currency` 缺席时的输出与 2026-09-13 之前逐字节相同
+ * （判据在 protocol 的 `money.ts` 文件头最后一节）。
  *
- * - **`process.env` 保持最高是硬要求**：CI、Docker、
- *   `OPENAI_API_KEY=xxx epoch run ...` 这些用法一个都不能坏，
- *   headless 的整套非交互流程也建立在环境变量上。
- * - **`.env` 压在钥匙串之上**：它是迁移期的兼容层，也是
- *   `epoch config secret --export` 的落点 —— 用户主动倒出来的那份如果压不过
- *   钥匙串里的旧值，这个逃生口就没有意义了。
+ * ⚠️ 所以这里**不给一个 `{code:'USD', rate:1}` 的默认值**。给了的话「没配过」和
+ * 「配了美元」在下游就分不出来了，而 `WireConfigResponse.currency` 那一格的语义
+ * 恰恰是「没配就没有这个键」。
  */
-declare function readProviderKeyEnv(homeDir?: string): Record<string, string>;
+
 /**
- * 是否已配置任一 provider 的凭据。
+ * 钉住这个进程的展示币种。装配层读完配置后调一次。
  *
- * 三个来源都要算上：`process.env`、`.env` 文件、**系统钥匙串**。
+ * **生产路径上只有 `cli/src/language.ts` 的 `applyConfiguredCurrency()` 调它**，
+ * 和 `setLang()` 在同两个入口、同一个位置 —— 理由也一样：它必须跑在**任何一句
+ * 带金额的文案之前**，而最早那几句是启动诊断里的预算行（`boot.budget_cost`）。
  *
- * 最后一个是踩出来的：这个函数是同步的，而钥匙串是异步的，所以它只看
- * `listStoredSecretNames()` 读出来的**名字**（纯文件读，不起子进程）。
- * 不算这一层的话，迁移完成之后 `epoch status` 会打「凭证: 未配置」、
- * 欢迎语会引导用户再去 `epoch model` 配一遍 —— 三把 key 明明好好地在钥匙串里。
+ * 传 `undefined` 可以把它清回美元 —— 用例需要这条（进程是复用的，
+ * 一个用例设过币种之后不还原，下一个用例会莫名其妙拿到人民币）。
+ */
+declare function setDisplayCurrency(next: CurrencyDisplay | undefined): void;
+/**
+ * 当前展示币种，没设过就是 `undefined`（= 美元）。
  *
- * 名字是提示不是真源（值可能读不出来），但这个函数要回答的正是
- * 「要不要提示用户去配 key」，名字这一层足够。
+ * ⚠️ **现读，别存成模块级常量。** 常量在 `setDisplayCurrency()` 之前就求值完了，
+ * 币种会被永久钉在「没设过」那一档 —— 同 tui 那份 `t()` 文件头「别在模块级调
+ * `t()`」那条，失败形态一模一样：不报错，只是永远印美元。
  */
-declare function hasProviderCredentials(homeDir?: string): boolean;
+declare function displayCurrency(): CurrencyDisplay | undefined;
 
 /**
  * EpochConfig 的 zod schema —— **默认值的单一真源**。
@@ -12120,8 +12435,14 @@ declare function hasProviderCredentials(homeDir?: string): boolean;
  */
 declare const DEFAULT_COMPRESSION_THRESHOLD = 0.8;
 declare const EpochConfigSchema: z.ZodObject<{
-    provider: z.ZodPrefault<z.ZodObject<{
-        type: z.ZodDefault<z.ZodEnum<{
+    model: z.ZodOptional<z.ZodString>;
+    models: z.ZodOptional<z.ZodObject<{
+        utility: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    modelEntries: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        provider: z.ZodEnum<{
             openai: "openai";
             anthropic: "anthropic";
             google: "google";
@@ -12141,18 +12462,41 @@ declare const EpochConfigSchema: z.ZodObject<{
             togetherai: "togetherai";
             ollama: "ollama";
             "openai-compatible": "openai-compatible";
+        }>;
+        protocol: z.ZodOptional<z.ZodEnum<{
+            "openai-chat": "openai-chat";
+            "anthropic-messages": "anthropic-messages";
         }>>;
-        apiKey: z.ZodDefault<z.ZodString>;
-        credentials: z.ZodDefault<z.ZodArray<z.ZodObject<{
-            apiKey: z.ZodString;
-            model: z.ZodOptional<z.ZodString>;
-        }, z.core.$strip>>>;
-        baseUrl: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>>;
-    model: z.ZodDefault<z.ZodString>;
-    models: z.ZodOptional<z.ZodObject<{
-        utility: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>>;
+        baseUrl: z.ZodOptional<z.ZodURL>;
+        rawUrl: z.ZodOptional<z.ZodBoolean>;
+        model: z.ZodString;
+        capabilities: z.ZodOptional<z.ZodObject<{
+            tools: z.ZodOptional<z.ZodBoolean>;
+            images: z.ZodOptional<z.ZodBoolean>;
+            reasoning: z.ZodOptional<z.ZodBoolean>;
+            reasoningOnly: z.ZodOptional<z.ZodBoolean>;
+            reasoningToggle: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        reasoning: z.ZodOptional<z.ZodObject<{
+            levels: z.ZodArray<z.ZodEnum<{
+                max: "max";
+                low: "low";
+                medium: "medium";
+                high: "high";
+                xhigh: "xhigh";
+            }>>;
+            default: z.ZodOptional<z.ZodEnum<{
+                max: "max";
+                low: "low";
+                medium: "medium";
+                high: "high";
+                xhigh: "xhigh";
+            }>>;
+        }, z.core.$strip>>;
+        contextLength: z.ZodOptional<z.ZodInt>;
+        maxOutputTokens: z.ZodOptional<z.ZodInt>;
+        host: z.ZodOptional<z.ZodLiteral<true>>;
+    }, z.core.$strip>>>;
     shell: z.ZodOptional<z.ZodEnum<{
         cmd: "cmd";
         powershell: "powershell";
@@ -12188,27 +12532,6 @@ declare const EpochConfigSchema: z.ZodObject<{
         maxBackoffMs: z.ZodDefault<z.ZodInt>;
     }, z.core.$strip>>;
     fallback: z.ZodOptional<z.ZodObject<{
-        providers: z.ZodDefault<z.ZodArray<z.ZodEnum<{
-            openai: "openai";
-            anthropic: "anthropic";
-            google: "google";
-            deepseek: "deepseek";
-            groq: "groq";
-            mistral: "mistral";
-            moonshotai: "moonshotai";
-            zhipu: "zhipu";
-            dashscope: "dashscope";
-            bytedance: "bytedance";
-            qianfan: "qianfan";
-            cohere: "cohere";
-            xai: "xai";
-            perplexity: "perplexity";
-            "amazon-bedrock": "amazon-bedrock";
-            azure: "azure";
-            togetherai: "togetherai";
-            ollama: "ollama";
-            "openai-compatible": "openai-compatible";
-        }>>>;
         model: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     hooks: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
@@ -12340,13 +12663,15 @@ declare const EpochConfigSchema: z.ZodObject<{
         hide: "hide";
         show: "show";
     }>>;
+    brandMenuId: z.ZodOptional<z.ZodString>;
     sidebarMenu: z.ZodOptional<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         label: z.ZodString;
         icon: z.ZodOptional<z.ZodString>;
         primary: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>>;
-    userMenu: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    userMenuHost: z.ZodOptional<z.ZodBoolean>;
+    sidebarHeadMenu: z.ZodOptional<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         label: z.ZodString;
         icon: z.ZodOptional<z.ZodString>;
@@ -12504,7 +12829,8 @@ interface ConfigMigration {
  * `permissions` 在第一张名单里、**两张都不该给它写控件**：三张列表走并集不走
  * 覆盖，「加一条规则」和「把一个值改成另一个值」是两种动作、两种界面、两种确认，
  * 而它的来源标注早就在安全中心那一屏上了（`PermissionsControl.rules()`）。
- * `fallback.providers` 同理 —— 它是一条**有序的链**，不是一个标量。
+ * 2.0.0 之前这里还有第二个例子（`fallback.providers` 那条有序的降级链），随老写法
+ * 删了 —— 判据本身照旧：凡是「加一项 / 删一项」形状的值都不给铅笔。
  *
  * 那个「只写 ② 用户级就要能改任意键、得先回答 provider 段里的 key 怎么办」的
  * 顾虑，答案就是**这张名单本身**：可写的键是列举出来的，`provider` 那一段
@@ -12590,17 +12916,16 @@ declare function isSettingWriteLayer(value: string): value is SettingWriteLayer;
  * ## 收进来的判据：**它是不是一个标量旋钮**
  *
  * 「改一个值」这条路上能画出来的只有一个输入框加一次保存。于是收的是标量、
- * 拒的是别的形状 —— 两个被拒的都不是遗漏：
+ * 拒的是别的形状 —— 被拒的不是遗漏：
  *
  * - **`permissions`** 是三张列表、走并集不走覆盖，入口在安全中心（文件头第二节）
- * - **`fallback.providers`** 是一条**有序的链**。「往链尾加一家」和「把整条链换成
- *   另一条」是两种动作，而一个输入框只画得出后者 —— 用户敲错一个字就把降级
- *   整条清空了，而这个键存在的理由正是「主 provider 挂了还有下家」。
- *   它照旧在设置页上**读**得到（`fallback.providers` 那一行印着整条链），
- *   只是没有铅笔
+ * - **`provider` 那一段**（含 `apiKey`）**一个字段都不在这儿**，这就是文件头第二节
+ *   那个「provider 段里的 key 怎么办」的答案：可写的键是列举出来的
  *
- * `provider` 那一段（含 `apiKey`）**一个字段都不在这儿**，这就是文件头第二节
- * 那个「provider 段里的 key 怎么办」的答案：可写的键是列举出来的。
+ * 2.0.0 之前这一串里还有一条 `fallback.providers`（一条**有序的链** ——「往链尾
+ * 加一家」和「把整条链换成另一条」是两种动作，一个输入框只画得出后者），随老写法
+ * 删了。**「加一项 / 删一项」形状的值一律不收**这条判据没变，只是今天名单里
+ * 没有这样的键可举 —— 真加进来那天，照上面那句判它。
  *
  * ⚠️ 加键要**同时**回答两件事，缺一件别加：这个键写进用户级 yaml 之后，
  * 用户在界面上看到的会不会是真的；以及它的值域从哪儿摘（{@link VALUE_SCHEMA}，
@@ -12877,6 +13202,25 @@ declare function settingValueChoices(key: string): readonly string[] | null;
  * 警告按下去的决定 —— 把用户级的默认值钉住、由项目本地临时压着，是一件正常事。
  */
 declare function writeSettingValue(req: SettingWriteRequest): SettingWriteOutcome;
+/**
+ * 能从 ② 用户级里**删掉**的键（2026-10-15）。只有这两个，而且只在用户级。
+ *
+ * 文件头第三节说「这一轮没有删键」，理由是删键「在界面上要另一个控件和另一句确认」。
+ * 「我的模型」那一屏上副模型 / 降级模型的下拉里那一项「跟随主模型」**就是那个控件**：
+ * 它的语义正是「这一格不配，回到下一层是什么就是什么」，而把它做成「设成主模型那一条」
+ * 是另一件事 —— 用户之后换了主模型，副模型不会跟着换。
+ *
+ * 只开这两个是因为别的键没有这个控件；开成通用的就又回到了文件头那个问题。
+ */
+declare const UNSETTABLE_USER_KEYS: readonly ["models.utility", "fallback.model"];
+type UnsettableUserKey = (typeof UNSETTABLE_USER_KEYS)[number];
+/**
+ * 从 ② 用户级里删掉一个键。手术 + 回读同 {@link writeUserYaml}：删完要能解析、
+ * 目标字段确实不在了、**别的东西一个都没动**，有一条对不上就整个不写。
+ *
+ * 那个键本来就不在时是一次空操作（成功）—— 「跟随主模型」点两下不该报错。
+ */
+declare function unsetUserSetting(path: string, key: UnsettableUserKey): SettingWriteOutcome;
 
 /**
  * 设置文件的 JSON Schema 导出（方案 22 §2.7.5）。
@@ -21276,4 +21620,4 @@ declare function resolveCodeModeWorker(baseDir: string, exists?: typeof existsSy
  */
 declare function codeModeWorkerPath(): string | undefined;
 
-export { ABOUT_DESC_MAX_CHARS, ABOUT_README_MAX_CHARS, AGENT_ROLE_DIAG_MODULE, ARTIFACT_MAX_TOTAL_BYTES, ARTIFACT_RETENTION_DEFAULTS, ATTACHMENT_MAX_TOTAL_BYTES, ATTACHMENT_RETENTION_DEFAULTS, type AcquireResult, type AgentConfig, AgentLoop, type AgentProvider, type AgentSite, type AgentSiteRef, AppearanceStore, type AppendMessageInput, ApprovalCache, type ApprovalDecision, type ArtifactOpenRefusal, type ArtifactRetention, type AskQuestionDeps, type AttachmentRetention, BLOCKED_TOOLS, type BackendOptions, type BackendOutcome, type BackgroundTaskSource, type BaseOrigin, type BaseSlot, type BeginTurnInput, type BreakdownInput, BudgetGuard, type BudgetGuardOptions, type BudgetInfo, type BudgetLevel, type BudgetOptions, type BudgetStatus, BudgetStore, type BudgetStoreOptions, type BuildFireArgvInput, type BuildIndexOptions, CHECKPOINT_MAX_TOTAL_BYTES, CLAUDE_EVENT_NAMES, CLAUDE_TOOL_NAMES, CODE_MODE_LIMITS, CODE_MODE_SDK_TAG, CONFIG_KEYS, CURRENT_CONFIG_VERSION, type CachedApproval, type CachedDecision, type CheckpointCapture, type CheckpointFile, CheckpointManager, type CheckpointManagerOptions, type CheckpointManifest, CheckpointStore, type CheckpointStoreOptions, type CheckpointSummary, type ClaudeHooksParseOptions, type CodeModeLimits, type CodeRequest, type CodeResult, CodeSandbox, type CommandHookConfig, type CommandHookResult, type CommandLoadOutcome, type CommandLoadSummary, type CommandResult, type CommandRunner, type CompactionResult, type CompiledRules, type ComplianceDirSpec, type ComplianceDirsSummary, ComplianceEngine, type ComplianceEngineInput, type ComplianceGate, type ComplianceHit, type ComplianceRule, type ComplianceRuleSource, type ComplianceSettings, type ComplianceVerdict, type CompressConfig, type CompressResult, type ConfigMigration, type ConfigOrigins, ContextCompressor, type ContextEngine, type CreateScheduleInput, type CreateSessionInput, DEFAULT_COMPLIANCE_ACTIONS, DEFAULT_COMPLIANCE_SETTINGS, DEFAULT_COMPRESSION_THRESHOLD, DEFAULT_GOAL_MAX_ROUNDS, DEFAULT_MAX_HOLD_CHARS, type DelegateArgs, type DelegateConfig, DelegateManager, type DelegateTaskResult, type DiagnoseOptions, type DiscoverOutcome, type DiscoveredFile, type DoctorReport, type DraftParse, EMPTY_RULES, EPOCH_DISK_LEDGER, EpochConfigSchema, type ExpandOptions, type ExtractOutcome, FTS_TABLES, FTS_TRIGGERS, type FallbackEvent, type FileSlots, type FileSourceKind, type ForkInput, type FrontmatterParse, type FrontmatterSplit, type FtsHealth, type FtsReclaim, type FtsSpace, type FtsTableHealth, GOAL_BLOCK_CODES, type GateAxis, type GateVerdict, type GenerateInput, type GenerateOutput, type Goal, type GoalBlockReason, type GoalClear, type GoalPhase, type GoalPromptView, type GoalRefusal, type GoalRoundResult, GoalService, GoalStore, type GoalToolDeps, type GoalWrite, HEADLESS_AUDIT_CODES, type HeadlessPolicy, type HookConfigEntry, HookManager, type HookManagerOptions, type HookMatcher, type HookSourceKind, type HookSourceStatus, type HookSourcesOptions, type HookSourcesSummary, type HooksParseOutcome, type MemoryManager$1 as IMemoryManager, INSTRUCTION_BUDGET_CHARS, INSTRUCTION_FILES, type SessionManager$1 as ISessionManager, type SkillSystem$1 as ISkillSystem, ImageLoadError, type ImageSize, type ImportDecision, type ImportGate, type ImportGoal, type ImportMessage, type ImportNode, type ImportPartsResult, type ImportSessionInput, type ImportSessionMeta, type ImportSessionResult, type ImportSkipReason, type ImportTodo, ImportTrustStore, type InstallDependency, type InstallOptions, type InstallOutcome, type InstallPreview, type InstallStep, type InstructionScan, type InstructionSource, type IsolationReason, type IsolationReport, type JsonSchemaDocument, LAUNCHD_LABEL_PREFIX, LOCK_HEARTBEAT_MS, LOCK_STALE_MS, type LastOpenSession, LastOpenSessions, type LayerOutcome, type LayerScalars, type LayerStatus, type LearningContext, type LearningResult, type LearningSkipReason, type LexiconLoadOutcome, type LifecycleOutcome, type ListCandidatesInput, type ListSessionsInput, type ListSessionsOutput, type LoadCommandsOptions, type LoadConfigOptions, type LoadKeybindingsOptions, type LoadKeybindingsResult, type LoadRolesOptions, type LoadedPlugin, type LockHolder, MARKETPLACE_DISPLAY_FIELDS, MARKETPLACE_FILE, MAX_AUDIT_ENTRIES, MAX_COMMAND_DEPTH, MAX_GOAL_MAX_ROUNDS, MAX_IMPORT_DEPTH, MAX_LAST_OPEN_SESSIONS, MAX_OBJECTIVE_CHARS, MAX_REASON_CHARS, MAX_RECENT_WORKSPACES, MODEL_GIVE_UP_THRESHOLD, MULTIMODAL_DEFAULTS, type ManagedPolicy, ManagedPolicyError, type ManagedSettings, ManagedSettingsSchema, type MarketplaceCatalog, type MarketplaceCategory, type MarketplaceDisplay, type MarketplaceDisplayField, type MarketplaceEntry, type MarketplaceOutcome, type MarketplaceRecord, type MarketplaceStatus, type MemoryConfig, type MemoryEntry, type MemoryImportRecord, type MemoryImportResult, MemoryManager, type MemoryManagerOptions, type MemoryNotice, type MemoryRemoval, type MemorySearchResult, type MemoryTarget, type MemoryWriteResult, type MentionPart, type MentionResolution, type Message, type MessageHit, type MessageRecord, type MessageSurface, type ModelCapability, ModelFailureTracker, type ModelMetaEntry, type ModelPricing, type MultimodalPolicy, NOMINAL_TOTAL_BYTES, NO_REVEALED_TOOLS, type NonInteractiveProbe, type OsTaskSnapshot, type OutputGuard, PACK_EXCLUDES, PACK_MAX_BYTES, PACK_MAX_FILES, PERMISSION_AUDIT_CODES, PLUGIN_ICON_MAX_BYTES, PLUGIN_LAYOUT, PLUGIN_MANIFEST_FILE, PLUGIN_MANIFEST_KEYS, PLUGIN_NAME_PATTERN, PLUGIN_ROOT_ENV, PLUGIN_ROOT_TOKEN, PLUGIN_VISIBILITY, POLICY_DECISIONS, PROBE_VERSION, PROJECT_AGENTS_SUBDIR, PROVIDER_NO_CREDENTIAL, type PackFile, type PackLimits, type PackOutcome, type PackPlan, type PackPlanOutcome, type PermissionAuditCode, type PermissionAuditEntry, type PermissionAuditOutcome, type PermissionAuditScope, type PermissionAuditSnapshot, PermissionManager, type PersistFailureKind, type PersistedBudget, type PersistedPart, type PlanApprovalFn, type PlanEnterResult, type PlanModeDeps, PlanModeState, type PlanSettlement, type PluginAbout, type PluginArtifacts, type PluginAuthor, PluginAuthorSchema, type PluginCommandDir, type PluginCounts, type PluginDoc, type PluginHookFile, type PluginInventory, type PluginLoadOptions, type PluginManifest, type PluginPathRef, type PluginRecord, type PluginSettingsFile, type PluginSourceType, type PluginStateReadOutcome, PluginStore, type PluginVisibility, type PolicyDirSpec, type PolicyDirsSummary, type PolicyLoadOutcome, type PolicyRule, PolicyRuleSchema, type PricingAt, type PricingOverride, type ProjectContext, type ProjectExtensionInventory, ProviderError, ProviderRouter, type ProviderStreamChunk, type ProviderToolCall$1 as ProviderToolCall, type ProviderWarning, type PruneResult, type QuestionAskFn, RECORDING_KEEP_RUNS, RECORDING_MAX_BYTES, ROLE_FRONTMATTER_SCHEMA, RUN_CODE_TOOL, type ReadMessagesInput, type ReadMessagesOutput, type RecentWorkspace, RecentWorkspaces, type RecordRunInput, type RecorderOptions, type RecoveryAction, type RegisterInput, type RegisterOutcome, type RegistrarOptions, type RegistrationPatch, type RepairOutcome, type ResolveMentionsOptions, type ResolveReferenceInput, type ResolveSettingsOptions, type ResolvedCompression, type ResolvedReference, type ResolvedSource, type ResponseFormat, type RestorePartsOptions, type RewindAction, type RewindDrift, type RewindFilePlan, type RewindOptions, type RewindOutcome, type RewindPreview, type RoleCreateFailure, type RoleCreateInput, type RoleCreateOptions, type RoleCreateOutcome, type RoleLoadOutcome, type RoleLoadSummary, type RoleMergeNotice, type RoleMergeResult, type RoleRemoveFailure, type RoleRemoveOptions, type RoleRemoveOutcome, type RoleScope, type RuleMatch, type RuleSuggestion, type RuleVerdict, type RunCodeFailure, type RunCodeInput, type RunCodeOutcome, type RunCodeToolDeps, type RunEstimateInput, type RunInput, type RunResult, type RunningSchedule, SANDBOX_COVERS, SANDBOX_EXCLUDES, SCALAR_KEYS, SCHEDULE_DEFAULTS, SCHEDULE_DEFAULT_ALLOWLIST, SCHEDULE_FORM_BUDGET_USD, SCHEDULE_ISSUE_CODES, SCHTASKS_FOLDER, SESSION_MESSAGES_READ_TOOL, SESSION_MESSAGES_SEARCH_TOOL, SESSION_QUERY_TOOLS, SESSION_SEARCH_TOOL, SESSION_TRACE_TOOL, SETTINGS_LAYER_ORDER, SETTING_WRITE_KEYS, SETTING_WRITE_LAYERS, SKILL_ASSET_DIRS, SKILL_CREATE_TOOL, SKILL_EDIT_TOOL, SKILL_FILE, SKILL_PATCH_TOOL, SKILL_VIEW_TOOL, SKILL_WRITE_FILE_TOOL, SLASH_COMMANDS_DIAG_MODULE, type ScalarKey, type ScanInstructionsOptions, type ScheduleArgvRefusal, type ScheduleArgvResult, type ScheduleArgvWarning, type ScheduleBackend, type ScheduleCliEntry, type ScheduleDraftDeps, type ScheduleDrift, type ScheduleDriftKind, type ScheduleImportInput, type ScheduleInstallForm, type ScheduleIssue, type ScheduleIssueCode, type ScheduleLock, ScheduleRecorder, ScheduleRegistrar, ScheduleStore, type ScheduleValidation, type SchemaExport, type SearchHit, type SearchInput, type SearchMessagesInput, type SearchMessagesOutput, type SearchOutput, type SearchSessionsInput, type SelectionDeps, type SelfConnector, type SelfIndexInput, type SelfSettings, type Session, type SessionCandidate, type SessionHit, SessionManager, type SessionMentionDeps, type SessionMeta, SessionQueries, SessionReferences, type SessionSearchDeps, type SessionStats, type SessionSurface, type SessionTrace, type SessionVisibility, type SessionVisibilityInput, type SettingApply, type SettingApplyFacts, type SettingChain, type SettingFutile, type SettingLayer, type SettingStep, type SettingValue, type SettingValueKind, type SettingWriteFailure, type SettingWriteKey, type SettingWriteLayer, type SettingWriteOutcome, type SettingWriteRequest, type SettingWriteTarget, type SettingWriteTargetsOptions, type SettingsFile, SettingsFileError, SettingsFileSchema, type SettingsLayer, type SettingsResolution, type ShadowFinding, type ShadowKind, type Skill, type SkillDirSource, type SkillDirSpec, type SkillDirsSummary, type SkillImportConflict, type SkillImportDone, type SkillImportEntry, type SkillImportFailure, type SkillImportForm, type SkillImportOptions, type SkillImportPreview, type SkillImportResult, type SkillIndexEntry, type SkillIndexOptions, type SkillIndexResidency, type SkillIndexStats, SkillLearner, type SkillLearningProvider, type SkillMeta, type SkillStats, SkillSystem, type SkillSystemOptions, type SkillViewDeps, type SkillWriteDeps, type SteerSource, type StoredAppearance, type SubAgentRunner, type SubTask, type SubToolCaller, type SummarizeOutput, type SurfaceMessage, type SystemPromptParams, type SystemPromptSegments, TOOL_SEARCH_TOOL, TaskNoticeTracker, type TodoItem, type ToolCall, type ToolConflict, type ToolGate, type ToolNameFidelity, type ToolNameLookup, ToolRegistry, type ToolRevealState, type ToolScope, type ToolSearchDeps, type ToolTableCost, type TraceInput, type TraceNode, TrackerDB, type TrustDecision, type TrustGate, type TrustGateOptions, TrustManager, type TurnRecord, type TurnTiming, type UpdateScheduleInput, type UtilityModelInfo, type ValidateScheduleInput, type VersionCheck, Workspace, type WorkspaceFiles, type WorkspaceIssue, type WorkspaceIssueKind, acquireScheduleLock, addMarketplace, addUsage, admitArtifact, admitArtifacts, affectedPaths, approvalEntryFor, approvalRootFor, artifactLaunchArgv, artifactOpenRefusal, assertLevelAllowed, blockedRoleTools, buildContextBreakdown, buildFireArgv, buildFtsMatchQuery, buildSchemaExports, buildSystemPrompt, buildTrigramMatchQuery, builtinRoles, checkEpochVersion, checkFtsHealth, checkShadowing, classifyPersistFailure, classifyProviderError, clearModelCache, coalesceRecording, codeModeWorkerPath, commandNameFromRelPath, compileRuleLists, compressionOptions, computeCost, computeCostMicros, computeExecHash, countRules, createAllowAllGate, createAllowAllImportGate, createAskQuestionTool, createCodeExecTool, createDelegateTool, createDenyAllGate, createDenyAllImportGate, createGoalTool, createImportGate, createMemoryTool, createPlanModeTools, createRoleFile, createRoleScope, createRunCodeTool, createScheduleDraftTool, createSessionMessagesReadTool, createSessionMessagesSearchTool, createSessionSearchTool, createSessionSearchTools, createSessionTraceTool, createSkillViewTool, createSkillWriteTools, createTodoTool, createToolRevealState, createToolScope, createToolSearchTool, createTrustGate, currentEpochVersion, decideImport, decideTrust, defaultConfig, defaultModelOf, describeArtifactRefusal, describeBackgroundTask, describeHeadlessPolicy, describeIsolation, describeJsonError, diagnoseSchedules, discoverMarkdown, discoverModels, discoverProject, displayAllows, displayCurrency, draftCommandLine, draftWidening, escapeRuleContent, estimateImageTokens, estimateRunTokens, estimateTokens, evaluateSelection, expandCommand, expandImports, explainSetting, extractArchive, findInstructionFiles, findProjectInstructions, findRole, formatBytes, formatSkillIndex, formatUsd, gateForTool, getCapability, getConfigIssues, getConfigOrigins, getImportGate, getTrustGate, grantedPathsFor, hasDedicatedExecContent, hasExecTierContent, hasPromptCaching, hasProviderCredentials, hasReadTierContent, imageFromBase64, imageFromPath, imagePartTokens, importParts, importSkills, installPlugin, instructionDirs, instructionNotices, intervalSlots, inventoryProjectExtensions, inventoryTotal, isBlockCode, isCodeModeDeferred, isEmptyRules, isGoalPhase, isNonInteractive, isReadOnlySubCall, isSettingWriteLayer, isTransientPersistFailure, isValidInterval, isValidPluginName, isWithinWindow, isWritableSettingKey, labelSlug, layerRank, listRunningSchedules, listSessionCandidates, listWorkspaceFiles, loadCommandDefinitions, loadCommandFile, loadCommands, loadConfig, loadHookSources, loadKeybindings, loadLexiconDir, loadLexiconFiles, loadPlugins, loadPolicyFiles, loadPolicyRules, loadRoleDefinitions, loadRoleDir, loadedImports, localDateString, managedSwitchNotes, mapClaudeToolName, mapEpochToolName, mapOperationType, matchPreauthorization, matchRuleLists, matchesHook, mentionsPluginRoot, mergeHeadlessPolicy, mergeRoles, mergeSchedulePatch, microsToUsd, modelListCandidates, needsAllowlist, nextFallbackModel, nextRunAt, noConfigOrigins, noManagedPolicy, noPlugins, normalizeTrigger, openArtifact, originOf, packFileName, packPlugin, parseClaudeSettingsHooks, parseClock, parseDate, parseFrontmatter, parseHooksConfig, parseHooksConfigVerbose, parseImportLine, parseModelList, parseRoleDefinition, parseScheduleDraft, parseSkillFrontmatter, parseTrigger, pendingImageTokens, persistFailureCode, persistParts, persistToolResults, persistedUsage, planPack, previewSkillImport, pricingFor, projectEntryForDisplay, pruneArtifacts, pruneAttachments, pruneRecordings, pruneSchedules, readImageSize, readMarketplaces, readPluginAbout, readPluginIcon, readPluginManifest, readPluginRecords, readProviderKeyEnv, readRecording, readSessionSurface, reclaimFtsSpace, redactLine, refreshOpenRouterMetadata, removeMarketplace, removeRecordings, removeRoleFile, removeSessionArtifacts, removeSessionAttachments, renderImportTree, renderProjectContext, renderSdkDeclaration, renderSelfIndex, repairSchedules, resolveArtifactRetention, resolveCodeModeWorker, resolveComplianceDirs, resolveEntrySource, resolveInWorkspace, resolveMarketplaceRef, resolveMentions, resolveMultimodalPolicy, resolvePolicyDirs, resolvePricingAt, resolveProjectRoot, resolveScheduleBackend, resolveSessionReference, resolveSessionVisibility, resolveSettings, resolveSkillDirs, resolveSource, resolveTar, resolveWorkspace, restoreParts, revealScopedProvider, roleScopedProvider, roleSourceLabel, ruleCovers, ruleFromString, ruleToString, runCode, runCommand, sanitizeArgNames, sanitizeCommand, sanitizeFtsQuery, sanitizePath, sanitizeToolOutput, scanInstructions, scanPluginDir, scanSkillDirs, searchMarketplaces, setDisplayCurrency, setImportGate, setPluginEnabled, setTrustGate, settingValueChoices, settingValueKind, settingWriteApply, settingWriteLayers, settingWriteTargets, skillIndexDescription, skillIndexResidency, skillIndexStats, sniffMediaType, splitFrontmatter, staticToolProvider, stripArtifactData, substitutePluginRoot, suggestRuleFromApproval, systemOpenArgv, systemPromptSegments, toPosix, toolDefinitionTokens, toolMatches, toolTableTokens, totalTokens, traceSession, triggerPeriodMs, unescapeRuleContent, uninstallPlugin, unknownRoleSkills, unknownRoleTools, unloadedInstructionFiles, updateMarketplace, updatePlugin, usdToMicros, validateSchedule, validateTrigger, validateWindow, withGoalCompression, withGoalPrompt, workspaceDisplayPath, writeSettingValue };
+export { ABOUT_DESC_MAX_CHARS, ABOUT_README_MAX_CHARS, AGENT_ROLE_DIAG_MODULE, ARTIFACT_MAX_TOTAL_BYTES, ARTIFACT_RETENTION_DEFAULTS, ATTACHMENT_MAX_TOTAL_BYTES, ATTACHMENT_RETENTION_DEFAULTS, type AcquireResult, type AgentConfig, AgentLoop, type AgentProvider, type AgentSite, type AgentSiteRef, AppearanceStore, type AppendMessageInput, ApprovalCache, type ApprovalDecision, type ArtifactOpenRefusal, type ArtifactRetention, type AskQuestionDeps, type AttachmentRetention, BLOCKED_TOOLS, type BackendOptions, type BackendOutcome, type BackgroundTaskSource, type BaseOrigin, type BaseSlot, type BeginTurnInput, type BreakdownInput, BudgetGuard, type BudgetGuardOptions, type BudgetInfo, type BudgetLevel, type BudgetOptions, type BudgetStatus, BudgetStore, type BudgetStoreOptions, type BuildFireArgvInput, type BuildIndexOptions, CHECKPOINT_MAX_TOTAL_BYTES, CLAUDE_EVENT_NAMES, CLAUDE_TOOL_NAMES, CODE_MODE_LIMITS, CODE_MODE_SDK_TAG, CONFIG_KEYS, CURRENT_CONFIG_VERSION, type CachedApproval, type CachedDecision, type CheckpointCapture, type CheckpointFile, CheckpointManager, type CheckpointManagerOptions, type CheckpointManifest, CheckpointStore, type CheckpointStoreOptions, type CheckpointSummary, type ClaudeHooksParseOptions, type CodeModeLimits, type CodeRequest, type CodeResult, CodeSandbox, type CommandHookConfig, type CommandHookResult, type CommandLoadOutcome, type CommandLoadSummary, type CommandResult, type CommandRunner, type CompactionResult, type CompiledRules, type ComplianceDirSpec, type ComplianceDirsSummary, ComplianceEngine, type ComplianceEngineInput, type ComplianceGate, type ComplianceHit, type ComplianceRule, type ComplianceRuleSource, type ComplianceSettings, type ComplianceVerdict, type CompressConfig, type CompressResult, type ConfigMigration, type ConfigOrigins, ContextCompressor, type ContextEngine, type CreateScheduleInput, type CreateSessionInput, DEFAULT_COMPLIANCE_ACTIONS, DEFAULT_COMPLIANCE_SETTINGS, DEFAULT_COMPRESSION_THRESHOLD, DEFAULT_GOAL_MAX_ROUNDS, DEFAULT_MAX_HOLD_CHARS, type DelegateArgs, type DelegateConfig, DelegateManager, type DelegateTaskResult, type DiagnoseOptions, type DiscoverOutcome, type DiscoveredFile, type DoctorReport, type DraftParse, EMPTY_RULES, EPOCH_DISK_LEDGER, type EntryProbeCode, type EntryProbeResult, EpochConfigSchema, type ExpandOptions, type ExtractOutcome, FTS_TABLES, FTS_TRIGGERS, type FallbackEvent, type FileSlots, type FileSourceKind, type ForkInput, type FrontmatterParse, type FrontmatterSplit, type FtsHealth, type FtsReclaim, type FtsSpace, type FtsTableHealth, GOAL_BLOCK_CODES, type GateAxis, type GateVerdict, type GenerateInput, type GenerateOutput, type Goal, type GoalBlockReason, type GoalClear, type GoalPhase, type GoalPromptView, type GoalRefusal, type GoalRoundResult, GoalService, GoalStore, type GoalToolDeps, type GoalWrite, HEADLESS_AUDIT_CODES, type HeadlessPolicy, type HookConfigEntry, HookManager, type HookManagerOptions, type HookMatcher, type HookSourceKind, type HookSourceStatus, type HookSourcesOptions, type HookSourcesSummary, type HooksParseOutcome, type MemoryManager$1 as IMemoryManager, INSTRUCTION_BUDGET_CHARS, INSTRUCTION_FILES, type SessionManager$1 as ISessionManager, type SkillSystem$1 as ISkillSystem, ImageLoadError, type ImageSize, type ImportDecision, type ImportGate, type ImportGoal, type ImportMessage, type ImportNode, type ImportPartsResult, type ImportSessionInput, type ImportSessionMeta, type ImportSessionResult, type ImportSkipReason, type ImportTodo, ImportTrustStore, type InstallDependency, type InstallOptions, type InstallOutcome, type InstallPreview, type InstallStep, type InstructionScan, type InstructionSource, type IsolationReason, type IsolationReport, type JsonSchemaDocument, LAUNCHD_LABEL_PREFIX, LOCK_HEARTBEAT_MS, LOCK_STALE_MS, type LastOpenSession, LastOpenSessions, type LayerOutcome, type LayerScalars, type LayerStatus, type LearningContext, type LearningResult, type LearningSkipReason, type LexiconLoadOutcome, type LifecycleOutcome, type ListCandidatesInput, type ListSessionsInput, type ListSessionsOutput, type LoadCommandsOptions, type LoadConfigOptions, type LoadKeybindingsOptions, type LoadKeybindingsResult, type LoadRolesOptions, type LoadedPlugin, type LockHolder, MARKETPLACE_DISPLAY_FIELDS, MARKETPLACE_FILE, MAX_AUDIT_ENTRIES, MAX_COMMAND_DEPTH, MAX_GOAL_MAX_ROUNDS, MAX_IMPORT_DEPTH, MAX_LAST_OPEN_SESSIONS, MAX_OBJECTIVE_CHARS, MAX_REASON_CHARS, MAX_RECENT_WORKSPACES, MODEL_ENTRIES_FILE, MODEL_GIVE_UP_THRESHOLD, MULTIMODAL_DEFAULTS, type ManagedPolicy, ManagedPolicyError, type ManagedSettings, ManagedSettingsSchema, type MarketplaceCatalog, type MarketplaceCategory, type MarketplaceDisplay, type MarketplaceDisplayField, type MarketplaceEntry, type MarketplaceOutcome, type MarketplaceRecord, type MarketplaceStatus, type MemoryConfig, type MemoryEntry, type MemoryImportRecord, type MemoryImportResult, MemoryManager, type MemoryManagerOptions, type MemoryNotice, type MemoryRemoval, type MemorySearchResult, type MemoryTarget, type MemoryWriteResult, type MentionPart, type MentionResolution, type Message, type MessageHit, type MessageRecord, type MessageSurface, type ModelCapability, ModelFailureTracker, type ModelMetaEntry, type ModelPricing, type MultimodalPolicy, NOMINAL_TOTAL_BYTES, NO_REVEALED_TOOLS, type NonInteractiveProbe, type OsTaskSnapshot, type OutputGuard, PACK_EXCLUDES, PACK_MAX_BYTES, PACK_MAX_FILES, PERMISSION_AUDIT_CODES, PLUGIN_ICON_MAX_BYTES, PLUGIN_LAYOUT, PLUGIN_MANIFEST_FILE, PLUGIN_MANIFEST_KEYS, PLUGIN_NAME_PATTERN, PLUGIN_ROOT_ENV, PLUGIN_ROOT_TOKEN, PLUGIN_VISIBILITY, POLICY_DECISIONS, PROBE_VERSION, PROJECT_AGENTS_SUBDIR, PROVIDER_NO_CREDENTIAL, type PackFile, type PackLimits, type PackOutcome, type PackPlan, type PackPlanOutcome, type PermissionAuditCode, type PermissionAuditEntry, type PermissionAuditOutcome, type PermissionAuditScope, type PermissionAuditSnapshot, PermissionManager, type PersistFailureKind, type PersistedBudget, type PersistedPart, type PlanApprovalFn, type PlanEnterResult, type PlanModeDeps, PlanModeState, type PlanSettlement, type PluginAbout, type PluginArtifacts, type PluginAuthor, PluginAuthorSchema, type PluginCommandDir, type PluginCounts, type PluginDoc, type PluginHookFile, type PluginInventory, type PluginLoadOptions, type PluginManifest, type PluginPathRef, type PluginRecord, type PluginSettingsFile, type PluginSourceType, type PluginStateReadOutcome, PluginStore, type PluginVisibility, type PolicyDirSpec, type PolicyDirsSummary, type PolicyLoadOutcome, type PolicyRule, PolicyRuleSchema, type PricingAt, type PricingOverride, type ProjectContext, type ProjectExtensionInventory, ProviderError, ProviderRouter, type ProviderStreamChunk, type ProviderToolCall$1 as ProviderToolCall, type ProviderWarning, type PruneResult, type QuestionAskFn, RECORDING_KEEP_RUNS, RECORDING_MAX_BYTES, ROLE_FRONTMATTER_SCHEMA, RUN_CODE_TOOL, type ReadMessagesInput, type ReadMessagesOutput, type RecentWorkspace, RecentWorkspaces, type RecordRunInput, type RecorderOptions, type RecoveryAction, type RegisterInput, type RegisterOutcome, type RegistrarOptions, type RegistrationPatch, type RepairOutcome, type ResolveMentionsOptions, type ResolveReferenceInput, type ResolveSettingsOptions, type ResolvedCompression, type ResolvedReference, type ResolvedSource, type ResponseFormat, type RestorePartsOptions, type RewindAction, type RewindDrift, type RewindFilePlan, type RewindOptions, type RewindOutcome, type RewindPreview, type RoleCreateFailure, type RoleCreateInput, type RoleCreateOptions, type RoleCreateOutcome, type RoleLoadOutcome, type RoleLoadSummary, type RoleMergeNotice, type RoleMergeResult, type RoleRemoveFailure, type RoleRemoveOptions, type RoleRemoveOutcome, type RoleScope, type RuleMatch, type RuleSuggestion, type RuleVerdict, type RunCodeFailure, type RunCodeInput, type RunCodeOutcome, type RunCodeToolDeps, type RunEstimateInput, type RunInput, type RunResult, type RunningSchedule, SANDBOX_COVERS, SANDBOX_EXCLUDES, SCALAR_KEYS, SCHEDULE_DEFAULTS, SCHEDULE_DEFAULT_ALLOWLIST, SCHEDULE_FORM_BUDGET_USD, SCHEDULE_ISSUE_CODES, SCHTASKS_FOLDER, SESSION_MESSAGES_READ_TOOL, SESSION_MESSAGES_SEARCH_TOOL, SESSION_QUERY_TOOLS, SESSION_SEARCH_TOOL, SESSION_TRACE_TOOL, SETTINGS_LAYER_ORDER, SETTING_WRITE_KEYS, SETTING_WRITE_LAYERS, SKILL_ASSET_DIRS, SKILL_CREATE_TOOL, SKILL_EDIT_TOOL, SKILL_FILE, SKILL_PATCH_TOOL, SKILL_VIEW_TOOL, SKILL_WRITE_FILE_TOOL, SLASH_COMMANDS_DIAG_MODULE, type ScalarKey, type ScanInstructionsOptions, type ScheduleArgvRefusal, type ScheduleArgvResult, type ScheduleArgvWarning, type ScheduleBackend, type ScheduleCliEntry, type ScheduleDraftDeps, type ScheduleDrift, type ScheduleDriftKind, type ScheduleImportInput, type ScheduleInstallForm, type ScheduleIssue, type ScheduleIssueCode, type ScheduleLock, ScheduleRecorder, ScheduleRegistrar, ScheduleStore, type ScheduleValidation, type SchemaExport, type SearchHit, type SearchInput, type SearchMessagesInput, type SearchMessagesOutput, type SearchOutput, type SearchSessionsInput, type SelectionDeps, type SelfConnector, type SelfIndexInput, type SelfSettings, type Session, type SessionCandidate, type SessionHit, SessionManager, type SessionMentionDeps, type SessionMeta, SessionQueries, SessionReferences, type SessionSearchDeps, type SessionStats, type SessionSurface, type SessionTrace, type SessionVisibility, type SessionVisibilityInput, type SettingApply, type SettingApplyFacts, type SettingChain, type SettingFutile, type SettingLayer, type SettingStep, type SettingValue, type SettingValueKind, type SettingWriteFailure, type SettingWriteKey, type SettingWriteLayer, type SettingWriteOutcome, type SettingWriteRequest, type SettingWriteTarget, type SettingWriteTargetsOptions, type SettingsFile, SettingsFileError, SettingsFileSchema, type SettingsLayer, type SettingsResolution, type ShadowFinding, type ShadowKind, type Skill, type SkillDirSource, type SkillDirSpec, type SkillDirsSummary, type SkillImportConflict, type SkillImportDone, type SkillImportEntry, type SkillImportFailure, type SkillImportForm, type SkillImportOptions, type SkillImportPreview, type SkillImportResult, type SkillIndexEntry, type SkillIndexOptions, type SkillIndexResidency, type SkillIndexStats, SkillLearner, type SkillLearningProvider, type SkillMeta, type SkillStats, SkillSystem, type SkillSystemOptions, type SkillViewDeps, type SkillWriteDeps, type SteerSource, type StoredAppearance, type SubAgentRunner, type SubTask, type SubToolCaller, type SummarizeOutput, type SurfaceMessage, type SystemPromptParams, type SystemPromptSegments, TOOL_SEARCH_TOOL, TaskNoticeTracker, type TodoItem, type ToolCall, type ToolConflict, type ToolGate, type ToolNameFidelity, type ToolNameLookup, ToolRegistry, type ToolRevealState, type ToolScope, type ToolSearchDeps, type ToolTableCost, type TraceInput, type TraceNode, TrackerDB, type TrustDecision, type TrustGate, type TrustGateOptions, TrustManager, type TurnRecord, type TurnTiming, UNSETTABLE_USER_KEYS, type UpdateScheduleInput, type UtilityModelInfo, type ValidateScheduleInput, type VersionCheck, Workspace, type WorkspaceFiles, type WorkspaceIssue, type WorkspaceIssueKind, acquireScheduleLock, addMarketplace, addUsage, admitArtifact, admitArtifacts, affectedPaths, approvalEntryFor, approvalRootFor, artifactLaunchArgv, artifactOpenRefusal, assertLevelAllowed, blockedRoleTools, buildContextBreakdown, buildFireArgv, buildFtsMatchQuery, buildSchemaExports, buildSystemPrompt, buildTrigramMatchQuery, builtinRoles, capabilityOfRef, checkEpochVersion, checkFtsHealth, checkShadowing, classifyPersistFailure, classifyProviderError, clearModelCache, coalesceRecording, codeModeWorkerPath, commandNameFromRelPath, compileRuleLists, compressionOptions, computeCost, computeCostMicros, computeExecHash, countRules, createAllowAllGate, createAllowAllImportGate, createAskQuestionTool, createCodeExecTool, createDelegateTool, createDenyAllGate, createDenyAllImportGate, createGoalTool, createImportGate, createMemoryTool, createPlanModeTools, createRoleFile, createRoleScope, createRunCodeTool, createScheduleDraftTool, createSessionMessagesReadTool, createSessionMessagesSearchTool, createSessionSearchTool, createSessionSearchTools, createSessionTraceTool, createSkillViewTool, createSkillWriteTools, createTodoTool, createToolRevealState, createToolScope, createToolSearchTool, createTrustGate, currentEpochVersion, decideImport, decideTrust, defaultConfig, describeArtifactRefusal, describeBackgroundTask, describeHeadlessPolicy, describeIsolation, describeJsonError, diagnoseSchedules, discoverMarkdown, discoverModels, discoverProject, discoverySpec, displayAllows, displayCurrency, draftCommandLine, draftWidening, escapeRuleContent, estimateImageTokens, estimateRunTokens, estimateTokens, evaluateSelection, expandCommand, expandImports, explainSetting, extractArchive, findInstructionFiles, findProjectInstructions, findRole, formatBytes, formatSkillIndex, formatUsd, gateForTool, getCapability, getConfigIssues, getConfigOrigins, getImportGate, getTrustGate, grantedPathsFor, hasDedicatedExecContent, hasExecTierContent, hasPromptCaching, hasProviderCredentials, hasReadTierContent, hasUsableModel, imageFromBase64, imageFromPath, imagePartTokens, importParts, importSkills, installPlugin, instructionDirs, instructionNotices, intervalSlots, inventoryProjectExtensions, inventoryTotal, isBlockCode, isCodeModeDeferred, isEmptyRules, isGoalPhase, isNonInteractive, isReadOnlySubCall, isSettingWriteLayer, isTransientPersistFailure, isValidInterval, isValidPluginName, isWithinWindow, isWritableSettingKey, labelSlug, layerRank, listEntryModels, listRunningSchedules, listSessionCandidates, listWorkspaceFiles, loadCommandDefinitions, loadCommandFile, loadCommands, loadConfig, loadHookSources, loadKeybindings, loadLexiconDir, loadLexiconFiles, loadModelEntries, loadPlugins, loadPolicyFiles, loadPolicyRules, loadRoleDefinitions, loadRoleDir, loadedImports, localDateString, managedSwitchNotes, mapClaudeToolName, mapEpochToolName, mapOperationType, matchPreauthorization, matchRuleLists, matchesHook, mentionsPluginRoot, mergeHeadlessPolicy, mergeRoles, mergeSchedulePatch, microsToUsd, modelEntriesPath, modelListCandidates, needsAllowlist, nextRunAt, noConfigOrigins, noManagedPolicy, noPlugins, normalizeModelEntry, normalizeTrigger, openArtifact, originOf, packFileName, packPlugin, parseClaudeSettingsHooks, parseClock, parseDate, parseFrontmatter, parseHooksConfig, parseHooksConfigVerbose, parseImportLine, parseModelEntry, parseModelList, parseRoleDefinition, parseScheduleDraft, parseSkillFrontmatter, parseTrigger, pendingImageTokens, persistFailureCode, persistParts, persistToolResults, persistedUsage, planPack, previewSkillImport, pricingFor, projectEntryForDisplay, pruneArtifacts, pruneAttachments, pruneRecordings, pruneSchedules, readEntryKey, readImageSize, readMarketplaces, readPluginAbout, readPluginIcon, readPluginManifest, readPluginRecords, readRecording, readSessionSurface, reclaimFtsSpace, redactLine, refreshOpenRouterMetadata, removeMarketplace, removeRecordings, removeRoleFile, removeSessionArtifacts, removeSessionAttachments, renderImportTree, renderProjectContext, renderSdkDeclaration, renderSelfIndex, repairSchedules, resolveArtifactRetention, resolveCodeModeWorker, resolveComplianceDirs, resolveEntrySource, resolveInWorkspace, resolveMarketplaceRef, resolveMentions, resolveMultimodalPolicy, resolvePolicyDirs, resolvePricingAt, resolveProjectRoot, resolveScheduleBackend, resolveSessionReference, resolveSessionVisibility, resolveSettings, resolveSkillDirs, resolveSource, resolveTar, resolveWorkspace, restoreParts, revealScopedProvider, roleScopedProvider, roleSourceLabel, ruleCovers, ruleFromString, ruleToString, runCode, runCommand, sanitizeArgNames, sanitizeCommand, sanitizeFtsQuery, sanitizePath, sanitizeToolOutput, saveModelEntries, scanInstructions, scanPluginDir, scanSkillDirs, searchMarketplaces, setDisplayCurrency, setImportGate, setPluginEnabled, setTrustGate, settingValueChoices, settingValueKind, settingWriteApply, settingWriteLayers, settingWriteTargets, skillIndexDescription, skillIndexResidency, skillIndexStats, sniffMediaType, splitFrontmatter, staticToolProvider, stripArtifactData, substitutePluginRoot, suggestRuleFromApproval, systemOpenArgv, systemPromptSegments, testModelEntry, toPosix, toolDefinitionTokens, toolMatches, toolTableTokens, totalTokens, traceSession, triggerPeriodMs, unescapeRuleContent, uninstallPlugin, unknownRoleSkills, unknownRoleTools, unloadedInstructionFiles, unsetUserSetting, updateMarketplace, updatePlugin, usdToMicros, validateSchedule, validateTrigger, validateWindow, withGoalCompression, withGoalPrompt, workspaceDisplayPath, writeSettingValue };