@sema-agent/server 7.38.0-rc.1 → 7.38.0

package/USAGE.md

@@ -681,7 +681,7 @@ curl -N http://<host>:8090/v1/tasks/stream -H 'content-type: application/json' \
 | `GET /v1/capabilities/scenarios/<name>` | 单个场景的只读详情:工具面、提示词概览、**本部署现在跑不跑得动**(见下) |
 | `POST /v1/admin/drain` `{"reason":"…"}` | **停机因由显式声明**(7.35.0+;operator-only —— principal 须在 `OPERATOR_PRINCIPALS` 内,空名单 = 谁都不是 operator ⇒ 恒 403)。编排壳在发 SIGTERM **之前**调它;server 记进程内 `drainState.reason`,draining 期由 `/health` 的 `drainReason` 与 503 `draining` 体的 `reason` 透出(未声明 = 两面键缺席)。声明是**覆盖式**、无 TTL、随进程重启清零 ⇒ 每次停机流程内都要重新声明。`reason` 非空、trim 后 ≤256 字符,坏值 400。🔴 **写口是特权的,读口不是**:`/health` 免鉴权(见下一行)且缺省全网卡监听 —— 任何能连到这个端口的人都读得到你写的那句话。**别在 reason 里写工单号、内部主机名或任何内部标识**。 |
 | `POST /v1/admin/config/refresh` | **配置手动刷新**(#322 批1;operator-only,与上一行同门:空 `OPERATOR_PRINCIPALS` ⇒ 恒 403)。改完中心配置 / `config.d` 之后不想等 60s 轮询就调它:触发**一次既有**的 refresh 拍(在飞则汇入那一拍,绝不并发双拍),返回时该拍已落地。200 体 `{triggered:true,targetVersion,appliedVersion}` —— 两个世代号与 `/health` 的 `configTargetVersion`/`configAppliedVersion` 同源。本部署没有配置管道(纯 env worker:既没配 `CONFIG_CENTER`、也不是 `CONFIG_PROVIDER=local`)⇒ 409 `config.refresh_unavailable` 指路,不会回一个「触发了但什么都没发生」的 200。 |
-| `GET /health` | 健康(无需鉴权)。7.37.0+ 配置管道在场时带世代账三键:`configTargetVersion`(本副本见过的最新配置版本)、`configAppliedVersion`(最后一次真落地的版本)、`configApplyStaleMs`(两者**持续**不等的时长;收敛时键缺席)—— 编排器据此摘掉「配置持续落后」的副本 |
+| `GET /health` | 健康(无需鉴权)。7.37.0+ 配置管道在场时带世代账键:`configTargetVersion`(本副本**最后见到**的配置版本,身份标)、`configAppliedVersion`(最后一次真落地的版本)、`configTargetOrdinal`/`configAppliedOrdinal`(7.38.0-rc.2 起,**收货序数**——`CONFIG_PROVIDER=local` 下 version 是内容哈希不承诺序,「改了没生效」看序数对不对齐)、`configApplyStaleMs`(target≠applied **持续**时长;收敛时键缺席)—— 编排器据此摘掉「配置持续落后」的副本 |
 | `GET /metrics` | Prometheus 指标(有 token 时需带) |
 
 > **场景可用性(7.7.0 起)**:场景详情里 `enabled` 与 `available` 是**两件事**。`enabled` = 这条场景

package/dist/boot/config-center.js

@@ -72,6 +72,19 @@ export async function createConfigCenterRuntime(ctx) {
     // #322 世代账(§2):主键=上游 version(不造本地 epoch)。boot/refresh/迟到 boot 三条腿共用这一本;
     // 候选被整拒的拍只推进 target ⇒ /health 的 stale 面从结构上可见。
     const applyLedger = createConfigApplyLedger();
+    // #325(test [4809],[4810] 阻断裁定):**收货序数**——CAS 与世代账的序轴。source version 在
+    // local 腿是内容哈希(registry-core file-store getVersion(),无序承诺),不能当序数比;这里按
+    // 收货顺序铸进程内单调 ordinal:version 变即 ++,等版本重放(etag 未推进的下一拍)沿用同
+    // ordinal=幂等语义保留。version 仍是跨副本对账的身份标(账里两者双报)。
+    let generationOrdinal = 0;
+    let lastGenerationVersion;
+    const generationOf = (version) => {
+        if (version !== lastGenerationVersion) {
+            lastGenerationVersion = version;
+            generationOrdinal += 1;
+        }
+        return generationOrdinal;
+    };
     // #322 追加件:手动触发口的实现指针 —— `startRefreshLoop` 起环时装上(cadence 与手动口共用的那只
     // join 形拍)。未起环(纯 env 部署 / 还没到装配那一步)⇒ 恒 undefined ⇒ 端点诚实 4xx。
     let manualRefresh;
@@ -376,9 +389,10 @@ export async function createConfigCenterRuntime(ctx) {
             return { effective: read.lkg.effective, ...(read.lkg.etag !== undefined ? { etag: read.lkg.etag } : {}) };
         };
         const bootApplyLkgInline = async (lkgR) => {
-            applyLedger.seenTarget(lkgR.effective.version);
-            applyEffective(config, lkgR.effective, logger, { sealedKeys, report: (rep) => applyLedger.recordApply(rep) });
-            applyLedger.applied(lkgR.effective.version);
+            const lkgGen = generationOf(lkgR.effective.version);
+            applyLedger.seenTarget(lkgGen, lkgR.effective.version);
+            applyEffective(config, lkgR.effective, logger, { sealedKeys, generation: lkgGen, report: (rep) => applyLedger.recordApply(rep) });
+            applyLedger.applied(lkgGen, lkgR.effective.version);
             await adoptCenterPrompts(lkgR.effective, "boot-lkg");
             markRosterLanded(lkgR.effective);
             effective = lkgR.effective;
@@ -442,16 +456,18 @@ export async function createConfigCenterRuntime(ctx) {
                         ccEtag = r.etag;
                 }
                 else {
-                    applyLedger.seenTarget(r.effective.version);
+                    const bootGen = generationOf(r.effective.version);
+                    applyLedger.seenTarget(bootGen, r.effective.version);
                     let bootReport;
                     applyEffective(config, r.effective, logger, {
                         sealedKeys,
+                        generation: bootGen,
                         report: (rep) => {
                             bootReport = rep;
                             applyLedger.recordApply(rep);
                         },
                     }); // sealedKeys: unseal sealedApiKey → in-memory key pipeline
-                    applyLedger.applied(r.effective.version);
+                    applyLedger.applied(bootGen, r.effective.version);
                     // codex R2-F1(boot 半场):某组被拒 ⇒ 这棵树**不干净** —— 与 domainErrors/坏 prompts 同处置
                     // (etag 不进、不进 LKG 候选),否则一次带坏 limits 的 boot 会把它写成盘上的 LKG。
                     if (bootReport?.fullyApplied === false)
@@ -796,7 +812,8 @@ export async function createConfigCenterRuntime(ctx) {
                         if (r) {
                             // #322 世代账:**拉到即算 target**(候选是否被采纳是下面的事)。整拒的拍只推进 target ⇒
                             // target≠applied 的持续时长在 /health 上可见 —— 「持续卡在旧代」的副本从结构上可被摘除。
-                            applyLedger.seenTarget(r.effective.version);
+                            const tickGen = generationOf(r.effective.version); // #325:收货序数(本拍全链同一个)
+                            applyLedger.seenTarget(tickGen, r.effective.version);
                             // §9.5-5 candidate gate: ANY invalid domain rejects the WHOLE candidate — the live config
                             // keeps serving the LKG (`latestEffective`) instead of that domain falling to schema-default/
                             // empty. ccEtag is deliberately NOT advanced: the bad tree stays visible (re-judged each poll),
@@ -864,6 +881,7 @@ export async function createConfigCenterRuntime(ctx) {
                                 const committed = applyEffective(config, r.effective, logger, {
                                     teamsOnly: true,
                                     sealedKeys,
+                                    generation: tickGen,
                                     report: (rep) => {
                                         applyReport = rep;
                                         applyLedger.recordApply(rep);
@@ -885,7 +903,7 @@ export async function createConfigCenterRuntime(ctx) {
                                 mutateInPlace(pricing, buildPricing(config.models)); // hot: cost/model changes; Runner reads this.deps.pricing live
                                 keyResolver = createKeyResolver(config.modelApiKeyEnv, process.env, config.modelApiKeys); // hot: per-model key add/remove/change (env-ref + sealed)
                                 limitSync?.sync(); // #322 批1:限额座与 config 成对换代(同一条「派生件紧贴 commit」纪律)
-                                applyLedger.applied(r.effective.version);
+                                applyLedger.applied(tickGen, r.effective.version);
                                 if (planeDeferred) {
                                     logger.warn("models_tiers_plane_deferred", { version: r.effective.version, note: "tier-frozen Runner: the changed model plane (models/roles/tiers/default) is NOT hot-applied — admission stays on the Runner's generation; restart applies the new plane (models-tiers restart signal rides /health)" });
                                 }
@@ -1082,7 +1100,8 @@ export async function createConfigCenterRuntime(ctx) {
                     }
                 };
                 const deferredBootApplyInner = async (r) => {
-                    applyLedger.seenTarget(r.effective.version); // #322:迟到 boot 也是「见过这一代」
+                    const lateGen = generationOf(r.effective.version); // #325:收货序数(迟到 boot 拍全链同一个)
+                    applyLedger.seenTarget(lateGen, r.effective.version); // #322:迟到 boot 也是「见过这一代」
                     const promptsRaw = r.effective.prompts;
                     const promptsGate = promptsRaw !== undefined ? validatePromptsDomain(promptsRaw) : { ok: true };
                     if ((r.domainErrors ?? []).length > 0 || !promptsGate.ok) {
@@ -1111,6 +1130,7 @@ export async function createConfigCenterRuntime(ctx) {
                     const committedLate = applyEffective(config, r.effective, logger, {
                         teamsOnly: true,
                         sealedKeys,
+                        generation: lateGen,
                         report: (rep) => {
                             applyReportLate = rep;
                             applyLedger.recordApply(rep);
@@ -1125,7 +1145,7 @@ export async function createConfigCenterRuntime(ctx) {
                     mutateInPlace(pricing, buildPricing(config.models));
                     keyResolver = createKeyResolver(config.modelApiKeyEnv, process.env, config.modelApiKeys);
                     limitSync?.sync(); // #322 批1(late-boot 双胞胎:只修一条腿 = 另一条继续漏)
-                    applyLedger.applied(r.effective.version);
+                    applyLedger.applied(lateGen, r.effective.version);
                     if (planeDeferredLate)
                         logger.warn("models_tiers_plane_deferred", { version: r.effective.version, note: "tier-frozen Runner (env tiers): the late-boot center model plane is NOT hot-applied — restart applies it" });
                     else {

package/dist/config-center/apply-effective.d.ts

@@ -30,6 +30,8 @@ export declare const UNPARSABLE_AT_MODEL_ALLOWLIST_ENTRY = "\0<unparsable-at-mod
 /** #322:一次 apply 的**世代账载荷**(post-commit 发,[2283]② —— commit 段仍是零回调零发射)。 */
 export interface ApplyReport {
     readonly version: number;
+    /** #325:本候选的收货序数(= opts.generation 原样带回;世代账按它记拒收,身份标仍是 version)。 */
+    readonly ordinal?: number;
     readonly limits: {
         /** 本世代真正换了值的键。 */
         readonly applied: readonly string[];
@@ -53,6 +55,7 @@ export declare function applyEffective(config: ServiceConfig, eff: EffectiveConf
     teamsOnly?: boolean;
     sealedKeys?: SealedKeyOpener;
     deferModelPlane?: boolean;
+    generation?: number;
     report?: (r: ApplyReport) => void;
     swapPlane?: (plane: {
         models: Record<string, Model>;

package/dist/config-center/apply-effective.js

@@ -158,12 +158,17 @@ function stageAtModelAllowlist(raw, models, logger) {
 }
 export function applyEffective(config, eff, logger, opts = {}) {
     const staged = stageEffective(config, eff, logger, opts);
+    // #325(test [4809]):CAS 的序轴=**收货序数**(opts.generation,config-center 收货处铸的进程内
+    // 单调 ordinal),不再是 source version——local 腿的 version 是内容哈希(registry-core file-store
+    // getVersion(),上游只承诺「同 files⇒同 number」,无序承诺),按它比序会把哈希更小的合法新代
+    // 永久静默拒掉。generation 缺席(单元测试/一次性 lane)退回 version:既有单调 version 语义不变。
+    const gen = opts.generation ?? staged.version;
     const live = appliedGeneration.get(config);
-    if (staged.version > 0 && live !== undefined && staged.version < live) {
+    if (staged.version > 0 && live !== undefined && gen < live) {
         // [2283]③:两次拉取的 staging 并发/乱序完成时,慢的旧世代不得整体覆盖快的新世代——每次都是
         // 「整世代」,但方向反了。拒绝必须留痕(C6);caller 的 etag 纪律本就只在 apply 成功后推进,
-        // 下一拍拉到的自然是更新的世代。等版本重放(etag 未推进的幂等重放)照常放行。
-        logger?.warn("sema_registry_stale_generation_refused", { staged: staged.version, live, note: "an older staged generation must not overwrite a newer committed one — refused whole; next poll replays" });
+        // 下一拍拉到的自然是更新的世代。等版本重放(etag 未推进的幂等重放,同 ordinal)照常放行。
+        logger?.warn("sema_registry_stale_generation_refused", { staged: staged.version, stagedOrdinal: gen, live, note: "an older staged generation must not overwrite a newer committed one — refused whole; next poll replays" });
         return false;
     }
     // core 5.49 `Runner.swapModels` 换装腿([4775]①,defer 臂退役):caller 传入 swapPlane 时,staged
@@ -185,10 +190,13 @@ export function applyEffective(config, eff, logger, opts = {}) {
         }
     }
     commitStaged(config, staged);
+    if (staged.version > 0)
+        appliedGeneration.set(config, gen); // #325:CAS 的 live 端=收货序数
     // ── post-commit notifications(全部世代描述性通知在最后一笔赋值之后,[2283]②)──
     // #322 世代账:apply 报告也是「世代描述性通知」⇒ 同样在 commit 之后发(commit 段零回调纪律不破)。
     opts.report?.({
         version: staged.version,
+        ...(opts.generation !== undefined ? { ordinal: opts.generation } : {}),
         limits: {
             applied: staged.limits.changed,
             ...(staged.limits.deferred.length > 0 ? { deferred: staged.limits.deferred } : {}),
@@ -256,8 +264,7 @@ function commitStaged(config, staged) {
         registerCollabWorkflows(tp.workflows);
     }
     mutateInPlace(config.projects, staged.projects); // IN PLACE: keep the ref per-request consumers captured at boot
-    if (staged.version > 0)
-        appliedGeneration.set(config, staged.version);
+    // 世代登记在 applyEffective 内做(#325:登记的是收货序数 gen,不是 source version)。
 }
 /** STAGE 段:一切计算/校验/解封/投影(可抛;抛=候选整体拒绝,活配置零触碰)。内容判定性 warn/error
  *  (描述 eff 真伪,与是否 commit 无关)在此发;世代描述性 info 只装载荷,post-commit 发。 */

package/dist/config-center/apply-ledger.d.ts

@@ -1,19 +1,28 @@
 /**
  * #322 —— **世代账**(design/322 §2 世代账,codex 设计审 F4)。
  *
- * 主键 = 上游 `EffectiveConfig.version`(apply-effective 的 CAS 用的就是它),**刻意不造本地自增 epoch**:
+ * 身份标 = 上游 `EffectiveConfig.version`,**刻意不造跨进程 epoch**(codex F4 语义不变):
  *  · 同版本幂等重放(etag 未推进的下一拍)不该伪增世代;
- *  · 双副本对账「是不是同一代」必须能跨进程判 —— 本地计数器做不到这件事。
+ *  · 双副本对账「是不是同一代」必须能跨进程判 —— 同 source version = 同一代。
  *
- * 读面两个:`/health` 的三键(target / applied / 失败持续时长)给编排器判「这个副本要不要摘」;诊断端点的
- * `configApply` 段给运维看**按组**的细节(哪一组停在哪一代、上一次为什么被拒)。
+ * 🔴 #325(test [4809],[4810] 阻断裁定):**序轴与身份标分离**。source version 在
+ * `CONFIG_PROVIDER=local` 下是 registry-core file-store 的内容哈希(u53,上游契约只承诺
+ * 「同 files ⇒ 同 number」,从未承诺序)——把它当序数消费,哈希更小的合法新代会被永久
+ * 静默忽略且本账双盲(target/applied 都不动)。修后:**推进判断吃收货处铸的进程内单调
+ * ordinal**(config-center `generationOf`;等版本重放沿用同 ordinal=幂等语义保留),
+ * `version` 只做对账身份标——configTargetVersion 语义从「max(见过)」变为「**最后**见过的
+ * 源代」(remote 单调腿二者等价;local 腿这才是真相)。
+ *
+ * 读面两个:`/health` 的三键(target / applied / 失败持续时长;#325 起 additive 补
+ * targetOrdinal/appliedOrdinal 两键=推进/停滞的机器判据)给编排器判「这个副本要不要摘」;
+ * 诊断端点的 `configApply` 段给运维看**按组**的细节(哪一组停在哪一代、上一次为什么被拒)。
  *
  * 🔴 原子承诺的**域**是单进程(§2):本账记的是「本副本的收敛状态」,不是 fleet 的。fleet 级判据 = 各副本
  * /health 的 applied == target,拉齐工具归运维面。
  */
 /** 一组的收敛状态(批1 只有 limitsHttp 组;后续批次按组追加,读面形不变)。 */
 export interface ConfigApplyGroupState {
-    /** 本组最后一次**真的落地**的源版本。 */
+    /** 本组最后一次**真的落地**的源版本(身份标)。 */
     readonly appliedVersion: number;
     /** 被判定为「只能重启生效」的键 + 铸因(热路径拒了,但拒因是姿态而不是坏值)。 */
     readonly deferredKeys?: ReadonlyArray<{
@@ -29,10 +38,14 @@ export interface ConfigApplyGroupState {
     };
 }
 export interface ConfigApplyLedgerView {
-    /** 本副本见过的最新源版本(拉到即算,哪怕候选被整拒)。 */
+    /** 本副本**最后**见到的源版本(身份标;拉到即算,哪怕候选被整拒)。 */
     readonly configTargetVersion: number;
-    /** 最后一次成功 commit 的源版本。 */
+    /** 最后一次成功 commit 的源版本(身份标)。 */
     readonly configAppliedVersion: number;
+    /** #325:target 的收货序数(进程内单调)——「见过多少代」的推进判据,哈希方向免疫。 */
+    readonly configTargetOrdinal: number;
+    /** #325:applied 的收货序数。targetOrdinal 推进而这里停滞 = 「改了没生效」的机器判据。 */
+    readonly configAppliedOrdinal: number;
     /** target≠applied 的**持续**时长(ms);收敛时键缺席(健康面不制造噪音)。 */
     readonly configApplyStaleMs?: number;
     readonly groups: Readonly<Record<string, ConfigApplyGroupState>>;
@@ -40,6 +53,8 @@ export interface ConfigApplyLedgerView {
 /** applyEffective 的 post-commit 报告(见 apply-effective.ts `ApplyReport`)。 */
 export interface ConfigApplyReport {
     readonly version: number;
+    /** #325:本候选的收货序数(applyEffective opts.generation 原样带回;缺席=version 兼容臂)。 */
+    readonly ordinal?: number;
     readonly limits: {
         readonly applied: readonly string[];
         readonly deferred?: ReadonlyArray<{
@@ -55,10 +70,10 @@ export interface ConfigApplyReport {
     readonly fullyApplied?: boolean;
 }
 export interface ConfigApplyLedger {
-    /** 拉到一个候选(无论后续是否应用)。 */
-    seenTarget(version: number): void;
+    /** 拉到一个候选(无论后续是否应用)。ordinal=收货序数,version=身份标。 */
+    seenTarget(ordinal: number, version: number): void;
     /** 一个候选整体 commit 成功。 */
-    applied(version: number): void;
+    applied(ordinal: number, version: number): void;
     /** 消费 applyEffective 的报告(按组记账)。 */
     recordApply(report: ConfigApplyReport): void;
     view(): ConfigApplyLedgerView;

package/dist/config-center/apply-ledger.js

@@ -1,56 +1,75 @@
 /**
  * #322 —— **世代账**(design/322 §2 世代账,codex 设计审 F4)。
  *
- * 主键 = 上游 `EffectiveConfig.version`(apply-effective 的 CAS 用的就是它),**刻意不造本地自增 epoch**:
+ * 身份标 = 上游 `EffectiveConfig.version`,**刻意不造跨进程 epoch**(codex F4 语义不变):
  *  · 同版本幂等重放(etag 未推进的下一拍)不该伪增世代;
- *  · 双副本对账「是不是同一代」必须能跨进程判 —— 本地计数器做不到这件事。
+ *  · 双副本对账「是不是同一代」必须能跨进程判 —— 同 source version = 同一代。
  *
- * 读面两个:`/health` 的三键(target / applied / 失败持续时长)给编排器判「这个副本要不要摘」;诊断端点的
- * `configApply` 段给运维看**按组**的细节(哪一组停在哪一代、上一次为什么被拒)。
+ * 🔴 #325(test [4809],[4810] 阻断裁定):**序轴与身份标分离**。source version 在
+ * `CONFIG_PROVIDER=local` 下是 registry-core file-store 的内容哈希(u53,上游契约只承诺
+ * 「同 files ⇒ 同 number」,从未承诺序)——把它当序数消费,哈希更小的合法新代会被永久
+ * 静默忽略且本账双盲(target/applied 都不动)。修后:**推进判断吃收货处铸的进程内单调
+ * ordinal**(config-center `generationOf`;等版本重放沿用同 ordinal=幂等语义保留),
+ * `version` 只做对账身份标——configTargetVersion 语义从「max(见过)」变为「**最后**见过的
+ * 源代」(remote 单调腿二者等价;local 腿这才是真相)。
+ *
+ * 读面两个:`/health` 的三键(target / applied / 失败持续时长;#325 起 additive 补
+ * targetOrdinal/appliedOrdinal 两键=推进/停滞的机器判据)给编排器判「这个副本要不要摘」;
+ * 诊断端点的 `configApply` 段给运维看**按组**的细节(哪一组停在哪一代、上一次为什么被拒)。
  *
  * 🔴 原子承诺的**域**是单进程(§2):本账记的是「本副本的收敛状态」,不是 fleet 的。fleet 级判据 = 各副本
  * /health 的 applied == target,拉齐工具归运维面。
  */
 export function createConfigApplyLedger(now = () => Date.now()) {
-    let target = 0;
-    let applied = 0;
+    let targetOrd = 0;
+    let appliedOrd = 0;
+    let targetVersion = 0;
+    let appliedVersion = 0;
     /**
      * 🔴 codex R1-F3(真 finding,红先):**有组被拒的世代不算「本副本应用了这一代」**。
      *
      * applyEffective 对一个 limits 被整组拒的候选仍返回 true(其余面照常提交),生产腿随后无条件调
-     * `applied(version)` —— 修前于是 `/health` 报 applied==target、stale 时长消失,而限额面其实停在旧代。
-     * 世代账存在的全部理由就是让这种漂移可见,所以拒过的世代号在这里被记下,`applied()` 拒绝为它收敛。
+     * `applied(...)` —— 修前于是 `/health` 报 applied==target、stale 时长消失,而限额面其实停在旧代。
+     * 世代账存在的全部理由就是让这种漂移可见,所以拒过的世代在这里被记下,`applied()` 拒绝为它收敛。
+     * #325 起按 **ordinal** 记(local 腿同 version 可能隔代重现,序数才是「这一次候选」的唯一键)。
      */
-    const rejectedVersions = new Set();
+    const rejectedOrds = new Set();
     /** 首次分歧的时刻 —— **持续**时长的锚(每拍刷新会把「卡了一小时」写成「卡了 0 秒」)。 */
     let divergedSince;
     const groups = {};
     const reconcile = () => {
-        if (target === applied)
+        if (targetOrd === appliedOrd)
             divergedSince = undefined;
         else
             divergedSince ??= now();
     };
     return {
-        seenTarget(version) {
-            if (version > target)
-                target = version;
+        seenTarget(ordinal, version) {
+            if (ordinal > targetOrd) {
+                targetOrd = ordinal;
+                targetVersion = version;
+            }
             reconcile();
         },
-        applied(version) {
-            if (version > target)
-                target = version; // 迟到 boot / LKG 腿:应用的那一代自然也是见过的
+        applied(ordinal, version) {
+            if (ordinal > targetOrd) {
+                targetOrd = ordinal; // 迟到 boot / LKG 腿:应用的那一代自然也是见过的
+                targetVersion = version;
+            }
             // 本世代有组被拒 ⇒ 只推进 target(诚实的「见过、没能完整应用」),applied 停在上一个完整世代。
-            if (!rejectedVersions.has(version) && version > applied)
-                applied = version;
+            if (!rejectedOrds.has(ordinal) && ordinal > appliedOrd) {
+                appliedOrd = ordinal;
+                appliedVersion = version;
+            }
             reconcile();
         },
         recordApply(report) {
             const prev = groups.limitsHttp;
+            const ord = report.ordinal ?? report.version; // 兼容臂:未传 ordinal 的单元调用退回 version 键
             if (report.limits.rejected)
-                rejectedVersions.add(report.version);
+                rejectedOrds.add(ord);
             else
-                rejectedVersions.delete(report.version); // 同一世代重放且这次过了(拒因已修)⇒ 允许收敛
+                rejectedOrds.delete(ord); // 同一世代重放且这次过了(拒因已修)⇒ 允许收敛
             if (report.limits.rejected) {
                 groups.limitsHttp = {
                     appliedVersion: prev?.appliedVersion ?? 0, // 被拒的世代不许推进组的 applied
@@ -72,8 +91,10 @@ export function createConfigApplyLedger(now = () => Date.now()) {
         view() {
             const stale = divergedSince !== undefined ? now() - divergedSince : undefined;
             return {
-                configTargetVersion: target,
-                configAppliedVersion: applied,
+                configTargetVersion: targetVersion,
+                configAppliedVersion: appliedVersion,
+                configTargetOrdinal: targetOrd,
+                configAppliedOrdinal: appliedOrd,
                 ...(stale !== undefined ? { configApplyStaleMs: stale } : {}),
                 groups: { ...groups },
             };

package/dist/http/routes/runs.js

@@ -1396,19 +1396,23 @@ async function handleRunVerbsBody(req, res, url, ctx, miss) {
         // [1596]/[1600] core 1.397 三分:仲裁器**抛错**(店不可达)此前被误吞成 park_resume_won 的假话——
         // 「输给了并发 resume」与「根本问不到仲裁结果」是两种不同的行动建议(前者重查状态,后者原样重试
         // stop),新码 `park_arbiter_unreachable` 让二者不再共用一个 errorCode。
-        const parkArbiterUnreachable = details?.error === "park_arbiter_unreachable";
-        const parkResumeWon = details?.error === "park_resume_won";
-        const stillParked = details?.error === "parked_pending_approval" || details?.status === "parked";
+        // [4797](core 5.50)details.code 孪生对表:stop 族座位今天仍只铸 `error`(族扫未及,已上板点名),
+        // 但 core 契约方向是「code wins when both present」且未承诺新失败座位必带 error ⇒ 判类读
+        // code-优先-error-回落、在场判据双键取并,未来只铸 code 的失败座位不会漏判成 200 成功。
+        const stopCode = typeof details?.code === "string" ? details.code : details?.error;
+        const parkArbiterUnreachable = stopCode === "park_arbiter_unreachable";
+        const parkResumeWon = stopCode === "park_resume_won";
+        const stillParked = stopCode === "parked_pending_approval" || details?.status === "parked";
         // v3.1 批2(统检第二波 high):判别方向翻转——旧形是 (status,error) 的**失败白名单**(status==="running"
         // || 三个具名码),core 新增失败码且行状态不在 {running,parked} 时整个分支被跳过落 200,与上面注释自陈
         // 的不变量(kill 没落地绝不读成功)正相悖(B5 联合非穷尽的 default-放行形;not_local/park 族/arbiter
         // 三次历史新增全靠人追认)。新形:stop 动词的 error **在场即失败**(not_found 已在上方早退),具名臂
         // 保留各自 errorCode,未知码落 stop.not_landed 兜底 409——新失败码默认可见,不默认成功。
-        if (stopVerb && details?.error !== undefined) {
+        if (stopVerb && (details?.error !== undefined || details?.code !== undefined)) {
             // 1.250:durable 回落臂(core stopTask agentStore 分支)对他实例 running 行应答 error="not_local"
             // (没有 kill 被尝试)——与「kill 尝试了没落地」(stop.not_landed)是不同的失败形,各给各的
             // errorCode(同 409 家族,additive)。
-            const notLocal = details.error === "not_local";
+            const notLocal = stopCode === "not_local";
             sendError(res, 409, notLocal
                 ? "stop.not_local"
                 : parkArbiterUnreachable
@@ -1425,7 +1429,7 @@ async function handleRunVerbsBody(req, res, url, ctx, miss) {
                         ? "the pending tool-approval was resolved (resumed) concurrently with this stop attempt — the resume won the race, so nothing was stopped; re-check the task's current status"
                         : stillParked
                             ? "this task is durably parked awaiting a tool-approval decision, not actively running — there is no live process to interrupt; resolve (or let expire) the pending approval instead"
-                            : `stop did not land (${details.error}) — the process may still be running`, { taskId: runId, target, content: out.content, output: out.details });
+                            : `stop did not land (${stopCode}) — the process may still be running`, { taskId: runId, target, content: out.content, output: out.details });
             return;
         }
         // Registry projection passed through verbatim (status/retrieval_status/cursor flags); `content` is

package/dist/http/server.js

@@ -496,10 +496,11 @@ export function createHttpServer(rawDeps) {
                     const stuck = deps.planeDeferredState?.();
                     return stuck ? { modelPlaneDeferred: { version: stuck.version, since: stuck.since, noHandoff: true, ...(stuck.blocked ? { blockedReasons: stuck.blocked } : {}) } } : {};
                 })(),
-                // #322 世代账三键(additive;未接线 ⇒ 三键全缺席,/health 形状逐字不变)。
-                // 语义:target = 本副本见过的最新源版本;applied = 最后一次真的 commit 的版本;staleMs = 两者
-                // **持续**不等的时长(收敛即缺席)。编排器据此摘掉「配置持续落后」的副本 —— 修前这个状态只在
-                // 日志里,跨副本不可聚合。
+                // #322 世代账三键(additive;未接线 ⇒ 键全缺席,/health 形状逐字不变)。
+                // 语义:target = 本副本**最后**见到的源版本(身份标);applied = 最后一次真的 commit 的版本;
+                // staleMs = 两者**持续**不等的时长(收敛即缺席)。#325 起 additive 补两 ordinal 键(收货序数,
+                // 进程内单调)——local 腿 version 是内容哈希无序承诺,「见过多少代/停在哪一代」的推进判断
+                // 用 ordinal 键;跨副本「同不同代」的对账仍用 version 身份标。
                 ...(() => {
                     const gen = deps.configApplyState?.();
                     if (!gen)
@@ -507,6 +508,8 @@ export function createHttpServer(rawDeps) {
                     return {
                         configTargetVersion: gen.configTargetVersion,
                         configAppliedVersion: gen.configAppliedVersion,
+                        configTargetOrdinal: gen.configTargetOrdinal,
+                        configAppliedOrdinal: gen.configAppliedOrdinal,
                         ...(gen.configApplyStaleMs !== undefined ? { configApplyStaleMs: gen.configApplyStaleMs } : {}),
                     };
                 })(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "7.38.0-rc.1",
+  "version": "7.38.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.49.0",
+    "@sema-agent/core": "^5.50.0",
     "@sema-agent/registry-core": "^0.19.0",
     "e2b": "^2.28.0",
     "libsodium-wrappers": "^0.8.4",