@sema-agent/server 7.37.0 → 7.38.0-rc.2

package/dist/main.js

@@ -51,6 +51,7 @@ import { openStores } from "./boot/stores.js";
 import { runAdoptionBootScan } from "./boot/adoption.js";
 import { auditDormantPermissionRules } from "./boot/permission-rules-audit.js";
 import { createBudgetAndTracing } from "./boot/budget-tracing.js";
+import { createLimitSync } from "./boot/limit-sync.js"; // #322 批1:限额座的换代口(恒构造 + 关断哨兵)
 import { createSideQueryLane } from "./boot/side-query-lane.js";
 import { createWebFetchSummarizeLane } from "./boot/webfetch-summarize-lane.js";
 import { createRuleConsentLane } from "./rules-consent.js";
@@ -113,12 +114,17 @@ function serviceVersion() {
  */
 async function main() {
     const config = loadConfig();
+    // ── CROSS-INVARIANT-REGION:begin ────────────────────────────────────────────────────────────────
     // Liveness invariant: the running instance refreshes updated_at every HEARTBEAT_MS; the reaper fails
     // a run whose updated_at is older than runStaleSec. If the stale window were ≤ the heartbeat, the
     // reaper would race a perfectly alive run. Fail fast on a misconfiguration instead of reaping live work.
+    // #322:判据本体已搬进 `config-invariants.ts` 的单源表 —— 热路径(config-center stage)跑的是**同一条**,
+    // 所以一个过小的 runStaleSec 既不能从 env 起服,也不能从中心热发布进来(禁手抄第二份判据)。
     if (config.runStaleSec * 1000 <= HEARTBEAT_MS) {
+        // CROSS-INVARIANT:run-stale-heartbeat
         throw new Error(`REAP_RUN_STALE_SEC (${config.runStaleSec}s) must exceed the ${HEARTBEAT_MS / 1000}s liveness heartbeat`);
     }
+    // ── CROSS-INVARIANT-REGION:end ──────────────────────────────────────────────────────────────────
     const logger = createLogger(config.logLevel);
     const metrics = createMetrics();
     // #157 fail-open 治理:把 logger/metrics 接到进程级 failOpen 记录器上(见 observability/fail-open.ts)。
@@ -735,11 +741,13 @@ async function main() {
         logger.warn("multi_tenant_no_service_token", { detail: "REQUIRE_PRINCIPAL is on but no SERVICE_AUTH_TOKEN/authTokens/TRACE_TOKEN — fleet/trace/session-list are owner-gated only (never fleet-wide, tenant-isolation safe). Set a token for cross-tenant ops visibility." });
     // Rate limiter: TiDB-backed (cross-replica SOFT limit, same write-behind counter as the cost quota)
     // when a pool exists, else in-memory per-replica. Both satisfy RateGate. (design/30 P0-2)
-    const rateLimiter = config.rateLimitPerMin > 0
-        ? backend?.rateLimiter // local omits rateLimiter() → in-memory per-process RateLimiter (single-replica)
-            ? backend.rateLimiter(config.rateLimitPerMin, counterDegradeHook).startRefresh()
-            : new RateLimiter(config.rateLimitPerMin)
-        : undefined;
+    //
+    // 🔴 #322 批1:与 costQuota 同一条改造(恒构造 + 0=关断哨兵)——修前 `rateLimitPerMin > 0` 才构造,
+    // 默认部署零实例,于是热改 0→N 无座可 set。恒构造之后 0↔N 是纯值变(boot/limit-sync.ts 一次 setLimits),
+    // 关断态由座位自己表达:恒放行、不记窗、SQL 腿不起刷新环(零 SQL)。
+    const rateLimiter = backend?.rateLimiter // local omits rateLimiter() → in-memory per-process RateLimiter (single-replica)
+        ? backend.rateLimiter(config.rateLimitPerMin, counterDegradeHook).startRefresh()
+        : new RateLimiter(config.rateLimitPerMin);
     // Capability layer: scenario → {tools (+ subagent roster), prompt, skills}. Heavy bits (skills,
     // git client) are built ONCE here; per request we only select a scenario and bind coordinates.
     let skills = loadSkills(config.skillsDir);
@@ -933,7 +941,36 @@ async function main() {
         : undefined;
     // design/158 A10 尾刀:60s refresh 循环 + boot-deferred 到货续接搬到 boot/config-center.ts(逐字)。
     // ⚠️ 位置即契约:必须在 new Runner 之后 —— runnerTierFrozen 与构造函数读的是同一 config 代际。
-    configCenter.startRefreshLoop({ runnerTierFrozen, pricing });
+    // #322 批1:限额座的换代口(恒构造的两只座 —— rateLimiter 上面建、costQuota 在 budget-tracing 段建)。
+    // boot 期先 sync 一次:让「上一代读数」落位,于是第一次真变更才会留 `limit_gates_reloaded` 那一行。
+    const limitSync = createLimitSync({ config, rateGate: rateLimiter, quota: costQuota, logger });
+    limitSync.sync();
+    // core 5.49 `Runner.swapModels` 接缝([4775]①,models-tiers defer 臂退役):plane 候选在 commit 前
+    // 喂给**全部** boot 单例 Runner 原子换代。五实例必须同代——swap 替代 restart 后,漏换的长命 Runner
+    // 会永久停在旧代(比 defer+restart 更糟);leader lane 的 Runner 是逐调用现构(读 config.models 活
+    // 引用),不在此列。校验对同一候选输入是确定性的:首个 swap 抛 ⇒ 零实例换装、候选整拒;首个成功后
+    // 后继实例抛=结构性不可达,若真发生则 error 留痕后照抛(下一拍幂等重 swap 收敛)。
+    const bootRunners = [
+        ["runner", runner],
+        ["handsless", handslessRunner],
+        ["hookAgent", hookAgentRunner],
+        ["sub", subRunner],
+        ["handslessSub", handslessSubRunner],
+    ];
+    const swapRunnerModels = (plane) => {
+        for (let i = 0; i < bootRunners.length; i++) {
+            const [name, rn] = bootRunners[i];
+            try {
+                rn.swapModels({ models: plane.models, tiers: plane.tiers });
+            }
+            catch (err) {
+                if (i > 0)
+                    logger.error("model_plane_swap_split", { failedAt: name, swapped: bootRunners.slice(0, i).map(([n]) => n), err: String(err) });
+                throw err;
+            }
+        }
+    };
+    configCenter.startRefreshLoop({ runnerTierFrozen, pricing, limitSync, swapRunnerModels });
     // design/158 A10 尾刀:per-model key resolver 首建(+ Bearer 网关组合告警)搬到 boot/config-center.ts。
     // ⚠️ 位置即契约:首建读的必须是 boot apply **之后**的 config.modelApiKeyEnv/modelApiKeys。
     configCenter.initKeyResolver();
@@ -989,6 +1026,10 @@ async function main() {
         sessionDurability: staticWiring.session.store,
         posture: staticWiring.interaction.posture,
         streamApproval: streamApprovalGate.active ? "active" : streamApprovalGate.reason,
+        // debt #292-manifest:C18 部署级读数上 operator 日志——`full` = agent 行店在线 ∧ session 店
+        // 声明 subagent placement 分区 durable(ForkRoutingSessionStore 从 host 透传声明)。诊断端点
+        // GET /v1/diagnostics/wiring 携带全量 manifest,这里只投这枚部署级结论。
+        subagentTranscripts: staticWiring.fleet.subagentTranscripts,
     });
     // ═══════════ design/158 A8:ServiceDeps 分组装配(七组窄接口)═══════════
     // 每组一个**带类型标注**的中间 const —— 标注位触发 TS 多余属性检查,键放错组当场编译红。
@@ -1160,6 +1201,8 @@ async function main() {
         // pull's restart-to-apply slices differ from boot. A live getter (not a snapshot) so /health always reads current.
         restartState: () => configCenter.restartState(),
         planeDeferredState: () => configCenter.planeDeferredState(), // codex R18: /health.modelPlaneDeferred (stuck-deferred plane, no handoff)
+        configApplyState: () => configCenter.configApplyState(), // #322 世代账:/health 三键 + 诊断 configApply 段(同一份读数)
+        configRefreshNow: () => configCenter.refreshNow(), // #322 追加件:POST /v1/admin/config/refresh(触发既有拍,在飞则 join)
         // shared drain state — SIGTERM flips `draining`, createServer assigns `inflight`, /health mirrors it.
         drainState,
         storeDegraded: storeBackendDegraded, // S5: /health twin of the store_backend_degraded gauge

package/dist/memory-sync.js

@@ -34,7 +34,7 @@
 //
 // putCursor 失败于 applyPatches 之后 = 补丁已落、游标陈旧:向上抛(路由 500),客户端按同一
 // baseRevs 重放即幂等自愈(identical revs 全程 no-op)——游标写不是本轮正确性的一部分。
-import { computeEntryRev, nextSyncBaseline, reconcileMemoryEntries, screenInboundEntries, } from "@sema-agent/core";
+import { computeEntryRev, MEMORY_ORIGIN_CAUSES, nextSyncBaseline, reconcileMemoryEntries, screenInboundEntries, } from "@sema-agent/core";
 import { exportMemoryScope } from "./memory-export.js";
 // ── 验型(HTTP 面的 422 判据;返回 error 字符串而非 throw——validateUserSkills 姿势) ──────────
 /** 一轮 push 的条目数上限 = core REMOTE_HARVEST_MAX_FILES 同款口径(一个 scope 的文件面上限 500;
@@ -99,6 +99,41 @@ export function parseMemorySyncRequest(body, scope) {
         if (fm["extra"] !== undefined && !(Array.isArray(fm["extra"]) && fm["extra"].every((s) => typeof s === "string"))) {
             return { ok: false, error: "entry.frontmatter.extra must be an array of strings when present" };
         }
+        // #323([4769]):三只 provenance 载体入白名单——修前这里静默剥掉 origin/trust/provenance,
+        // 带标条目过 sync wire 即丢标(污染追踪断链)、rev 恒假冲突(client 以含标载体算 rev),且
+        // 「typed origin + 冲突 extra 块」的歧义表示被选择性改写成非歧义形绕过 core 的
+        // ambiguousOriginRepresentation 拒绝门(applyPatches 直调路径拒、sync 路径放行=同法两答)。
+        // 修=pick+闭集验形(照 core MemoryEntryFrontmatter 单源形),坏形响亮拒;歧义**判定**刻意不在
+        // 这里重复——保真透传后 core 受理门(clause 31)与 sync 路径同答([4770] core 已确认零改动)。
+        const rawOrigin = fm["origin"];
+        if (rawOrigin !== undefined) {
+            if (rawOrigin === null || typeof rawOrigin !== "object" || Array.isArray(rawOrigin))
+                return { ok: false, error: "entry.frontmatter.origin must be an object { taint, at, cause? } when present" };
+            const o = rawOrigin;
+            if (o["taint"] !== "external")
+                return { ok: false, error: 'entry.frontmatter.origin.taint must be the literal "external"' };
+            if (typeof o["at"] !== "number" || !Number.isFinite(o["at"]))
+                return { ok: false, error: "entry.frontmatter.origin.at must be a finite number (ms epoch)" };
+            if (o["cause"] !== undefined && !MEMORY_ORIGIN_CAUSES.includes(o["cause"])) {
+                return { ok: false, error: `entry.frontmatter.origin.cause must be one of ${JSON.stringify(MEMORY_ORIGIN_CAUSES)} when present` };
+            }
+        }
+        if (fm["trust"] !== undefined && fm["trust"] !== "untrusted")
+            return { ok: false, error: 'entry.frontmatter.trust must be the literal "untrusted" when present (single-value union — there is no trusted spelling)' };
+        const rawProv = fm["provenance"];
+        if (rawProv !== undefined) {
+            if (rawProv === null || typeof rawProv !== "object" || Array.isArray(rawProv))
+                return { ok: false, error: "entry.frontmatter.provenance must be an object { kind, path, contentHash, ingestedAt } when present" };
+            const p = rawProv;
+            if (p["kind"] !== "repo_file")
+                return { ok: false, error: 'entry.frontmatter.provenance.kind must be the literal "repo_file"' };
+            if (typeof p["path"] !== "string" || p["path"].length === 0)
+                return { ok: false, error: "entry.frontmatter.provenance.path must be a non-empty string" };
+            if (typeof p["contentHash"] !== "string" || p["contentHash"].length === 0)
+                return { ok: false, error: "entry.frontmatter.provenance.contentHash must be a non-empty string" };
+            if (typeof p["ingestedAt"] !== "number" || !Number.isFinite(p["ingestedAt"]))
+                return { ok: false, error: "entry.frontmatter.provenance.ingestedAt must be a finite number (ms epoch)" };
+        }
         entries.push({
             id: e["id"],
             slug: e["slug"],
@@ -110,6 +145,20 @@ export function parseMemorySyncRequest(body, scope) {
                 ...(fm["description"] !== undefined ? { description: fm["description"] } : {}),
                 ...(fm["type"] !== undefined ? { type: fm["type"] } : {}),
                 ...(fm["deleted"] !== undefined ? { deleted: fm["deleted"] } : {}),
+                // #323:三载体保真重建(pick,不 spread——上面已闭集验形;origin 逐成员重建防原对象带私货键)
+                ...(rawOrigin !== undefined
+                    ? {
+                        origin: {
+                            taint: "external",
+                            at: rawOrigin.at,
+                            ...(rawOrigin.cause !== undefined ? { cause: rawOrigin.cause } : {}),
+                        },
+                    }
+                    : {}),
+                ...(fm["trust"] !== undefined ? { trust: "untrusted" } : {}),
+                ...(rawProv !== undefined
+                    ? { provenance: { kind: "repo_file", path: rawProv.path, contentHash: rawProv.contentHash, ingestedAt: rawProv.ingestedAt } }
+                    : {}),
                 ...(fm["extra"] !== undefined ? { extra: [...fm["extra"]] } : {}),
             },
         });

package/dist/observability/cost-quota.d.ts

@@ -20,17 +20,37 @@ export interface QuotaDecision {
 /** The hot-path surface shared by the in-memory {@link CostQuota} (single replica) and the cross-replica
  *  {@link import("../plugins/tidb-cost-quota.js").TiDBCostQuota}. `key` is opaque (principal today;
  *  principal/team/feature later — design/30 N3), so both stores are key-based. */
+/** #322 批1:配额的**值换代**入参(四实现类同一形;单位与构造参数一致 —— USD/秒 → micro/ms 的换算
+ *  只有一处,`boot/limit-sync.ts` 的 `buildQuotaBounds`)。`limitMicroUsd <= 0` = **关断哨兵**。 */
+export interface QuotaLimits {
+    limitMicroUsd: number;
+    windowMs: number;
+}
 export interface QuotaTracker {
     check(key: string): QuotaDecision;
     add(key: string, micro: number): void;
+    /** #322:值换代座位。**接口级**声明——新实现漏掉它 = 编译红,而不是热更新在那条腿上静默失效。 */
+    setLimits(next: QuotaLimits): void;
 }
 export declare class CostQuota implements QuotaTracker {
-    private readonly limitMicroUsd;
-    private readonly windowMs;
     private readonly now;
     private windows;
-    /** @param limitMicroUsd ceiling per window (integer micro-USD). @param windowMs rolling window. */
+    /** 🔴 不再 `readonly`:限额/窗长是比较参数,换代只动它们,窗内已累计的花费一个不动(design/322 §5)。 */
+    private limitMicroUsd;
+    private windowMs;
+    /** @param limitMicroUsd ceiling per window (integer micro-USD; `<=0` = OFF sentinel). @param windowMs rolling window. */
     constructor(limitMicroUsd: number, windowMs: number, now?: () => number);
+    /**
+     * 值换代。两件事**语义不同**,别混:
+     *  · **限额**换代 = 纯比较参数 ⇒ 窗内已累计的花费一个不动(design/322 §5 定案:调小当场更严)。
+     *  · **窗长**换代 = 换**记账周期** ⇒ 当代累计重开。
+     *
+     * 🔴 后者是 codex R1-F4(真 finding,红先):SQL 腿的窗长是**桶键的一部分**(`floor(now/windowMs)`),
+     * 换窗长后当代桶天然重算 ⇒ 已累计不跟着搬家;内存腿修前却保留原窗口累计。于是**同一条发布**在
+     * 内存部署上继续拒绝超额 principal、在 PG/TiDB 部署上重新放行一整个额度 —— 后端相关的成本 fail-open。
+     * 统一取 SQL 腿那一侧(唯一能在两条腿上都实现的语义:SQL 侧无法把旧桶累计搬进新桶)。
+     */
+    setLimits(next: QuotaLimits): void;
     /** Is this principal under quota right now? (Reads only — does not consume.) */
     check(key: string): QuotaDecision;
     /** Add spend for a principal, starting a fresh window if the prior one expired. */

package/dist/observability/cost-quota.js

@@ -1,16 +1,37 @@
 export class CostQuota {
-    limitMicroUsd;
-    windowMs;
     now;
     windows = new Map();
-    /** @param limitMicroUsd ceiling per window (integer micro-USD). @param windowMs rolling window. */
+    /** 🔴 不再 `readonly`:限额/窗长是比较参数,换代只动它们,窗内已累计的花费一个不动(design/322 §5)。 */
+    limitMicroUsd;
+    windowMs;
+    /** @param limitMicroUsd ceiling per window (integer micro-USD; `<=0` = OFF sentinel). @param windowMs rolling window. */
     constructor(limitMicroUsd, windowMs, now = () => Date.now()) {
+        this.now = now;
         this.limitMicroUsd = limitMicroUsd;
         this.windowMs = windowMs;
-        this.now = now;
+    }
+    /**
+     * 值换代。两件事**语义不同**,别混:
+     *  · **限额**换代 = 纯比较参数 ⇒ 窗内已累计的花费一个不动(design/322 §5 定案:调小当场更严)。
+     *  · **窗长**换代 = 换**记账周期** ⇒ 当代累计重开。
+     *
+     * 🔴 后者是 codex R1-F4(真 finding,红先):SQL 腿的窗长是**桶键的一部分**(`floor(now/windowMs)`),
+     * 换窗长后当代桶天然重算 ⇒ 已累计不跟着搬家;内存腿修前却保留原窗口累计。于是**同一条发布**在
+     * 内存部署上继续拒绝超额 principal、在 PG/TiDB 部署上重新放行一整个额度 —— 后端相关的成本 fail-open。
+     * 统一取 SQL 腿那一侧(唯一能在两条腿上都实现的语义:SQL 侧无法把旧桶累计搬进新桶)。
+     */
+    setLimits(next) {
+        this.limitMicroUsd = next.limitMicroUsd;
+        if (next.windowMs !== this.windowMs) {
+            this.windowMs = next.windowMs;
+            this.windows.clear();
+        }
     }
     /** Is this principal under quota right now? (Reads only — does not consume.) */
     check(key) {
+        // 关断哨兵:零窗表访问,如实报 `limitMicroUsd: 0`(消费方据此知道「本部署此刻没有 ceiling」)。
+        if (this.limitMicroUsd <= 0)
+            return { allowed: true, usedMicroUsd: 0, limitMicroUsd: 0, retryAfterSec: 0 };
         const t = this.now();
         const w = this.windows.get(key);
         const live = w && t - w.start < this.windowMs;
@@ -21,6 +42,8 @@ export class CostQuota {
     }
     /** Add spend for a principal, starting a fresh window if the prior one expired. */
     add(key, micro) {
+        if (this.limitMicroUsd <= 0)
+            return; // 关断哨兵:不为一个不存在的门攒内存(0→N 打开时是全新的窗口)
         if (micro <= 0)
             return;
         const t = this.now();

package/dist/observability/fail-open.d.ts

@@ -13,6 +13,14 @@ export declare const FAIL_OPEN_TAGS: {
         readonly cls: "P-DEBT";
         readonly note: "件6(#43 案 [4281]):`FileRunStore.hydrate()` 的 `readdirSync(runs/)` 失败 ⇒ 引擎以**空账**起动。旧形是空 catch + return:data root 不可读(权限/挂载丢失/路径被换走)时零告警,此后每一次 getRun 恒 miss —— 而「恒 miss」正是 #43 现场看到的形,一次环境故障被伪装成「本来就没有这条 run」。方向问题在于吞掉之后被读成的是「证不出有行 ⇒ 没有行」,两句话不等价。**不拒启是刻意保留的行为**(拒启是行为变更,另立),所以这条留作债:响亮化(error 级启动日志带 runs 绝对路径+异常文案)+ 本计数,让它在遥测里显形而不是只活在一行日志里。终局=给 file 后端一条可选的 fail-closed 启动门。";
     };
+    readonly "server.fork-routing.placed-probe-host-error": {
+        readonly cls: "F";
+        readonly note: "#292 placement 半场:hostPlacedProbe 对 host 店的 requireExisting 探针失败且**不是 not_found**(host 读故障)时折叠为 absent —— 路由回旧规则(claim-create 会在 transient 建新会话)。放行的是「host 暂不可达时 transient 腿保持独立可用」;最坏后果=故障窗内对一个真 placed id 铸出 transient 影子(host 恢复后双身,requireExisting 冷探针会重新指回 host 真身)。not_found 是常态路径不计数;只有真故障臂进本计数。";
+    };
+    readonly "server.fork-routing.placed-roster-meta-unreadable": {
+        readonly cls: "F";
+        readonly note: "#292 placement 半场:host-fallback 命中后顺手读 meta 入 placed 名册失败(stub 会话无 getMetadata / 读故障)。名册只是省探针的缓存,不是判定 —— 缺一条=该 id 下次 acquire 多付一次 hostPlacedProbe,正确性零影响。计数留痕是为了让「meta 读一直在失败」这种环境病显形。";
+    };
     readonly "server.hitl.frame-undelivered-stream-closed": {
         readonly cls: "P-DEBT";
         readonly note: "HITL 的 **open** 帧写向一条已断/已关的 SSE 连接 ⇒ 静默丢弃,上游据此把投递记成成功,该 ask 挂到 TTL 才按无人应答结算。⚠️ #173 后 question 开帧改走断流 THROW(立即结算 unavailable),因此本 tag 在产的只剩 **elicitation** 一族——读计数时勿把它当作 question 的人在环缺口。no-op 而非 throw 对 elicitation 仍是既有的刻意决定,本条只保证它不再无声。";

package/dist/observability/fail-open.js

@@ -36,6 +36,14 @@ export const FAIL_OPEN_TAGS = {
         cls: "P-DEBT",
         note: "件6(#43 案 [4281]):`FileRunStore.hydrate()` 的 `readdirSync(runs/)` 失败 ⇒ 引擎以**空账**起动。旧形是空 catch + return:data root 不可读(权限/挂载丢失/路径被换走)时零告警,此后每一次 getRun 恒 miss —— 而「恒 miss」正是 #43 现场看到的形,一次环境故障被伪装成「本来就没有这条 run」。方向问题在于吞掉之后被读成的是「证不出有行 ⇒ 没有行」,两句话不等价。**不拒启是刻意保留的行为**(拒启是行为变更,另立),所以这条留作债:响亮化(error 级启动日志带 runs 绝对路径+异常文案)+ 本计数,让它在遥测里显形而不是只活在一行日志里。终局=给 file 后端一条可选的 fail-closed 启动门。",
     },
+    "server.fork-routing.placed-probe-host-error": {
+        cls: "F",
+        note: "#292 placement 半场:hostPlacedProbe 对 host 店的 requireExisting 探针失败且**不是 not_found**(host 读故障)时折叠为 absent —— 路由回旧规则(claim-create 会在 transient 建新会话)。放行的是「host 暂不可达时 transient 腿保持独立可用」;最坏后果=故障窗内对一个真 placed id 铸出 transient 影子(host 恢复后双身,requireExisting 冷探针会重新指回 host 真身)。not_found 是常态路径不计数;只有真故障臂进本计数。",
+    },
+    "server.fork-routing.placed-roster-meta-unreadable": {
+        cls: "F",
+        note: "#292 placement 半场:host-fallback 命中后顺手读 meta 入 placed 名册失败(stub 会话无 getMetadata / 读故障)。名册只是省探针的缓存,不是判定 —— 缺一条=该 id 下次 acquire 多付一次 hostPlacedProbe,正确性零影响。计数留痕是为了让「meta 读一直在失败」这种环境病显形。",
+    },
     "server.hitl.frame-undelivered-stream-closed": {
         cls: "P-DEBT",
         note: "HITL 的 **open** 帧写向一条已断/已关的 SSE 连接 ⇒ 静默丢弃,上游据此把投递记成成功,该 ask 挂到 TTL 才按无人应答结算。⚠️ #173 后 question 开帧改走断流 THROW(立即结算 unavailable),因此本 tag 在产的只剩 **elicitation** 一族——读计数时勿把它当作 question 的人在环缺口。no-op 而非 throw 对 elicitation 仍是既有的刻意决定,本条只保证它不再无声。",

package/dist/observability/rate-limit.d.ts

@@ -10,18 +10,28 @@ export interface RateDecision {
     retryAfterSec: number;
     remaining: number;
 }
+/** #322 批1:限额的**值换代**入参(六实现类同一形)。语义定案(design/322 §5):窗口内计数**不清零**,
+ *  新限额即时用于比较 —— 调小 = 窗内立刻更严(可能当场 429,符合运营意图),调大 = 立刻放宽。 */
+export interface RateLimits {
+    /** 每窗请求上限;`<= 0` = **关断哨兵**(恒放行、不记账、SQL 腿不起刷新环)。 */
+    rateLimitPerMin: number;
+}
 /** The surface the HTTP layer uses — satisfied by the in-memory {@link RateLimiter} (single replica)
  *  and the cross-replica {@link import("../plugins/tidb-rate-limiter.js").TiDBRateLimiter}. */
 export interface RateGate {
     check(key: string): RateDecision;
     sweep(now?: number): void;
+    /** #322:值换代座位。**接口级**声明(不是各类自选):新实现漏掉它 = 编译红,而不是热更新在那条腿上静默失效。 */
+    setLimits(next: RateLimits): void;
 }
 export declare class RateLimiter implements RateGate {
-    private readonly limit;
     private readonly windowMs;
     private readonly windows;
+    /** 🔴 不再 `readonly`:限额是**比较参数**,不是窗表状态 —— 换代只动它,窗内已计的数一个不动(§5)。 */
+    private limit;
     constructor(limit: number, windowMs?: number);
     check(key: string): RateDecision;
+    setLimits(next: RateLimits): void;
     /** Drop expired windows (call periodically). */
     sweep(now?: number): void;
 }

package/dist/observability/rate-limit.js

@@ -1,12 +1,15 @@
 export class RateLimiter {
-    limit;
     windowMs;
     windows = new Map();
+    /** 🔴 不再 `readonly`:限额是**比较参数**,不是窗表状态 —— 换代只动它,窗内已计的数一个不动(§5)。 */
+    limit;
     constructor(limit, windowMs = 60_000) {
-        this.limit = limit;
         this.windowMs = windowMs;
+        this.limit = limit;
     }
     check(key) {
+        // 关断哨兵:零比较、零窗表写入。off 期间不攒计数是刻意的——0→N 打开时应该是一个完整的新窗口,
+        // 而不是「上来就超」(那段时间根本没有 ceiling,补记账等于追溯执法)。
         if (this.limit <= 0)
             return { allowed: true, retryAfterSec: 0, remaining: Number.POSITIVE_INFINITY };
         const now = Date.now();
@@ -21,6 +24,9 @@ export class RateLimiter {
         }
         return { allowed: true, retryAfterSec: 0, remaining: this.limit - w.count };
     }
+    setLimits(next) {
+        this.limit = next.rateLimitPerMin;
+    }
     /** Drop expired windows (call periodically). */
     sweep(now = Date.now()) {
         for (const [k, w] of this.windows)

package/dist/plan-cache-probe.d.ts

@@ -8,11 +8,11 @@
  * does an agent's traffic actually re-pose near-duplicate objectives per tenant? (arXiv 2602.18922:
  * heterogeneous queries can hit 0–12%.) We hold the real multi-tenant traffic, so this is ours to count.
  *
- * **The token criterion is copied verbatim from core `src/core/strategy-store.ts`** (`tokens()` /
- * `significant()` / `find()` lines 46-52, 107-110) — otherwise we'd measure something other than what
- * plan-cache retrieval would actually use. Note the **asymmetry**: a stored problem is matched on its
- * full `tokens()` set, the query on its `significant()` set, and a hit = every significant query token
- * is present in some stored problem (`significant(new) ⊆ tokens(historical)`).
+ * **The token criterion is copied verbatim from core `strategy-store` (`compileStrategyQuery`)** —
+ * otherwise we'd measure something other than what plan-cache retrieval would actually use. Note the
+ * **asymmetry**: a stored problem is matched on its full `tokens()` set, the query on its
+ * `significant()` set. A hit = `significant(new) ⊆ tokens(historical)` OR (5.49 legacy acceptance
+ * arm) the non-CJK subset `qAlnum` is non-empty and fully contained (`qAlnum ⊆ tokens(historical)`).
  *
  * Fidelity choices (stated to search AI for confirmation): the history ring holds only **completed**
  * tasks (plan-cache only stores plans from successful runs), while the hit test runs for **every**
@@ -21,9 +21,7 @@
  */
 import type { Metrics } from "./observability/metrics.js";
 import type { Logger } from "./observability/logger.js";
-/** Lowercased word tokens (core口径). */
 export declare function tokens(s: string): string[];
-/** Meaningful tokens: ≥3 chars, not a stopword (core口径). */
 export declare function significant(s: string): string[];
 /** Per-scope view for the 2-week handoff back to search AI. */
 export interface ScopeRecurrence {

package/dist/plan-cache-probe.js

@@ -8,12 +8,30 @@ const STOP = new Set([
     "of", "to", "in", "on", "is", "it", "or", "as", "at", "by", "be", "do", "if", "so", "no", "up", "we",
 ]);
 /** Lowercased word tokens (core口径). */
+/** core 5.49 G2(CJK 检索修)同形:拉丁/数字按非字母数字切段 + CJK 按单字与相邻二元组入集
+ *  (core `memory-vector.termSet` 逐字搬)。旧形 `match(/[a-z0-9]+/g)` 对纯中文任务名恒空 ⇒
+ *  probe 测出的 recurrence 与 plan-cache 真命中脱钩——同源钉(plan-cache-probe.test.ts)就是
+ *  为这次换形红的。 */
+const CJK_RUN = /[぀-ヿㇰ-ㇿ㐀-䶿一-鿿가-힣豈-﫿]+/g;
 export function tokens(s) {
-    return s.toLowerCase().match(/[a-z0-9]+/g) ?? [];
+    const lower = s.toLowerCase();
+    const out = new Set();
+    for (const run of lower.split(/[^a-z0-9]+/))
+        if (run)
+            out.add(run);
+    for (const m of lower.matchAll(CJK_RUN)) {
+        const chars = [...m[0]];
+        for (const c of chars)
+            out.add(c);
+        for (let i = 0; i + 1 < chars.length; i++)
+            out.add(chars[i] + chars[i + 1]);
+    }
+    return [...out];
 }
-/** Meaningful tokens: ≥3 chars, not a stopword (core口径). */
+/** CJK 词条豁免长度/停词判(core 5.49 `CJK_LEAD` 同形:单字即显著);拉丁保持 ≥3 且非停词。 */
+const CJK_LEAD = /^[぀-ヿㇰ-ㇿ㐀-䶿一-鿿가-힣豈-﫿]/;
 export function significant(s) {
-    return tokens(s).filter((t) => t.length >= 3 && !STOP.has(t));
+    return tokens(s).filter((t) => (CJK_LEAD.test(t) ? true : t.length >= 3 && !STOP.has(t)));
 }
 const RING = 1000; // most-recent completed tasks per scope (= search AI's N=1000)
 const MAX_SCOPES = 2000; // LRU cap on tracked scopes — bounds memory under high tenant cardinality
@@ -38,12 +56,16 @@ export class PlanCacheProbe {
         const scope = scopeRaw && scopeRaw.length > 0 ? scopeRaw : "anon";
         const qSig = significant(objective);
         const st = this.touch(scope);
-        // Hit = some historical (completed) task's full token set ⊇ this task's significant tokens.
+        // Hit = some historical (completed) task's full token set ⊇ this task's significant tokens,
+        // OR(core 5.49 compileStrategyQuery 的 legacy acceptance 臂,合并窗重扫 medium)⊇ 其拉丁/数字
+        // 子集 qAlnum(非空时)——changelog 原句 "old hits preserved via a legacy acceptance arm"。
+        // 少这条臂时「CJK 团不全匹配但拉丁标识符全匹配」的真命中被判 miss ⇒ recurrence 系统性低估。
         // qSig empty → never a hit (mirrors find()'s `qSig.length===0 → []`, no injection).
         let hit = false;
         if (qSig.length > 0) {
+            const qAlnum = qSig.filter((t) => !CJK_LEAD.test(t));
             for (const hist of st.ring) {
-                if (qSig.every((t) => hist.has(t))) {
+                if (qSig.every((t) => hist.has(t)) || (qAlnum.length > 0 && qAlnum.every((t) => hist.has(t)))) {
                     hit = true;
                     break;
                 }

package/dist/plugins/caching-session-store.d.ts

@@ -1,6 +1,7 @@
-import type { AcquiredSession, RetentionDeclaration, SessionStore, SessionTreeEntry } from "@sema-agent/core";
+import type { AcquiredSession, PlacedSessionRow, RetentionDeclaration, SessionPlacementRecord, SessionStore, SessionTreeEntry } from "@sema-agent/core";
 import type { SessionListItem } from "../security.js";
 import type { StagingHandle } from "../session-sync-kernel.js";
+import { type PlacementAcquireOpts } from "./session-placement.js";
 export interface CachingOptions {
     /** Idle seconds a woken session is kept warm. 0 disables caching (pure passthrough). */
     ttlSec: number;
@@ -105,10 +106,25 @@ export declare class CachingSessionStore implements SessionStore {
      * 构造期常量,一个会变的声明本身就是缺陷。缺席则不设(保持 fail-closed 的缺席读法)。
      */
     readonly retention?: RetentionDeclaration;
+    /**
+     * #292 C18 —— 内层店的 **placement 声明**转发。
+     *
+     * 🔴 这一格与 {@link retention} 是同一条教训的同一族(而且更狠):生产默认 `SESSION_CACHE_TTL_SEC=300`
+     * 把真店包进本类,于是 boot 递给 core 的就是**包装层**。core 的铸造门判「row store ∧ **session 店声明**」
+     * ⇒ 不转发 = 整条 subagent 转录持久化在默认部署上**静默不生效**(placement 参数被合法忽略、子代转录
+     * 退回普通会话、声明的 durable tier 变成一句空话),而且没有任何一处会报错。
+     * 只读快照而非 getter:声明是店的构造期常量(会变的声明本身就是缺陷)。
+     */
+    readonly placements?: SessionStore["placements"];
+    /** #292:placed 分区的两只读面(reap 分区腿 / 准入探针)——同款转发理由:reaper 与准入判据拿到的
+     *  是包装层,不转发 = 分区腿静默不可用、暖命中的 claim 关门静默失效。缺席则不设(诚实降级)。 */
+    readonly listPlaced?: (kind: "subagent", opts?: {
+        olderThanMs?: number;
+        scope?: string;
+    }) => Promise<PlacedSessionRow[]>;
+    readonly placementOf?: (sessionId: string) => Promise<SessionPlacementRecord | undefined>;
     constructor(inner: SessionStore, opts: CachingOptions);
-    acquire(sessionId?: string, opts?: {
-        requireExisting?: boolean;
-    }): Promise<AcquiredSession>;
+    acquire(sessionId?: string, opts?: PlacementAcquireOpts): Promise<AcquiredSession>;
     touch(sessionId: string): Promise<void>;
     release(sessionId: string): Promise<void>;
     /** Drop a session from the warm cache (e.g. after a cross-instance write conflict). */

package/dist/plugins/caching-session-store.js

@@ -1,3 +1,4 @@
+import { assertPlacementAdmission } from "./session-placement.js";
 /**
  * Warm/sticky cache in front of a durable {@link SessionStore} (Option A).
  *
@@ -79,12 +80,34 @@ export class CachingSessionStore {
      * 构造期常量,一个会变的声明本身就是缺陷。缺席则不设(保持 fail-closed 的缺席读法)。
      */
     retention;
+    /**
+     * #292 C18 —— 内层店的 **placement 声明**转发。
+     *
+     * 🔴 这一格与 {@link retention} 是同一条教训的同一族(而且更狠):生产默认 `SESSION_CACHE_TTL_SEC=300`
+     * 把真店包进本类,于是 boot 递给 core 的就是**包装层**。core 的铸造门判「row store ∧ **session 店声明**」
+     * ⇒ 不转发 = 整条 subagent 转录持久化在默认部署上**静默不生效**(placement 参数被合法忽略、子代转录
+     * 退回普通会话、声明的 durable tier 变成一句空话),而且没有任何一处会报错。
+     * 只读快照而非 getter:声明是店的构造期常量(会变的声明本身就是缺陷)。
+     */
+    placements;
+    /** #292:placed 分区的两只读面(reap 分区腿 / 准入探针)——同款转发理由:reaper 与准入判据拿到的
+     *  是包装层,不转发 = 分区腿静默不可用、暖命中的 claim 关门静默失效。缺席则不设(诚实降级)。 */
+    listPlaced;
+    placementOf;
     constructor(inner, opts) {
         this.inner = inner;
         this.ttlMs = Math.max(0, opts.ttlSec) * 1000;
         const declared = inner.retention;
         if (declared !== undefined)
             this.retention = declared;
+        // #292:声明 + 两只读面逐字转发(理由见各自的字段注)。
+        if (inner.placements !== undefined)
+            this.placements = inner.placements;
+        if (typeof inner.listPlaced === "function")
+            this.listPlaced = (kind, o) => inner.listPlaced(kind, o);
+        const innerPlacementOf = inner.placementOf;
+        if (typeof innerPlacementOf === "function")
+            this.placementOf = (id) => innerPlacementOf.call(inner, id);
         const ownerAware = inner;
         if (ownerAware.ownerOf)
             this.ownerOf = ownerAware.ownerOf.bind(inner);
@@ -187,6 +210,13 @@ export class CachingSessionStore {
             return fresh;
         }
         const hit = this.cache.get(sessionId);
+        // 🔴 #292 义务 6(claim 关门)在**暖命中**上的半场:一次 claim 形 acquire 撞上缓存里的 placed 会话,
+        // 若按下面的「命中即返回」放行,包装层就成了义务的一个**旁路**——同一条 id 在冷缓存上被拒、在暖
+        // 缓存上被接受,而生产默认恰恰是暖的。判据仍吃**持久化元组**(一次 PK 探针,只在声明了分区的内层
+        // 店 + 非 requireExisting 的形上付),绝不用缓存里的影子事实当准入依据。
+        if (hit && opts?.requireExisting !== true && this.placements !== undefined && this.placementOf !== undefined) {
+            assertPlacementAdmission(sessionId, await this.placementOf(sessionId), opts);
+        }
         if (hit) {
             // A warm cache hit means the session EXISTS → it satisfies `requireExisting` (no need to re-open the durable
             // log). design/114 Phase3: the fail-loud only ever fires on a genuinely-missing (uncached) session below.
@@ -208,8 +238,19 @@ export class CachingSessionStore {
             return a;
         }
         const inflight = this.pending.get(sessionId);
-        if (inflight)
-            return inflight;
+        if (inflight) {
+            // 🔴 #292(codex 对抗复审 R1-[high],验真后修):**in-flight 合并也要逐调用者复判**准入。
+            // 病:两个并发调用一冷一后到,后到者直接拿走**首个**调用者的 promise —— 于是
+            //  · 可信 placement 创建先到 + claim 形后到 ⇒ 后者当场附着到一条 placed 转录上(义务 6 被绕过);
+            //  · 顺序反过来 ⇒ placement 创建方拿到一只**普通**会话(镜像方向的 squat 判本该拒,却被合并吞掉)。
+            // 内层 SQL 店自己有逐调用者复判(它的 pending 分支同款),但**默认生产形是本包装层**,而本层在
+            // 到达内层之前就把第二个调用者截断了 —— 判据被一层缓存挡在门外,正是本类反复吃过的那一类亏。
+            const acquired = await inflight;
+            if (this.placements !== undefined && this.placementOf !== undefined) {
+                assertPlacementAdmission(sessionId, await this.placementOf(sessionId), opts);
+            }
+            return acquired;
+        }
         const p = this.inner
             .acquire(sessionId, opts)
             .then((a) => {

package/dist/plugins/fork-routing-session-store.d.ts

@@ -23,7 +23,12 @@
  * 路由表 LRU 上限 {@link ROUTE_MAX}:满额逐最老(refresh-on-use);被逐后下次 `acquire` 按上述规则重derive
  * (requireExisting 的 host-first 重试仍落对店),中途 touch/noteTaskRun 缺路由=落 transient(no-op 级)。
  */
-import type { SessionStore, AcquiredSession, SessionStoreSummary } from "@sema-agent/core";
+import { type SessionStore, type AcquiredSession, type SessionStoreSummary, type SessionPlacement, type PlacedSessionRow } from "@sema-agent/core";
+/** acquire 选项形(core 5.48 SessionStore 契约):#292 placement=受信 spawner 的分区建会话声明。 */
+type AcquireOpts = {
+    requireExisting?: boolean;
+    placement?: SessionPlacement;
+};
 export declare class ForkRoutingSessionStore implements SessionStore {
     private readonly host;
     private readonly transient;
@@ -35,12 +40,28 @@ export declare class ForkRoutingSessionStore implements SessionStore {
      *  亲读),逐出后 transient-first 的 requireExisting 会把陈旧快照端回给 revive。本集不逐出(上界=
      *  parked 子代数,天然小);pick/acquire 首查。 */
     private readonly promoted;
+    /** #292 placement 半场:placed id 名册(与 promoted 同姿势——不随路由 LRU 逐出)。placed 会话的
+     *  真居所恒=host(分区在 durable 店),任何形的 acquire/touch/release 都不得落 transient——
+     *  否则 transient 的 claim-create 会铸出同 id 影子会话,requireExisting 的 transient-first 顺序
+     *  会让影子遮蔽真转录(F-7 顺序对 placed 反向成害)。 */
+    private readonly placed;
+    /** #292:host 店的 placements 声明透传(声明制——包装层不 duck-type,host 声明了才武装 placed
+     *  路由;host 不声明时本店全行为与 5.47 前逐字节同)。 */
+    readonly placements?: SessionStore["placements"];
+    /** #292:分区枚举透传(host 有才有——恒在的空实现会把「不能枚举」谎报成「没有 placed 会话」)。 */
+    readonly listPlaced?: (kind: "subagent", opts?: {
+        olderThanMs?: number;
+        scope?: string;
+    }) => Promise<PlacedSessionRow[]>;
     constructor(host: SessionStore, transient: SessionStore);
     private remember;
     private pick;
-    acquire(sessionId?: string, opts?: {
-        requireExisting?: boolean;
-    }): Promise<AcquiredSession>;
+    /** #292:host 声明分区时的冷缓存判位探针。判据=host `requireExisting` acquire 的 `SessionMetadata.placement`
+     *  (5.48 additive,File/SQL/Ttl 三形都带——比 `placementOf` 面更普适:Ttl 缓存层不透传 placementOf)。
+     *  placed 命中把 acquired 会话一并交回(调用方正需要它时零二次 acquire);非 placed/absent 的探针
+     *  acquire 一律 **forget** 收尾([4743] 义务①:验存在的 acquire 禁 release——release(placed)=真删)。 */
+    private hostPlacedProbe;
+    acquire(sessionId?: string, opts?: AcquireOpts): Promise<AcquiredSession>;
     touch(sessionId: string): void | Promise<void>;
     release(sessionId: string): Promise<void>;
     forget(sessionId: string): void | Promise<void>;
@@ -70,4 +91,5 @@ export declare class ForkRoutingSessionStore implements SessionStore {
     get size(): number;
     dispose(): void | Promise<void>;
 }
+export {};
 //# sourceMappingURL=fork-routing-session-store.d.ts.map