@sema-agent/server 6.0.0 → 6.2.0

package/USAGE.md

@@ -53,7 +53,7 @@ ANTHROPIC_API_KEY=sk-ant-…   # 可选:ANTHROPIC_BASE_URL / ANTHROPIC_VERSION /
 
 **可选 — 韧性栈:分级超时 + 断路器(core 1.38，叠在 failover 之下)**
 ```bash
-# ③ 分级超时:任务级 timeoutSec 之下补两段,各记为可重试的 [network] → 触发重试/断路器/failover
+# ③ 分级超时:任务级 limits.maxWalltimeMs(6.0.0 起,毫秒)之下补两段,各记为可重试的 [network] → 触发重试/断路器/failover
 MODEL_CONNECT_TIMEOUT_MS=8000        # fetch 迟迟不返响应头(网关连不上)→ 中止
 MODEL_FIRST_TOKEN_TIMEOUT_MS=30000   # SSE 已开但迟迟不吐第一个 delta(网关 hang);reasoning 的首个 thinking 也算首 token
 MODEL_IDLE_TIMEOUT_MS=20000          # (1.40.1)出过 token 后中途卡死:每个 delta 重置,静默超时→中止(补 first-token 只管首字)
@@ -415,14 +415,47 @@ curl -N http://<host>:8090/v1/tasks/stream -H 'content-type: application/json' \
 | HTTP `200` + `status:"completed"` | 成功 | 取 `result` |
 | `status:"blocked"` | agent 主动报卡住 | 看 `blockedReason`,补信息再发 |
 | `status:"failed"` + `errorCode:"conflict"` | 跨实例乐观锁丢失 | 直接重试(幂等) |
-| `status:"timeout"` | 超时 | 拆小任务 / 提高超时(服务端 `limits`) |
+| `status:"failed"` + `errorCode:"limits.max_walltime_exceeded"` | 墙钟到限(6.0.0 起 `status:"timeout"` 退役) | 拆小任务 / 提高 `limits.maxWalltimeMs`(毫秒) |
 | HTTP `401` | 缺 `Authorization` / 缺 `x-agent-principal`(要求时) | 补头 |
 | HTTP `403` / `404`(session/run) | 不是该 principal 的资源 | 用正确身份 |
 | HTTP `409`(`/v1/runs`) | 同 session 已有活跃 run | 等它完成 / 用返回的 `activeTaskId` |
 | HTTP `429` | 限流 | 看 `Retry-After` 退避 |
+| HTTP `429` + `errorCode:"usage.window_exhausted"` | 部署级 token 治理窗耗尽(`USAGE_WINDOWS`) | 看响应体 `retryAfterSec` 退避;窗滑动/桶到期后放行 |
 | HTTP `501`(`/v1/runs`) | 内存模式不支持异步 | 配 MySQL 协议存储(`SESSION_BACKEND=mysql`) |
 
 **机器码**:每个 4xx/5xx 响应体都带一个 `errorCode`(与人类文案 `error` 并列),这是**唯一**该拿来做
 程序分支的字段——**别锚 `error` 文案**。前缀族固定:`auth.` / `request.` / `not_found.` / `conflict.` /
-`limit.` / `capability.`(本部署没接这个面)/ `feature.`(开关没开)/ `internal.` / `state.`;未知码按前缀
-兜底永远安全。完整码表见 `docs/ASSISTANT-WIRE-CONTRACT.md` §附录 A。
+`limit.` / `usage.`(部署级治理窗)/ `capability.`(本部署没接这个面)/ `feature.`(开关没开)/
+`internal.` / `state.`;未知码按前缀兜底永远安全。完整码表见 `docs/ASSISTANT-WIRE-CONTRACT.md` §附录 A。
+
+### 9.1 limits.approachNotice(6.1.0 起)
+
+引擎默认在上下文用量到 80%/95% 时各注入一次接近提示(SSE 上是 `steering_injected` 帧、
+`source:"limit_approach"`)。批处理场景嫌噪声:`limits:{approachNotice:false}` 关闭;调阈:
+`limits:{approachNotice:{at:[0.5,0.9]}}`(两分数 (0,1] 且 r1<=r2,相等合法;坏形 400 点名)。
+
+### 9.2 部署级 token 治理窗(USAGE_WINDOWS,6.1.0 起)
+
+跨任务的滑动 token 预算(core `usageWindows`),缺省不设=关。单键 JSON 数组:
+
+```bash
+USAGE_WINDOWS='[{"windowMs":18000000,"maxTokens":5000000,"anchor":"first-use"}]'   # 5h 窗 500 万 token
+# anchor:"first-use"=首次消费开桶、到期重开;"rolling"=滑动窗(最近 windowMs 内的消费之和)
+```
+
+- **key 语义是 per-key 而不是一口总锅**:带 principal 的请求计到各自 principal 的窗,匿名请求计到
+  GLOBAL 锅——`REQUIRE_PRINCIPAL=false` 的混流部署下,总放行量=(principal 数+1)×maxTokens。要 fleet
+  级总闸请用 quota/lease 面(那是按部署计费轴)。同一调用方有时带凭证有时不带,会在两口锅间劈叉计数。
+- 耗尽:提交面立即 `429 usage.window_exhausted`(体 `retryAfterSec` + `Retry-After` 头);已受理的
+  任务撞窗时,基建合格(checkpoint+durable approval)⇒ suspend(reason `usage_window`)等窗放行,
+  不合格 ⇒ 响亮失败同码落终态记录。
+- 计量覆盖:主任务、具名/委托 subagent、hook 内部任务全计(部署真花销都进窗)。
+- 坏形 `USAGE_WINDOWS` 拒启(fail-loud 点名第几项);**改窗形≈重开账**(first-use 桶按 windowMs
+  配对,改了窗长老桶下次记账即弃)。
+- 存储:SQL 后端=跨副本一致(`usage_window` 表,行锁守恒);local=文件;纯内存 dev=进程内。
+
+### 9.3 沙箱寿命声明(6.1.0 起)
+
+k8s 沙箱(pod `activeDeadlineSeconds` 真硬死线)向引擎声明 `lifetimeMs`——死线前 ~60s 引擎在 turn
+边界尝试 suspend(reason `env_lifetime`,基建合格时)而不是被平台杀在半途;单个 >60s 的工具调用仍可能
+冲过该窗口,声明是尽力座不是保证。e2b 沙箱有 keepalive 滚动续期、无固定死线,不声明(行为不变)。

package/dist/boot/runner-deps.d.ts

@@ -34,6 +34,8 @@ export interface RunnerDepsCtx {
     rosterStore: RunnerDeps["rosterStore"];
     backgroundAgentStore: RunnerDeps["backgroundAgentStore"];
     mailboxStore: RunnerDeps["mailboxStore"];
+    /** design/166-T1:治理窗账本店(USAGE_WINDOWS 配置时才在场;与 config.usageWindows 成对进 deps)。 */
+    usageWindowStore: RunnerDeps["usageWindowStore"];
     brain: ReturnType<typeof createBrain>;
     pricing: ReturnType<typeof buildPricing>;
     tracer: ReturnType<typeof createTracer>;
@@ -66,7 +68,7 @@ export interface RunnerDepsCtx {
 }
 /** design/158 A10 留档发现②:main runner `RunnerDeps` 与 main.ts subRunner 字面量之间此前手工重复
  * 的 ~15 个键,类型标注见 {@link createSharedRunnerDeps} 头注。 */
-export type SharedRunnerDeps = Pick<RunnerDeps, "brain" | "models" | "roles" | "tiers" | "pricing" | "tracer" | "promptSource" | "executionEnvFactory" | "lspManager" | "backgroundAgentStore" | "mailboxStore" | "rosterStore" | "hooks" | "toolResultStore" | "sessionPolicyStore">;
+export type SharedRunnerDeps = Pick<RunnerDeps, "brain" | "models" | "roles" | "tiers" | "pricing" | "tracer" | "promptSource" | "executionEnvFactory" | "lspManager" | "backgroundAgentStore" | "mailboxStore" | "rosterStore" | "hooks" | "toolResultStore" | "sessionPolicyStore" | "usageWindows" | "usageWindowStore">;
 /**
  * design/158 A10 留档发现②(review 2026-07-29,[1543]§三族A 同源修补的延续):main runner 的
  * `RunnerDeps` 字面量(下方 `createRunnerDeps`)与 `main.ts` 里 subRunner 的 `new Runner({...})`
@@ -95,7 +97,7 @@ export type SharedRunnerDeps = Pick<RunnerDeps, "brain" | "models" | "roles" | "
  *    属性,比再抽一层共享基座更强的同源保证),不重复收纳进这里。
  */
 /** 基座真实消费的窄面(Pick)——subRunner 调用点(main.ts)只需凑这 13 个字段,不必造全量 ctx。 */
-export type SharedRunnerDepsCtx = Pick<RunnerDepsCtx, "config" | "brain" | "pricing" | "tracer" | "promptSource" | "executionEnvFactory" | "lspManager" | "backgroundAgentStore" | "mailboxStore" | "rosterStore" | "deploymentHooks" | "toolResultStore" | "sessionPolicyStore">;
+export type SharedRunnerDepsCtx = Pick<RunnerDepsCtx, "config" | "brain" | "pricing" | "tracer" | "promptSource" | "executionEnvFactory" | "lspManager" | "backgroundAgentStore" | "mailboxStore" | "rosterStore" | "deploymentHooks" | "toolResultStore" | "sessionPolicyStore" | "usageWindowStore">;
 export declare function createSharedRunnerDeps(ctx: SharedRunnerDepsCtx): SharedRunnerDeps;
 export declare function createRunnerDeps(ctx: RunnerDepsCtx): RunnerDeps;
 //# sourceMappingURL=runner-deps.d.ts.map

package/dist/boot/runner-deps.js

@@ -49,6 +49,12 @@ export function createSharedRunnerDeps(ctx) {
         // E6: operator-tightened session tool rules — core folds them into the ToolPolicy FIRST (subtract-only) for tasks
         // carrying a sessionId (a delegated subagent has none → inherits no rules). Opt-in: undefined ⇒ no rules read.
         sessionPolicyStore: ctx.sessionPolicyStore ? ctx.sessionPolicyStore : undefined,
+        // design/166-T1:治理窗两键**成对**且进共享基座——主/sub/hook 三 runner 全覆盖(漏挂 subRunner=
+        // 子代用量不进窗,治理可被 subagent 刷穿;双记不存在:core stats.nested 是旁路侧栏不折入
+        // stats.tokens,governance.commit 是 per-任务 delta 制)。store 只在 config.usageWindows 配置时
+        // 构造(boot/stores.ts),两键同真同假。
+        usageWindows: ctx.config.usageWindows ? ctx.config.usageWindows : undefined,
+        usageWindowStore: ctx.usageWindowStore ? ctx.usageWindowStore : undefined,
     };
     return shared;
 }

package/dist/boot/stores.d.ts

@@ -28,5 +28,6 @@ export declare function openStores(ctx: OpenStoresCtx): Promise<{
     memorySyncRunner: MemorySyncRunner | undefined;
     sessionStore: import("@sema-agent/core").SessionStore;
     breakerState: import("../plugins/breaker-state-sql.js").TiDBBreakerState | import("../plugins/breaker-state-sql.js").PgBreakerState | undefined;
+    usageWindowStore: import("@sema-agent/core").UsageWindowStore | undefined;
 }>;
 //# sourceMappingURL=stores.d.ts.map

package/dist/boot/stores.js

@@ -13,7 +13,7 @@
  *  3. `breakerState` 放在段尾:brain(下一段)要它,而它要 backend。
  */
 import { join } from "node:path";
-import { FileBackgroundAgentStore, FileMailboxStore, FileRosterStore } from "@sema-agent/core";
+import { FileBackgroundAgentStore, FileMailboxStore, FileRosterStore, FileUsageWindowStore, InMemoryUsageWindowStore } from "@sema-agent/core";
 import { createMemorySyncRunner, createMemorySyncTransport } from "../memory-sync-client.js";
 import { PgMemoryEngineBackend, ensurePgMemoryEngineSchema } from "../plugins/memory-engine-pg.js";
 import { TiDBMemoryEngineBackend, ensureTiDBMemoryEngineSchema } from "../plugins/memory-engine-tidb.js";
@@ -22,6 +22,7 @@ import { TiDBMemoryHistoryStore, TiDBMemorySyncStore, ensureTiDBMemoryHistorySch
 import { MinioBlobBackend } from "../plugins/blob-backend.js";
 import { PgBackgroundAgentStore, TiDBBackgroundAgentStore, ensurePgBackgroundAgentSchema, ensureTiDBBackgroundAgentSchema } from "../plugins/background-agent-store-sql.js";
 import { PgMailboxStore, TiDBMailboxStore, ensurePgMailboxSchema, ensureTiDBMailboxSchema } from "../plugins/mailbox-store-sql.js";
+import { PgUsageWindowStore, TiDBUsageWindowStore, ensurePgUsageWindowSchema, ensureTiDBUsageWindowSchema } from "../plugins/usage-window-store-sql.js";
 import { PgRosterStore, TiDBRosterStore, ensurePgRosterSchema, ensureTiDBRosterSchema } from "../plugins/roster-store-sql.js";
 import { LocalTaskAttachmentStore } from "../plugins/local-task-attachment-store.js";
 import { PgTaskAttachmentStore, TiDBTaskAttachmentStore, ensurePgTaskAttachmentSchema, ensureTiDBTaskAttachmentSchema } from "../plugins/task-attachment-store.js";
@@ -261,6 +262,31 @@ export async function openStores(ctx) {
         if (mailboxStore)
             logger.info("mailbox_store_enabled", { backend: pgPool ? "pg" : mysqlPool ? "tidb" : "file" });
     }
+    // design/166-T1:治理窗账本店——只在 USAGE_WINDOWS 配置时构造(两键成对进 RunnerDeps,core 的
+    // 「windows 有 store 无=INACTIVE 警告」在构造上被排除)。形态跟 mailbox:tidb/pg=SQL twins
+    // (ensure-first+行锁,真双库验证,usage-window-store-sql.ts 顶注);local=core FileUsageWindowStore
+    // (构造器内部自拼 usage-windows/,直传数据根——复审新6);纯内存 dev=core InMemoryUsageWindowStore
+    // (进程内计数,单进程 dev 的诚实形——治理窗设了就得生效,不因无持久层而静默失活)。
+    let usageWindowStore;
+    if (config.usageWindows) {
+        const mysqlPool = backend?.mysqlPool?.();
+        const pgPool = backend?.pgPool?.();
+        if (pgPool) {
+            await ensurePgUsageWindowSchema(async (text, params) => pgPool.query(text, params));
+            usageWindowStore = new PgUsageWindowStore(pgPool);
+        }
+        else if (mysqlPool) {
+            await ensureTiDBUsageWindowSchema(mysqlPool);
+            usageWindowStore = new TiDBUsageWindowStore(mysqlPool);
+        }
+        else if (backend?.kind === "local") {
+            usageWindowStore = new FileUsageWindowStore(config.localDataRoot ?? localRoot);
+        }
+        else {
+            usageWindowStore = new InMemoryUsageWindowStore();
+        }
+        logger.info("usage_window_store_enabled", { backend: pgPool ? "pg" : mysqlPool ? "tidb" : backend?.kind === "local" ? "file" : "memory", windows: config.usageWindows.length });
+    }
     // 142-S5 §1.4: the per-scope export READ face lights up only on the DB memory plane (the multi-tenant
     // truth lives in the scope-partitioned tables; the file posture exports by copying the memory dir, so
     // the route 501s honestly there). History-table WRITE wiring: inside the backend construction above
@@ -365,6 +391,7 @@ export async function openStores(ctx) {
     return {
         backend, storeBackendDegraded, memoryEngine, memorySyncCursors, rosterStore, backgroundAgentStore,
         taskAttachmentStore, mailboxStore, memoryExportBackend, memorySyncRunner, sessionStore, breakerState,
+        usageWindowStore,
     };
 }
 //# sourceMappingURL=stores.js.map

package/dist/capabilities/scenarios.d.ts

@@ -129,7 +129,6 @@ export declare function semaIdentityProvider(): PromptProvider;
  * 无 systemPrompt 且无品牌时原样返回 core 常量(测试以引用比对锁 bench 同源,不做字符串快照)。
  */
 export declare function codePromptProvider(brand: boolean): PromptProvider;
-/** @deprecated [891] 改名 code——一版过渡期保留旧符号(与场景名 alias 同窗退役)。 */
 export declare function buildScenarios(deps: ScenarioDeps): Record<string, Scenario>;
 /** Resolve the scenario for a request (falls back to `default`). */
 export declare function selectScenario(scenarios: Record<string, Scenario>, name: string | undefined): Scenario;

package/dist/capabilities/scenarios.js

@@ -85,8 +85,9 @@ export function codePromptProvider(brand) {
         ],
     };
 }
-/** @deprecated [891] 改名 code——一版过渡期保留旧符号(与场景名 alias 同窗退役)。 */
 // [2400] CAPS-OPS-11:autonomousPromptProvider 别名导出已随场景退役删除(真身=codePromptProvider)。
+// 其 `@deprecated` JSDoc 曾残留于此,被 tsc 误挂到下方 buildScenarios(三处调用点全告 deprecated
+// ——TODO-3 立案的「迁移」实为孤儿注释,随删除清账;buildScenarios 本身非退役面)。
 export function buildScenarios(deps) {
     // The default scenario filters skills by "default" — NOT by req.scenario (which may be an unknown name
     // that fell back here): the bundle must be a coherent "default" set, matching how main.ts resolves an

package/dist/config-types.d.ts

@@ -642,6 +642,16 @@ export interface ServiceConfigFlat {
      *  Running rows are never reaped (that is the orphan-grace sweep's job). Default 30 days, floor 1m.
      *  `WORKFLOW_RUN_RETENTION_MS`. */
     workflowRunRetentionMs: number;
+    /** design/166-T1 — core 5.8.0 部署级 token 治理窗(`RunnerDeps.usageWindows`):滑动窗内跨任务
+     *  token 预算,key=principal(缺席=GLOBAL 一口锅,per-key 各一份额度——混流部署语义见 USAGE.md)。
+     *  `USAGE_WINDOWS` 单键 JSON 数组(每项 {windowMs,maxTokens,anchor:"first-use"|"rolling"});
+     *  缺省未设=关(零行为变化)。fail-loud:坏 JSON/空数组/非正整数/未知 anchor → boot throw
+     *  (parseUsageWindows)。窗形变更≈重开账(first-use 桶按 windowMs 配对,老桶下次 charge 即弃)。 */
+    usageWindows?: readonly {
+        windowMs: number;
+        maxTokens: number;
+        anchor: "first-use" | "rolling";
+    }[];
     /** core 1.364 durable background agents([1503] 提货单③):reaper 经 `TaskRegistry.reapDurableAgents`
      *  (联合 reap——条件删赢了才 release 转录 session;裸 store.reap 会 strand 转录)按 scope 清 TERMINAL
      *  `a*` 行,老于此值的删。SQL twins 走 DISTINCT-scope 枚举;local FileBackgroundAgentStore 单租户
@@ -888,7 +898,7 @@ export type ServiceMemoryConfig = Pick<ServiceConfigFlat, "memoryEngineEnabled"
  *  函数不产出它,但它与 `autonomy` 是同一根治理棒的两半,归本组。 */
 export type ServiceAuthConfig = Pick<ServiceConfigFlat, "authToken" | "authTokens" | "allowUnauthedWrites" | "corsOrigins" | "principalHeader" | "requirePrincipal" | "autonomy" | "commandPolicy" | "operatorPrincipals" | "principalJwtPubkeys" | "principalJwtIss" | "principalJwtAud" | "principalJwtMaxTtlSec" | "bindHost" | "bindHostSource">;
 /** 组:orchestration(编排 + 执行车道 + 沙箱面 + workflow/后台 agent 存留)。 */
-export type ServiceOrchestrationConfig = Pick<ServiceConfigFlat, "remoteExec" | "worktreeIsolation" | "leaderEnabled" | "leaderFanoutEnabled" | "routerEnabled" | "selfOrchestrationEnabled" | "selfOrchestrationModels" | "selfOrchestrationWorkerIsolation" | "forkEnabled" | "experimentalObserverAgents" | "schedulerEnabled" | "schedulerSessionWakeup" | "schedulerSessionLifetime" | "schedulerStorePath" | "planModeEnabled" | "workflowRunStoreBackend" | "workflowOrphanGraceMs" | "workflowJournalRetentionMs" | "workflowRunRetentionMs" | "workflowAgentsReadOnly" | "workflowSizeGuideline" | "backgroundAgentRetentionMs" | "backgroundAgentStaleRunningMs" | "backgroundAgentParkClaimStaleMs" | "rosterRetentionMs" | "scratchpadSweepTtlMs" | "sandboxPkgSource" | "sessionAutoTitle" | "selectEnvironmentTool" | "envFactsEnabled" | "toolDeferLongtail" | "lspEnabled" | "lspHostEnabled" | "imageBakes">;
+export type ServiceOrchestrationConfig = Pick<ServiceConfigFlat, "remoteExec" | "worktreeIsolation" | "leaderEnabled" | "leaderFanoutEnabled" | "routerEnabled" | "selfOrchestrationEnabled" | "selfOrchestrationModels" | "selfOrchestrationWorkerIsolation" | "forkEnabled" | "experimentalObserverAgents" | "schedulerEnabled" | "schedulerSessionWakeup" | "schedulerSessionLifetime" | "schedulerStorePath" | "planModeEnabled" | "workflowRunStoreBackend" | "workflowOrphanGraceMs" | "workflowJournalRetentionMs" | "workflowRunRetentionMs" | "usageWindows" | "workflowAgentsReadOnly" | "workflowSizeGuideline" | "backgroundAgentRetentionMs" | "backgroundAgentStaleRunningMs" | "backgroundAgentParkClaimStaleMs" | "rosterRetentionMs" | "scratchpadSweepTtlMs" | "sandboxPkgSource" | "sessionAutoTitle" | "selectEnvironmentTool" | "envFactsEnabled" | "toolDeferLongtail" | "lspEnabled" | "lspHostEnabled" | "imageBakes">;
 /** 组:limitsHttp(HTTP 面 + 各类上限/配额/回收窗)。 */
 export type ServiceLimitsHttpConfig = Pick<ServiceConfigFlat, "port" | "attachmentOrphanGraceMs" | "workspaceFileMaxBytes" | "attachmentMaxBytes" | "attachmentMimeAllowlist" | "attachmentUnboundTtlMs" | "infraCostRates" | "drainGraceMs" | "sighupIdleGraceMs" | "rateLimitPerMin" | "maxTaskCostUsd" | "maxTaskTokens" | "maxPrincipalCostUsd" | "costQuotaWindowSec" | "reapIntervalSec" | "runStaleSec" | "toolResultTtlSec">;
 /** 组:observability(可观测)。 */

package/dist/config.d.ts

@@ -11,6 +11,15 @@ export type { ServiceConfig, ScopedMcpServer, ImageBakeConfig, ServiceConfigFlat
  *  config overlay (config-center/facade.ts `applyRuntimeHot`) can re-derive the ENV BASELINE to revert to when center
  *  stops managing `autonomy` (a stale center override must not stick — see applyRuntimeHot). */
 export declare function parseAutonomy(raw: string | undefined): Autonomy | undefined;
+/** design/166-T1 — parse `USAGE_WINDOWS`(单键 JSON 数组;逐窗散键在窗数可变时组合爆炸,JSON 是唯一
+ *  封闭形)。unset/空串 → undefined(关)。fail-loud 族(numEnv 同纪律):坏 JSON/非数组/空数组/
+ *  非正有限整数/未知 anchor 全部 boot throw 点名——「设了但无意义」静默关掉=部署方以为有治理实际没有。
+ *  server 严于 core(core 允 maxTokens=0=恒拒锅;这里要求正整数,0 配置显然是笔误不是意图)。 */
+export declare function parseUsageWindows(raw: string | undefined): readonly {
+    windowMs: number;
+    maxTokens: number;
+    anchor: "first-use" | "rolling";
+}[] | undefined;
 /** Numeric env with validation: a non-numeric value FAILS at startup instead of silently becoming `NaN`
  *  (which e.g. slips past the `runStaleSec` liveness guard and silently disables the reaper). */
 export declare function numEnv(name: string, fallback: string): number;

package/dist/config.js

@@ -26,6 +26,34 @@ export function parseAutonomy(raw) {
     }
     return v;
 }
+/** design/166-T1 — parse `USAGE_WINDOWS`(单键 JSON 数组;逐窗散键在窗数可变时组合爆炸,JSON 是唯一
+ *  封闭形)。unset/空串 → undefined(关)。fail-loud 族(numEnv 同纪律):坏 JSON/非数组/空数组/
+ *  非正有限整数/未知 anchor 全部 boot throw 点名——「设了但无意义」静默关掉=部署方以为有治理实际没有。
+ *  server 严于 core(core 允 maxTokens=0=恒拒锅;这里要求正整数,0 配置显然是笔误不是意图)。 */
+export function parseUsageWindows(raw) {
+    const v = raw?.trim();
+    if (!v)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(v);
+    }
+    catch (e) {
+        throw new Error(`env USAGE_WINDOWS is not valid JSON: ${String(e)} — expected e.g. [{"windowMs":18000000,"maxTokens":5000000,"anchor":"first-use"}]`);
+    }
+    if (!Array.isArray(parsed) || parsed.length === 0) {
+        throw new Error(`env USAGE_WINDOWS must be a NON-EMPTY JSON array of {windowMs,maxTokens,anchor} (an empty array is a governance no-op nobody chose — unset the env to turn windows off)`);
+    }
+    const out = parsed.map((w, i) => {
+        const o = w;
+        const posInt = (n) => typeof n === "number" && Number.isInteger(n) && n > 0;
+        if (typeof w !== "object" || w === null || !posInt(o.windowMs) || !posInt(o.maxTokens) || (o.anchor !== "first-use" && o.anchor !== "rolling")) {
+            throw new Error(`env USAGE_WINDOWS[${i}] is invalid: expected {windowMs: positive int ms, maxTokens: positive int, anchor: "first-use"|"rolling"} (got ${JSON.stringify(w)})`);
+        }
+        return Object.freeze({ windowMs: o.windowMs, maxTokens: o.maxTokens, anchor: o.anchor });
+    });
+    return Object.freeze(out);
+}
 /** Resolve a CSV of env-var NAMES into a {NAME: value} map from THIS process's env (out-of-band secret
  *  forwarding into a sandbox). A name with no value set is skipped (not forwarded as undefined). The values
  *  are secrets — they live only in the returned map (in-memory), never logged. */
@@ -1023,6 +1051,8 @@ function parseOrchestrationDomain(ctx) {
         throw new Error(`WORKFLOW_SIZE_GUIDELINE must be small|medium|large|unrestricted, got "${workflowSizeGuidelineRaw}"`);
     }
     const workflowSizeGuideline = workflowSizeGuidelineRaw;
+    // design/166-T1:治理窗(fail-loud 解析;unset=undefined=关)。
+    const usageWindows = parseUsageWindows(process.env.USAGE_WINDOWS);
     const bakeRunnerPrincipal = env("BAKE_RUNNER_PRINCIPAL", "system:bake-runner");
     // ── design/158 B4 ② — the four knobs whose canonical name went from negative to positive. Only the first
     // lands on `ServiceConfig`; the other three are read lazily at their use sites (main.ts's LKG gate,
@@ -1193,6 +1223,7 @@ function parseOrchestrationDomain(ctx) {
         workflowOrphanGraceMs: Math.max(60_000, numEnv("WORKFLOW_ORPHAN_GRACE_MS", String(24 * 60 * 60 * 1000))), // SVC-1: 24h default, floor 1m
         workflowJournalRetentionMs: Math.max(60_000, numEnv("WORKFLOW_JOURNAL_RETENTION_MS", String(7 * 24 * 60 * 60 * 1000))), // SVC-2: 7d default, floor 1m
         workflowRunRetentionMs: Math.max(60_000, numEnv("WORKFLOW_RUN_RETENTION_MS", String(30 * 24 * 60 * 60 * 1000))), // 30d default, floor 1m; SQL twins only
+        ...(usageWindows ? { usageWindows } : {}), // design/166-T1:USAGE_WINDOWS 治理窗(fail-loud 已在 parseUsageWindows)
         backgroundAgentRetentionMs: Math.max(60_000, numEnv("BG_AGENT_RETENTION_MS", String(7 * 24 * 60 * 60 * 1000))), // core 1.364: 7d default, floor 1m
         backgroundAgentStaleRunningMs: Math.max(10 * 60_000, numEnv("BG_AGENT_STALE_RUNNING_MS", String(15 * 60_000))), // core 契约 ≥10min 硬钳(60s 写者心跳)
         backgroundAgentParkClaimStaleMs: Math.max(60_000, numEnv("BG_AGENT_PARK_CLAIM_STALE_MS", String(60 * 60_000))), // [1575] F1 修:default 1h,floor 1m(零/负值都不该让整块清算失活)
@@ -1334,7 +1365,7 @@ const ORCHESTRATION_GROUP_KEYS = [
     "remoteExec", "worktreeIsolation", "leaderEnabled", "leaderFanoutEnabled", "routerEnabled", "selfOrchestrationEnabled",
     "selfOrchestrationModels", "selfOrchestrationWorkerIsolation", "forkEnabled", "experimentalObserverAgents",
     "schedulerEnabled", "schedulerSessionWakeup", "schedulerSessionLifetime", "schedulerStorePath", "planModeEnabled", "workflowRunStoreBackend",
-    "workflowOrphanGraceMs", "workflowJournalRetentionMs", "workflowRunRetentionMs", "workflowAgentsReadOnly",
+    "workflowOrphanGraceMs", "workflowJournalRetentionMs", "workflowRunRetentionMs", "usageWindows", "workflowAgentsReadOnly",
     "workflowSizeGuideline", "backgroundAgentRetentionMs", "backgroundAgentStaleRunningMs",
     "backgroundAgentParkClaimStaleMs", "rosterRetentionMs", "scratchpadSweepTtlMs", "sandboxPkgSource",
     "sessionAutoTitle", "selectEnvironmentTool", "envFactsEnabled", "toolDeferLongtail", "lspEnabled", "lspHostEnabled",

package/dist/http/route-ctx.d.ts

@@ -47,6 +47,8 @@ export interface RouteHelpers {
     rateLimited(req: IncomingMessage, res: ServerResponse): boolean;
     quotaExceeded(req: IncomingMessage, res: ServerResponse): boolean;
     leaseDenied(req: IncomingMessage, res: ServerResponse): Promise<boolean>;
+    /** design/166-T1:治理窗 pre-admission(异步 202 车道的唯一 429 出路;key 公式与 core 单源)。 */
+    usageWindowDenied(req: IncomingMessage, res: ServerResponse): Promise<boolean>;
     safeDecode(seg: string): string | null;
     isFleetWide(req: IncomingMessage): boolean;
     runOwnerOk(req: IncomingMessage, res: ServerResponse, owner: string | null): boolean;

package/dist/http/routes/runs.js

@@ -111,7 +111,7 @@ export async function handleRunVerbs(req, res, url, ctx) {
 async function handleRunsBody(req, res, url, ctx, miss) {
     const { deps } = ctx;
     const { idemCache, inflightRuns, preemptableRuns, cancelledViaVerb, steerableRuns, wakeParkMints } = ctx.registry;
-    const { readJson, rateLimited, quotaExceeded, leaseDenied, runOwnerOk, runSessionAcceptOk } = ctx.helpers;
+    const { readJson, rateLimited, quotaExceeded, leaseDenied, usageWindowDenied, runOwnerOk, runSessionAcceptOk } = ctx.helpers;
     const { prepareSpec } = ctx.legs;
     const source = ctx.req.source;
     // Async run: create + return ids immediately, execute in the background.
@@ -171,7 +171,9 @@ async function handleRunsBody(req, res, url, ctx, miss) {
         }
         // 🔴 复审 C1:lease gate for a genuinely-NEW submission (past the idempotency replay above). Keyed on the
         // VERIFIED submitter = the principal billed for this run's spend (correct principal for the sync door).
-        if (await leaseDenied(req, res))
+        // design/166-T1:治理窗 pre-admission 同位(idempotency replay 之后——重放已建 run 必须拿回 202 收据,
+        // 不得因窗满改判 429;异步 202 车道的唯一 429 出路,core 进场拒是竞态窗兜底)。
+        if ((await leaseDenied(req, res)) || (await usageWindowDenied(req, res)))
             return;
         const resp = await idemCache.run(idemKey, async () => {
             const sessionId = prepared.spec.sessionId ?? uuidv7();

package/dist/http/routes/tasks.js

@@ -22,7 +22,7 @@ export async function handleTasks(req, res, url, ctx) {
 async function handleTasksBody(req, res, url, ctx, miss) {
     const { deps } = ctx;
     const { idemCache, inflightRuns, cancelledViaVerb, steerableRuns, counters } = ctx.registry;
-    const { rateLimited, quotaExceeded, leaseDenied } = ctx.helpers;
+    const { rateLimited, quotaExceeded, leaseDenied, usageWindowDenied } = ctx.helpers;
     const { prepareSpec, finalizeTaskResult } = ctx.legs;
     const reqState = ctx.req;
     const source = ctx.req.source;
@@ -61,7 +61,7 @@ async function handleTasksBody(req, res, url, ctx, miss) {
             }
             return;
         }
-        if (rateLimited(req, res) || quotaExceeded(req, res) || (await leaseDenied(req, res)))
+        if (rateLimited(req, res) || quotaExceeded(req, res) || (await leaseDenied(req, res)) || (await usageWindowDenied(req, res)))
             return;
         const prepared = await prepareSpec(req, res);
         if (!prepared)

package/dist/http/server.d.ts

@@ -344,6 +344,10 @@ export interface ServiceGovernanceDeps {
     costQuota?: QuotaTracker;
     /** D4 AP:worker 侧 quota-lease admission(协商式;center lane 未配 = 缺席 = 零行为)。 */
     fleetLease?: FleetLeaseManager;
+    /** design/166-T1:治理窗账本店(USAGE_WINDOWS 配置时在场,与 config.usageWindows 成对)——提交面
+     *  pre-admission 读窗用(主力 /v1/runs 是 202 异步,core 进场拒发生在 202 之后永远变不成 429;
+     *  这里是异步车道唯一的 429 出路)。enforcement 真源在 core(RunnerDeps 同店),此门是快速座。 */
+    usageWindowStore?: import("@sema-agent/core").UsageWindowStore;
 }
 /** **部署自述面**:只被 /health、/v1/capabilities 与提交前置门读的部署事实(多为 live getter,
  *  不是快照——/health 必须回答「此刻」)。 */

package/dist/http/server.js

@@ -1,7 +1,7 @@
 import http from "node:http";
 import { once } from "node:events";
 import { createHash } from "node:crypto";
-import { uuidv7, isThinkingLevel, expandTiers, resumeWithVerification, CheckpointError, HAND_TOOL_EFFECTS, defaultTaskRegistry, validatePendingSteer, subscribeWorkflow } from "@sema-agent/core";
+import { uuidv7, isThinkingLevel, expandTiers, resumeWithVerification, CheckpointError, HAND_TOOL_EFFECTS, defaultTaskRegistry, validatePendingSteer, subscribeWorkflow, GLOBAL_USAGE_KEY, usageRetryAfterMs } from "@sema-agent/core";
 import { decideParkedAgent, findParkedAgentForCheckpoint } from "../parked-decide.js";
 import { matchCatalogModel } from "../model-select.js";
 import {} from "../config-center/facade.js";
@@ -10,7 +10,7 @@ import { verifyDirectDoorProof } from "../principal-jwt.js";
 import {} from "../memory-sync.js";
 import { MAX_SETTINGS_OUTPUT_STYLE_CHARS, MAX_SETTINGS_PERMISSION_RULES, MAX_SETTINGS_ENV_VARS, MAX_SETTINGS_ENV_KEY_CHARS, MAX_SETTINGS_ENV_VALUE_CHARS } from "../task-settings.js";
 import { parseHooksConfig } from "../hooks/hook-runner.js";
-import { validateTaskAgents } from "../spec-fields.js";
+import { normalizeApproachNotice, validateTaskAgents } from "../spec-fields.js";
 import { isValidCwd, MAX_ADDITIONAL_DIRS } from "../task-cwd.js";
 import { runInBackground, evictIfConflict, stripCheckpointToken, TurnAnchorCapture, HEARTBEAT_MS, markChildrenStoppedByUserOnAbort } from "../runs.js";
 import { looksLikeJwt } from "@sema-agent/registry-core/api/auth-bridge";
@@ -297,7 +297,7 @@ export function createHttpServer(rawDeps) {
     const routeCtxBase = {
         deps,
         registry: { idemCache, inflightRuns, preemptableRuns, cancelledViaVerb, steerableRuns, wakeParkMints, counters },
-        helpers: { readJson, readRawBody, rateLimited, quotaExceeded, leaseDenied, safeDecode, isFleetWide, runOwnerOk, sessionOwnerScope, sessionOwnerScopeForWrite, runSessionAcceptOk },
+        helpers: { readJson, readRawBody, rateLimited, quotaExceeded, leaseDenied, usageWindowDenied, safeDecode, isFleetWide, runOwnerOk, sessionOwnerScope, sessionOwnerScopeForWrite, runSessionAcceptOk },
         local: { images: createImagesLocal(deps), sessions: createSessionsLocal(), sessionSync: createSessionSyncLocal() },
         // A9 尾批:提交/续跑「腿」只装引用(实现仍在本闭包里,逐字未动)——tasks/runs 共用 prepareSpec,
         // approvals/assistant/notify-wake 共用 resume 家族;走这一格才不会造出 routes/* 互相值 import 的环。
@@ -958,7 +958,12 @@ export function createHttpServer(rawDeps) {
                 sendError(res, 400, "request.field_invalid", "limits.timeoutSec was retired in core 5.8.0 — use limits.maxWalltimeMs (milliseconds; opt-in wall clock)");
                 return null;
             }
-            for (const k of ["deadlineNudge", "callCapByDeadline", "gracefulFinalize"]) {
+            // 166-T3(靶4b):deadlineNudge 的替代=approachNotice(core RETIRED 表同源);另两键随机制退役无替代。
+            if (l.deadlineNudge !== undefined) {
+                sendError(res, 400, "request.field_invalid", "limits.deadlineNudge was retired in core 5.8.0 — use limits.approachNotice (default on at 80%/95%; false turns it off, {at: [r1, r2]} tunes thresholds)");
+                return null;
+            }
+            for (const k of ["callCapByDeadline", "gracefulFinalize"]) {
                 if (l[k] !== undefined) {
                     sendError(res, 400, "request.field_invalid", `limits.${k} was retired in core 5.8.0 (the deadline-pacing mechanism family is gone; there is no replacement key — remove it)`);
                     return null;
@@ -971,6 +976,14 @@ export function createHttpServer(rawDeps) {
                     return null;
                 }
             }
+            // 166-T3:approachNotice fresh-submit fail-loud(判据单源 normalizeApproachNotice,阈值规则对齐 core a<=b)。
+            {
+                const v = l.approachNotice;
+                if (v !== undefined && normalizeApproachNotice(v) === undefined) {
+                    sendError(res, 400, "request.field_invalid", "limits.approachNotice accepts false (turn off) or {at?: [r1, r2]} with fractions in (0, 1], r1 <= r2 (default on at 80%/95%)");
+                    return null;
+                }
+            }
         }
         // [876] per-task subagents(core 1.295 TaskSpec.agents):fresh-submit 白名单门 fail-loud。与 resilience/
         // limits 的「容忍未知键」取舍相反 —— agents 是能力定义,静默丢字段=定义被悄悄削(丢一个 denyTools/
@@ -2271,6 +2284,35 @@ export function createHttpServer(rawDeps) {
         sendError(res, 429, "quota_exhausted", "budget exhausted (quota lease)", { retryAfterSec: adm.retryAfterSec, ...(adm.detail ?? {}) });
         return true;
     }
+    /** design/166-T1 — 治理窗 pre-admission(quotaExceeded/leaseDenied 的兄弟门):key 公式与 core 单源
+     *  (`principal || GLOBAL_USAGE_KEY`,GLOBAL_USAGE_KEY 引 core 公共导出防漂移;principal=verified,
+     *  spoofable header 不进键)。窗耗尽 → 429 + retryAfterSec(族形一致,秒上取整)+ Retry-After 头。
+     *  读窗失败(DB 瞬断/坏 record)→ warn + fail-open:enforcement 真源在 core 进场检查(同店同键,
+     *  会响亮拒),此门只是异步车道的 429 快速座——门故障不该把提交面整个拖死。admission-pass 与
+     *  core entry-拒之间存在竞态窗:该形落终态 run 记录(errorCode usage.window_exhausted),契约文档在案。 */
+    async function usageWindowDenied(req, res) {
+        const store = deps.usageWindowStore;
+        const windows = deps.config.usageWindows;
+        if (!store || !windows || windows.length === 0)
+            return false;
+        const key = gatedPrincipal(req, deps.config) || GLOBAL_USAGE_KEY;
+        let retryAfterMs;
+        try {
+            retryAfterMs = usageRetryAfterMs(await store.read(key, windows, Date.now()));
+        }
+        catch (e) {
+            deps.logger?.warn?.("usage_window_admission_read_failed", { error: e instanceof Error ? e.message : String(e) });
+            return false;
+        }
+        if (retryAfterMs === undefined)
+            return false;
+        deps.metrics?.inc("usage_window_rejected_total");
+        deps.logger?.info?.("usage_window_exhausted", { hasPrincipal: key !== GLOBAL_USAGE_KEY, retryAfterMs });
+        const retryAfterSec = Math.max(1, Math.ceil(retryAfterMs / 1000));
+        res.setHeader("retry-after", String(retryAfterSec));
+        sendError(res, 429, "usage.window_exhausted", "usage window exhausted (deployment token governance)", { retryAfterSec });
+        return true;
+    }
     /** Apply the per-principal rate limit; responds 429 and returns true when the caller is over. */
     function rateLimited(req, res) {
         if (!deps.rateLimiter)

package/dist/http/wire-types.d.ts

@@ -157,10 +157,14 @@ export interface TaskRequestBody {
      *  `maxOutputTokens`/`maxTurns`,均正整数;可选运营方上限旋钮各自封顶(TASK_TIMEOUT_MAX_SEC 保**秒**义,
      *  对毫秒键封顶 ×1000)。旧键 `timeoutSec` 与 deadline 族三 opt-out(机制退役)fresh-submit 400 响亮
      *  点名替代;`maxWalltimeMs` 缺席时保持既有 tenancy 墙钟姿势(resolveTaskLimits,spec-fields.ts)。 */
+    /** 166-T3:approachNotice——core 默认 ON(80%/95% 各提示一次);false 关,{at:[r1,r2]} 调阈((0,1] 且 r1<=r2)。 */
     limits?: {
         maxWalltimeMs?: number;
         maxOutputTokens?: number;
         maxTurns?: number;
+        approachNotice?: false | {
+            at?: [number, number];
+        };
     };
     /** design/133 (core 1.251) + G1 (core 1.253): turn-boundary attachment reminders (todo / changed-files /
      *  plan-mode) + one-shot boundary notices (post-compaction background-task recap / deferred-tools delta).

package/dist/main.js

@@ -158,7 +158,7 @@ async function main() {
     await configCenter.applyLocalRemoteExec();
     // design/158 A10:持久层装配搬到 src/boot/stores.ts(逐字)。⚠️ 该段就地归一 `config.sessionBackend`
     // 且承载三条 fail-loud 拒启断言 —— 位置即契约,理由见该文件头注。
-    const { backend, storeBackendDegraded, memoryEngine, memorySyncCursors, rosterStore, backgroundAgentStore, taskAttachmentStore, mailboxStore, memoryExportBackend, memorySyncRunner, sessionStore, breakerState, } = await openStores({ config, logger, metrics, localRoot });
+    const { backend, storeBackendDegraded, memoryEngine, memorySyncCursors, rosterStore, backgroundAgentStore, taskAttachmentStore, mailboxStore, memoryExportBackend, memorySyncRunner, sessionStore, breakerState, usageWindowStore, } = await openStores({ config, logger, metrics, localRoot });
     // design/158 A10:计费/追踪/预算装配搬到 src/boot/budget-tracing.ts(逐字;tracer 与 side-query 同 sink 实例的
     // 「同段构造」契约见该文件头注)。
     const { brain, pricing, counterDegradeHook, costQuota, modelUsageTracker, promptManifestTracker, fleetUsage, fleetLease, tracer, sideQueryAccounting, toolResultStore, sessionPolicyStore, fileSnapshotStore, } = createBudgetAndTracing({ config, logger, metrics, backend, breakerState });
@@ -185,7 +185,7 @@ async function main() {
     const { principalCaps, centerRuntimeCapsResolver, runtimeCapsResolver } = createRuntimeCaps({ config, logger });
     // design/158 A10:RunnerDeps 装配段搬到 src/boot/runner-deps.ts(逐字;runStore 晚绑改取值,见该文件头注)。
     const runnerDeps = createRunnerDeps({
-        config, logger, metrics, localRoot, promptSource: configCenter.promptSource, rosterStore, backgroundAgentStore, mailboxStore, brain,
+        config, logger, metrics, localRoot, promptSource: configCenter.promptSource, rosterStore, backgroundAgentStore, mailboxStore, usageWindowStore, brain,
         pricing, tracer, outcomeSink, elicitation, question, toolApproval, sessionStore, memoryEngine,
         memorySyncRunner, toolResultStore, sessionPolicyStore, runtimeCapsResolver, fileSnapshotStore,
         executionEnvFactory, lspManager, fleetBus, deploymentHooks, workflowRunStore, workflowJournalStore,
@@ -329,6 +329,7 @@ async function main() {
             deploymentHooks,
             toolResultStore,
             sessionPolicyStore,
+            usageWindowStore,
         }),
         // ── 以下为 subRunner 差异键(不在共享基座;逐个有因)──────────────────────────────────────
         sessionStore: subRunnerSessions, // 子代转录=私有短 TTL fork 路由店,生命周期异于宿主 durable 店
@@ -800,6 +801,7 @@ async function main() {
         rateLimiter,
         costQuota,
         fleetLease: fleetLease ? fleetLease : undefined, // lease admission 门(提交面,镜像 quotaExceeded)
+        usageWindowStore: usageWindowStore ? usageWindowStore : undefined, // design/166-T1:治理窗 pre-admission(与 RunnerDeps 同店同键)
     };
     // B1 活体 store 探测环(门与判据见 store-live-probe.ts 头注;探针原语=既有 S10 dbNowMs 真 DB 往返)
     const storeLiveProbe = backend && backend.kind !== "local" && backend.dbNowMs && config.storeProbeIntervalMs > 0

package/dist/plugins/remote-env-k8s.d.ts

@@ -129,6 +129,11 @@ export declare class RemoteK8sExecutionEnv implements RemoteExecutionEnv, Backgr
     private readonly cfg;
     private readonly deps;
     constructor(config: K8sEnvConfig, deps?: K8sEnvDeps);
+    /** 166-T2 — ExecutionEnv 寿命声明:pod `activeDeadlineSeconds = ceil(timeoutMs/1000)` 是平台真硬死线
+     *  (k8s 到点杀 pod,无 keepalive 续期机制)⇒ 恒声明,core 在死线−60s 处 suspend(基建合格)或响亮
+     *  终局(env.lifetime_expired)。`lifetimeStartedAt` 有意不声明:core 只在 prepare 期读一次,lazy-connect
+     *  下 pod 尚未创建 ⇒ core 回落铸造时刻为锚——比 pod 真启动早,提早 suspend 是保守方向。 */
+    get lifetimeMs(): number;
     private resolve;
     workspaceHandle(): WorkspaceHandle;
     /** Resolved lazily so an in-cluster pod picks up its service account without explicit config. */

package/dist/plugins/remote-env-k8s.js

@@ -159,6 +159,13 @@ export class RemoteK8sExecutionEnv {
             supportsDetach: true,
         };
     }
+    /** 166-T2 — ExecutionEnv 寿命声明:pod `activeDeadlineSeconds = ceil(timeoutMs/1000)` 是平台真硬死线
+     *  (k8s 到点杀 pod,无 keepalive 续期机制)⇒ 恒声明,core 在死线−60s 处 suspend(基建合格)或响亮
+     *  终局(env.lifetime_expired)。`lifetimeStartedAt` 有意不声明:core 只在 prepare 期读一次,lazy-connect
+     *  下 pod 尚未创建 ⇒ core 回落铸造时刻为锚——比 pod 真启动早,提早 suspend 是保守方向。 */
+    get lifetimeMs() {
+        return this.cfg.timeoutMs;
+    }
     resolve(p) {
         return path.posix.isAbsolute(p) ? path.posix.normalize(p) : path.posix.normalize(path.posix.join(this.cwd, p));
     }

package/dist/plugins/usage-window-store-sql.d.ts

@@ -0,0 +1,42 @@
+/**
+ * UsageWindowStore SQL twins(design/166-T1)——core 5.8.0 部署级 token 治理窗
+ * (`RunnerDeps.usageWindows` + `usageWindowStore`)的 TiDB/PG 双方言实现。
+ *
+ * 语义单源 = core 纯函数(`chargeUsageRecord`/`readUsageRecord`,dist/core/usage-window-store.js):
+ * 本层只负责 record 的持久化与多副本并发正确性;窗算法(rolling slots 按最宽 horizon 自剪、
+ * first-use bucket lapsed 即弃)完全由 core 纯函数执行——SQL 层零窗语义。
+ *
+ * 并发正确性(本 store 的靶心;两副本同 key 并发 charge 绝不能丢账——丢账方向=治理窗漏放):
+ *  - **ensure-first + 行锁**(mailbox twin 正字先例,design/166 复审靶1):事务内先幂等
+ *    INSERT IGNORE / ON CONFLICT DO NOTHING 建空行 ⇒ SELECT ... FOR UPDATE 时行恒在,
+ *    「无行 FOR UPDATE + INSERT」的并发死锁(InnoDB gap-lock)/dup 撞车形整个消掉。
+ *  - charge 频率低(core 只在任务进场/turn 边界/收尾 delta 提交),悲观锁简单正确,不用乐观 CAS。
+ *  - `read` 无锁单 SELECT(readUsageRecord 纯函数);行缺席 = EMPTY_USAGE_WINDOW_RECORD。
+ *  - record JSON 坏形(手工污染)= **fail-loud throw**:治理窗算错=计费面撒谎,不 fail-open。
+ *
+ * 列型:record 用 MySQL 方言 LONGTEXT(rolling slots 高并发长窗可破 64K TEXT——复审新5,
+ * background-agent LONGTEXT 同案);PG TEXT 不限长。key 列 VARCHAR(190)(principal 或
+ * GLOBAL_USAGE_KEY,均为受控标识,无字节等价诉求——不是用户可写身份键)。
+ *
+ * residue(design/166 04 §复审处置在档):不再被 charge 的 key 行永存(单行成本可忽略);
+ * GLOBAL 单行=并发 charge 串一把行锁的吞吐热点(出现瓶颈再分片)。
+ */
+import type { Pool as MySqlPool } from "mysql2/promise";
+import type { Pool as PgPool } from "pg";
+import type { UsageWindow, UsageWindowReading, UsageWindowStore } from "@sema-agent/core";
+export declare const USAGE_WINDOW_TABLE = "usage_window";
+export declare function ensureTiDBUsageWindowSchema(pool: MySqlPool): Promise<void>;
+export declare function ensurePgUsageWindowSchema(q: (text: string, params?: unknown[]) => Promise<unknown>): Promise<void>;
+export declare class TiDBUsageWindowStore implements UsageWindowStore {
+    private readonly pool;
+    constructor(pool: MySqlPool);
+    charge(key: string, tokens: number, at: number, windows: readonly UsageWindow[]): Promise<void>;
+    read(key: string, windows: readonly UsageWindow[], now: number): Promise<readonly UsageWindowReading[]>;
+}
+export declare class PgUsageWindowStore implements UsageWindowStore {
+    private readonly pool;
+    constructor(pool: PgPool);
+    charge(key: string, tokens: number, at: number, windows: readonly UsageWindow[]): Promise<void>;
+    read(key: string, windows: readonly UsageWindow[], now: number): Promise<readonly UsageWindowReading[]>;
+}
+//# sourceMappingURL=usage-window-store-sql.d.ts.map

package/dist/plugins/usage-window-store-sql.js

@@ -0,0 +1,113 @@
+import { EMPTY_USAGE_WINDOW_RECORD, chargeUsageRecord, readUsageRecord } from "@sema-agent/core";
+export const USAGE_WINDOW_TABLE = "usage_window";
+/** record 列 → UsageWindowRecord。坏形 fail-loud(治理窗算错=计费面撒谎;与快照/凭据类 store 的
+ *  onCorruptRead 披露座不同族——这里没有「跳过一行继续」的安全语义,账本坏=停)。 */
+function parseRecord(raw, key) {
+    let v;
+    try {
+        v = JSON.parse(String(raw));
+    }
+    catch (e) {
+        throw new Error(`usage_window record for key "${key}" is not valid JSON (${String(e)}) — refusing to mis-count a governance window`);
+    }
+    const r = v;
+    if (typeof v !== "object" || v === null || !Array.isArray(r.slots) || !Array.isArray(r.buckets)) {
+        throw new Error(`usage_window record for key "${key}" has an invalid shape (expected {slots[],buckets[]}) — refusing to mis-count a governance window`);
+    }
+    return v;
+}
+export async function ensureTiDBUsageWindowSchema(pool) {
+    await pool.query(`CREATE TABLE IF NOT EXISTS ${USAGE_WINDOW_TABLE} (
+    k VARCHAR(190) NOT NULL,
+    record LONGTEXT NOT NULL,
+    updated_at_ms BIGINT NOT NULL,
+    PRIMARY KEY (k)
+  ) COLLATE utf8mb4_bin`);
+}
+export async function ensurePgUsageWindowSchema(q) {
+    await q(`CREATE TABLE IF NOT EXISTS ${USAGE_WINDOW_TABLE} (
+    k VARCHAR(190) NOT NULL,
+    record TEXT NOT NULL,
+    updated_at_ms BIGINT NOT NULL,
+    PRIMARY KEY (k)
+  )`);
+}
+export class TiDBUsageWindowStore {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    async charge(key, tokens, at, windows) {
+        const c = await this.pool.getConnection();
+        try {
+            await c.beginTransaction();
+            // ensure-first:幂等建空行(EMPTY record)⇒ 下一步 FOR UPDATE 行恒在(锁语义干净,无 gap-lock 死锁形)。
+            await c.query(`INSERT IGNORE INTO ${USAGE_WINDOW_TABLE} (k, record, updated_at_ms) VALUES (?, ?, ?)`, [
+                key,
+                JSON.stringify(EMPTY_USAGE_WINDOW_RECORD),
+                at,
+            ]);
+            const [rows] = (await c.query(`SELECT record FROM ${USAGE_WINDOW_TABLE} WHERE k = ? FOR UPDATE`, [key]));
+            if (rows.length === 0) {
+                // 本表无删除臂(不同于 mailbox 的 drop/reap),ensure 后空 = 真障碍 fail-loud。
+                throw new Error(`usage_window row for key "${key}" vanished between ensure and lock — refusing to drop a governance charge`);
+            }
+            const record = parseRecord(rows[0].record, key);
+            const next = chargeUsageRecord(record, tokens, at, windows);
+            await c.query(`UPDATE ${USAGE_WINDOW_TABLE} SET record = ?, updated_at_ms = ? WHERE k = ?`, [JSON.stringify(next), at, key]);
+            await c.commit();
+        }
+        catch (e) {
+            await c.rollback().catch(() => { });
+            throw e;
+        }
+        finally {
+            c.release();
+        }
+    }
+    async read(key, windows, now) {
+        const [rows] = (await this.pool.query(`SELECT record FROM ${USAGE_WINDOW_TABLE} WHERE k = ?`, [key]));
+        const record = rows.length === 0 ? EMPTY_USAGE_WINDOW_RECORD : parseRecord(rows[0].record, key);
+        return readUsageRecord(record, windows, now);
+    }
+}
+export class PgUsageWindowStore {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    async charge(key, tokens, at, windows) {
+        const c = await this.pool.connect();
+        try {
+            await c.query("BEGIN");
+            // ensure-first(TiDB 同注):ON CONFLICT DO NOTHING 幂等建空行,再锁——插入不带锁,锁只从
+            // FOR UPDATE 来(复审靶1 的 PG 交错:并发首充双双 ensure,后到方 DO NOTHING 后必须真锁行)。
+            await c.query(`INSERT INTO ${USAGE_WINDOW_TABLE} (k, record, updated_at_ms) VALUES ($1, $2, $3) ON CONFLICT (k) DO NOTHING`, [
+                key,
+                JSON.stringify(EMPTY_USAGE_WINDOW_RECORD),
+                at,
+            ]);
+            const { rows } = await c.query(`SELECT record FROM ${USAGE_WINDOW_TABLE} WHERE k = $1 FOR UPDATE`, [key]);
+            if (rows.length === 0) {
+                throw new Error(`usage_window row for key "${key}" vanished between ensure and lock — refusing to drop a governance charge`);
+            }
+            const record = parseRecord(rows[0].record, key);
+            const next = chargeUsageRecord(record, tokens, at, windows);
+            await c.query(`UPDATE ${USAGE_WINDOW_TABLE} SET record = $1, updated_at_ms = $2 WHERE k = $3`, [JSON.stringify(next), at, key]);
+            await c.query("COMMIT");
+        }
+        catch (e) {
+            await c.query("ROLLBACK").catch(() => { });
+            throw e;
+        }
+        finally {
+            c.release();
+        }
+    }
+    async read(key, windows, now) {
+        const { rows } = await this.pool.query(`SELECT record FROM ${USAGE_WINDOW_TABLE} WHERE k = $1`, [key]);
+        const record = rows.length === 0 ? EMPTY_USAGE_WINDOW_RECORD : parseRecord(rows[0].record, key);
+        return readUsageRecord(record, windows, now);
+    }
+}
+//# sourceMappingURL=usage-window-store-sql.js.map

package/dist/resource-suspend.d.ts

@@ -6,7 +6,7 @@
  * `POST /v1/assistant/tasks/:id/resume`) instead of FAILING; absent ⇒ a limit still FAILS.
  *
  * 🔴 EXCLUDE verify/cascade tasks. Core runs their implementation via `runWithVerification`/`runCascade`, which
- * map an inner durable suspend to a FAILED result (`errorCode: "unexpected.suspended"`). The service would then
+ * map an inner durable suspend to a FAILED result (`errorCode: "suspended.awaiting_approval"`,core 5.9.0 W1 改名). The service would then
  * `setTerminal(failed)` while core had already minted a pending `resource_limit` checkpoint + suspended the
  * remote VM — ORPHANING both (the run row is terminal, so nothing resumes them). So a resource-limit hit on a
  * verify/cascade task must FAIL CLEANLY (no suspend), exactly as before the flag. This exclusion is the SAME

package/dist/resource-suspend.js

@@ -6,7 +6,7 @@
  * `POST /v1/assistant/tasks/:id/resume`) instead of FAILING; absent ⇒ a limit still FAILS.
  *
  * 🔴 EXCLUDE verify/cascade tasks. Core runs their implementation via `runWithVerification`/`runCascade`, which
- * map an inner durable suspend to a FAILED result (`errorCode: "unexpected.suspended"`). The service would then
+ * map an inner durable suspend to a FAILED result (`errorCode: "suspended.awaiting_approval"`,core 5.9.0 W1 改名). The service would then
  * `setTerminal(failed)` while core had already minted a pending `resource_limit` checkpoint + suspended the
  * remote VM — ORPHANING both (the run row is terminal, so nothing resumes them). So a resource-limit hit on a
  * verify/cascade task must FAIL CLEANLY (no suspend), exactly as before the flag. This exclusion is the SAME

package/dist/runs.d.ts

@@ -168,7 +168,7 @@ export declare class TurnAnchorCapture {
  * Strip the durable-resume capability token from a result before it is persisted to the replayable event
  * log / run row or returned to the submitter. The token IS the resume credential (token-as-auth, search
  * [18] Q1b) and must never leave the service. Safe on any result (no-op when absent) — notably core maps a
- * NESTED suspend under verify/cascade to status:"failed" + errorCode "unexpected.suspended" while still
+ * NESTED suspend under verify/cascade to status:"failed" + errorCode "suspended.awaiting_approval"(core 5.9.0 W1 改名)while still
  * spreading `checkpointToken`, so that "failed" path (unlike the stream path's explicit suspend handling)
  * would otherwise leak it into task_event / task_run.result / the sync 200 response. `checkpointGate` is
  * non-secret and intentionally kept.

package/dist/runs.js

@@ -237,7 +237,7 @@ export class TurnAnchorCapture {
  * Strip the durable-resume capability token from a result before it is persisted to the replayable event
  * log / run row or returned to the submitter. The token IS the resume credential (token-as-auth, search
  * [18] Q1b) and must never leave the service. Safe on any result (no-op when absent) — notably core maps a
- * NESTED suspend under verify/cascade to status:"failed" + errorCode "unexpected.suspended" while still
+ * NESTED suspend under verify/cascade to status:"failed" + errorCode "suspended.awaiting_approval"(core 5.9.0 W1 改名)while still
  * spreading `checkpointToken`, so that "failed" path (unlike the stream path's explicit suspend handling)
  * would otherwise leak it into task_event / task_run.result / the sync 200 response. `checkpointGate` is
  * non-secret and intentionally kept.

package/dist/spec-fields.d.ts

@@ -102,6 +102,14 @@ export declare function normalizeLimits(v: unknown, caps: TaskLimitCaps): {
     maxWalltimeMs?: number;
     maxOutputTokens?: number;
     maxTurns?: number;
+    approachNotice?: false | {
+        at?: [number, number];
+    };
+} | undefined;
+/** 166-T3 — approachNotice 单键归一(normalizeLimits/HTTP 门共用判据源):合法 ⇒ 归一值,坏形 ⇒ undefined。
+ *  阈值规则对齐 core(prepare-task at 校验):二元组、(0,1] 有限数、a<=b(允许相等)。 */
+export declare function normalizeApproachNotice(raw: unknown): false | {
+    at?: [number, number];
 } | undefined;
 /**
  * [854]④ — body.limits 与 env 墙钟的合成规则(resolveSpec 的唯一 limits 装配点;run-local 无 body 车道不经此):

package/dist/spec-fields.js

@@ -374,9 +374,28 @@ export function normalizeLimits(v, caps) {
         ...(() => { const n = pick(o.maxWalltimeMs, caps.timeoutSec !== undefined ? caps.timeoutSec * 1000 : undefined); return n !== undefined ? { maxWalltimeMs: n } : {}; })(),
         ...(() => { const n = pick(o.maxOutputTokens, caps.maxOutputTokens); return n !== undefined ? { maxOutputTokens: n } : {}; })(),
         ...(() => { const n = pick(o.maxTurns, caps.maxTurns); return n !== undefined ? { maxTurns: n } : {}; })(),
+        // 166-T3:approachNotice(core 默认 ON;false=唯一关闭形,{at:[a,b]} 调阈,core 允 a<=b)。坏形整键
+        // DROP(降级为 core 默认阈,方向安全)——不 throw,resume 重放通道同门。
+        ...(() => { const n = normalizeApproachNotice(o.approachNotice); return n !== undefined ? { approachNotice: n } : {}; })(),
     };
     return Object.keys(out).length > 0 ? out : undefined;
 }
+/** 166-T3 — approachNotice 单键归一(normalizeLimits/HTTP 门共用判据源):合法 ⇒ 归一值,坏形 ⇒ undefined。
+ *  阈值规则对齐 core(prepare-task at 校验):二元组、(0,1] 有限数、a<=b(允许相等)。 */
+export function normalizeApproachNotice(raw) {
+    if (raw === false)
+        return false;
+    if (raw == null || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const at = raw.at;
+    if (at === undefined)
+        return {};
+    if (!Array.isArray(at) || at.length !== 2)
+        return undefined;
+    const [a, b] = at;
+    const frac = (n) => typeof n === "number" && Number.isFinite(n) && n > 0 && n <= 1;
+    return frac(a) && frac(b) && a <= b ? { at: [a, b] } : undefined;
+}
 /**
  * [854]④ — body.limits 与 env 墙钟的合成规则(resolveSpec 的唯一 limits 装配点;run-local 无 body 车道不经此):
  *  - `timeoutSec`:body 给了就用 body(caller 明确配速;已在 normalizeLimits 里被 TASK_TIMEOUT_MAX_SEC 封顶)。

package/dist/tool-approval.d.ts

@@ -26,6 +26,14 @@ export interface ToolApprovalFrame {
     /** [1550] 展示身份(子代 agent 名)——UNTRUSTED-for-display(core 未做秘密脱敏)→ redactSecrets 后渲。
      *  仅子代 ask 上可能在场(core 未必总能解析出名字)。 */
     sourceAgentName?: string;
+    /** core 5.9.0 W1([2535]):审批上浮的出处链——{parentToolCallId, depth, agentName?}(孙代最内层帧
+     *  胜出)。只读展示增强(cli [2516] 验收形=审批卡带子代出处);agentName UNTRUSTED → redactSecrets。
+     *  只在子代 ask 上在场(与 fromSubagent 同门)。 */
+    delegation?: {
+        parentToolCallId: string;
+        depth: number;
+        agentName?: string;
+    };
     message?: string;
     /** "tool_approval" only: the tool call's args, secret-redacted, UNTRUSTED-for-display. Absent (with
      *  `argsOmitted: true`) when over the byte cap or unserializable. */

package/dist/tool-approval.js

@@ -329,6 +329,16 @@ export class ToolApprovalCoordinator {
                     sourceTaskId: req.sourceTaskId,
                     fromSubagent: true,
                     ...(typeof req.sourceAgentName === "string" ? { sourceAgentName: redactSecrets(req.sourceAgentName) } : {}),
+                    // core 5.9.0 W1:出处链透传(agentName 同 sourceAgentName 待遇 redact;其余为 core-mint 标识非内容)。
+                    ...(req.delegation
+                        ? {
+                            delegation: {
+                                parentToolCallId: req.delegation.parentToolCallId,
+                                depth: req.delegation.depth,
+                                ...(typeof req.delegation.agentName === "string" ? { agentName: redactSecrets(req.delegation.agentName) } : {}),
+                            },
+                        }
+                        : {}),
                 }
                 : {}),
             message: typeof req.message === "string" ? redactDeep(req.message) : "",

package/dist/trace/core-keyset-guard.d.ts

@@ -25,7 +25,7 @@ type BgNotifExcluded = "kind" | "sessionScoped" | "owner" | "scope" | "descripti
 type _GuardBgNotif = AssertAllKeysHandled<Exclude<keyof BackgroundChildEvent, BgNotifProjected | BgNotifExcluded>>;
 type RosterProjected = "name" | "agentId" | "sessionId" | "toolUseId" | "owner" | "scope" | "sessionScoped" | "rootSessionId" | "model" | "createdAt";
 type _GuardRoster = AssertAllKeysHandled<Exclude<keyof RosterEntry, RosterProjected>>;
-type AskProjected = "toolName" | "args" | "message" | "sourceTaskId" | "fromSubagent" | "sourceAgentName";
+type AskProjected = "toolName" | "args" | "message" | "sourceTaskId" | "fromSubagent" | "sourceAgentName" | "delegation";
 type AskExcluded = "toolCallId" | "preview" | "principal" | "requiresRealApproval";
 type _GuardAsk = AssertAllKeysHandled<Exclude<keyof AskRequest, AskProjected | AskExcluded>>;
 type TaskEventHandled = "text_delta" | "reasoning_delta" | "tool_start" | "tool_end" | "turn_end" | "compacted" | "diagnostics" | "message_committed" | "status" | "task_notification" | "task_progress" | "steering_injected" | "workspace_changed" | "done" | "context_usage" | "compaction_outcome";

package/dist/trace/project.d.ts

@@ -129,6 +129,7 @@ export declare function toolEndEventData(ev: {
     truncated?: boolean;
     totalChars?: number;
     structured?: unknown;
+    errorCode?: string;
     eventId?: string;
     parentToolCallId?: string;
 }): Record<string, unknown>;

package/dist/trace/project.js

@@ -156,6 +156,9 @@ export function toolEndEventData(ev) {
         // core 1.442([1898] RB-210):截断诚实体量(各 block 真实大小之和,不含 JSON 包装开销)。
         ...(Number.isFinite(ev.totalChars) ? { totalChars: ev.totalChars } : {}),
         ...(ev.structured !== undefined ? { structured: redactDeep(ev.structured) } : {}),
+        // core 5.9.0 W3([2535]):park/死投影结构化标记(引擎闭词表 `gate.parked`/`tool.not_found`,只在
+        // isError 时在场)——verbatim 透传,壳按它判别 park 毒化帧而不锚 abort 文案字面。
+        ...(typeof ev.errorCode === "string" ? { errorCode: ev.errorCode } : {}),
         ...identityFields(ev),
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "6.0.0",
+  "version": "6.2.0",
   "description": "Sema Server — the server/API implementation layer for Sema, wiring core, registry, model providers, and cloud agent execution. Built on @sema-agent/core.",
   "type": "module",
   "license": "BUSL-1.1",
@@ -54,7 +54,7 @@
     "build:binary:run-local:darwin-arm64": "bun build --compile --target=bun-darwin-arm64 src/run-local.ts --outfile dist/run-local-darwin-arm64"
   },
   "dependencies": {
-    "@sema-agent/core": "^5.8.0",
+    "@sema-agent/core": "^5.9.0",
     "@sema-agent/registry-core": "^0.14.0",
     "e2b": "^2.28.0",
     "libsodium-wrappers": "^0.8.4",
@@ -68,7 +68,7 @@
     "sharp": "^0.35.3"
   },
   "devDependencies": {
-    "@sema-agent/sdk": "^5.2.0",
+    "@sema-agent/sdk": "^6.1.0",
     "@types/libsodium-wrappers": "^0.7.14",
     "@types/node": "22.10.2",
     "@types/pg": "^8.20.0",