@sema-agent/server 7.123.0 → 7.124.0

package/dist/model-select.d.ts

@@ -1,5 +1,10 @@
 import { type Model, type RunnerDeps } from "@sema-agent/core";
+import { type AtMention } from "@sema-agent/settings-schema";
 import type { ModelEntryRefusal } from "./model-entry-refusal.js";
+/** 座位缺席时的读法 —— 契约 prefault 解出来的值(今天是 `{mode:"all"}`),env 车道(没有中心)的 `config.atMention` 也是它。 */
+export declare const DEFAULT_AT_MENTION: AtMention;
+/** 一个 `models.atMention` 值的读法:缺席 ⇒ {@link DEFAULT_AT_MENTION};在场 ⇒ 契约 schema 判形,判不过 ⇒ `undefined`(调用方 fail-closed 并响亮)。 */
+export declare function readAtMention(raw: unknown): AtMention | undefined;
 /**
  * Resolve the model ref for a task spec from the request (CLI `/model` picker + `run --model`).
  *
@@ -37,7 +42,7 @@ export declare const DEFAULT_MODEL_REF = "default";
  * 起不再各抄一份「展开 + 解」。
  */
 export declare function resolveMainModel(plane: Pick<RunnerDeps, "models" | "tiers">): Model;
-export declare function resolveTaskModel(bodyModel: unknown, objective: string, catalog: Record<string, unknown>, allowlist?: readonly string[], refusals?: Readonly<Record<string, ModelEntryRefusal>>): {
+export declare function resolveTaskModel(bodyModel: unknown, objective: string, catalog: Record<string, unknown>, atMention: AtMention, refusals?: Readonly<Record<string, ModelEntryRefusal>>): {
     model: string;
     cleanedObjective: string;
     unknownExplicit?: string;
@@ -84,7 +89,7 @@ export declare function refusedCatalogEntry(ref: string, refusals: Readonly<Reco
     name: string;
     refusal: ModelEntryRefusal;
 } | undefined;
-/** [ref] 判别式拒因:名单在场且这次**用户选择**落在名单外。`resolved` 已是目录 name 形(归一后)。 */
+/** [ref] 判别式拒因:这次**用户选择**不在 `atMention` 许可之内(`none`,或 `only` 而不在名里)。`resolved` 已是目录 name 形(归一后)。 */
 export interface ModelNotAllowed {
     /** 调用方发来的原始 ref(name / 档位词 / 别名 / id / `@name`),已做过日志安全的 repr 归一。 */
     requested: string;
@@ -94,28 +99,26 @@ export interface ModelNotAllowed {
     source: "explicit" | "mention";
 }
 /**
- * [ref] / [ref] —— **归一条款**:membership 判定前把 ref 归一到**终端 catalog 条目**再比。
+ * [ref] / [ref] —— 「这个 ref 此刻可不可以被用户 `@` / 显式点选」的**唯一**判据(`models.atMention`,三态闭集,穷举 switch)。
  *
- * 为什么不能拿字符串直接跟名单比:`expandTiers` 的增广目录里,档位词(`pro`)与 CC 别名(`sonnet`)
- * 的值与 `config.models[<name>]` 是**同一个对象引用**——裸串比较会让 `@pro` 跳过一张按 name 写的名单
- * (同一只模型,两个键)。所以两边(ref 与每个名单条目)都先经 {@link matchCatalogModel} 解到目录条目,
- * 再按 **引用相等** 判同。id 形的 ref 不需要特别处理:`matchCatalogModel` 本身就是 name+id 双键索引,
- * 它会把 id 解成目录键,引用相等接着就对上了。
+ * 判序(一条规则):先把 ref 归一到**目录条目**({@link matchCatalogModel},name / 档位词 / 别名 / id 同一只);目录里根本没有的 ref ⇒ 恒 `true`
+ * —— 那是「未知模型」那道门的辖区(fresh 400 / resume 降级留声),本门只答「在目录里,但准不准点」,两道门同码同拒会让消费端分不清
+ * "没这模型"和"不让你点"。然后按 `mode`:
+ *  · `all`  ⇒ `true`;
+ *  · `none` ⇒ `false`(一个都不许);
+ *  · `only` ⇒ ref 归一到的那只条目**自己的目录名**在名单里 ⇒ `true`(名单按目录名直比)。
  *
- * 🔴 **刻意没有「id 相等」退路**(codex 复审 R1 [high],已采纳):目录**允许两条不同 name 的条目共享
- * 同一个上游 `Model.id`,却各自带不同的 `baseUrl` / `apiKeyEnv` / `cost` / provider** —— 那正是多网关、
- * 多账号部署形。按 id 判同会把 `safe` 与 `premium` 合并,于是一张只含 `safe` 的名单会放行 `premium`,
- * 而真正执行的是 `premium` 那份坐标与计费。判据只认**目录条目本身**:两条条目就是两只模型,哪怕上游
- * id 撞车。(引用相等因此不是"优化",是唯一正确的判据;它天然覆盖 tier 词/别名/id 三形。)
+ * 为什么 ref 侧要先归一、不拿 ref 串直比:`expandTiers` 的增广目录里,档位词(`pro`)与 CC 别名(`sonnet`)的值与 `config.models[<name>]`
+ * 是**同一个对象引用**——裸串比较会让 `@pro` 跳过一张按 name 写的名单(同一只模型,两个键)。名单侧不归一:`only` 的名在 stage 期已按本世代
+ * 可用目录收窄成目录名(settings-schema `narrowAtMention`),名单项是档位词 / 别名 / id 的形只可能来自绕过 stage 的写者 —— 它们准不了任何东西。
+ * 🔴 **刻意没有「id 相等」退路**(codex 复审 R1 [high]):目录**允许两条不同 name 的条目共享同一个上游 `Model.id`,却各自带不同的
+ * `baseUrl` / `apiKeyEnv` / `cost` / provider** —— 按 id 判同会把 `safe` 与 `premium` 合并,一张只含 `safe` 的名单会放行 `premium`。
+ * 🔴 S-704:名里写着一条**不可用**条目的名字 ⇒ 它准不了任何东西(不经 id 回退 / 别名改绑去准另一只模型 —— `matchCatalogModel` 的名字保留律)。
+ * `only` 的名在 stage 期已按本世代可用目录收窄过(settings-schema `narrowAtMention`,收窄到一个不剩 ⇒ `none`),所以这里的悬空名只来自绕过 stage 的写者(按名直比,悬空名不等于任何条目的名)。
  *
- * 缺席/空名单 ⇒ 恒 `true`(ship-dark:缺省 = 旧行为,全放行)。
- * 目录里根本没有的 ref ⇒ 恒 `true`:那是「未知模型」那道门的辖区(fresh 400 / resume 降级留声),
- * 本门只答「在目录里,但准不准点」——两道门同码同拒会让消费端分不清"没这模型"和"不让你点"。
- *
- * ⚠️ 射程:本门是**提交时**门。core 运行时路由(degrade 降级链 / cascade 梯 / roles 解析)按 operator
- * 配置自己走,**不经本门**——那不是一次用户选择,如实声明,不假装是运行时执法。
+ * ⚠️ 射程:本门是**提交时**门。core 运行时路由(degrade 降级链 / cascade 梯 / roles 解析)按 operator 配置自己走,**不经本门**。
  */
-export declare function isModelAllowlisted(ref: string, catalog: Record<string, unknown>, allowlist: readonly string[] | undefined, refusals?: Readonly<Record<string, ModelEntryRefusal>>): boolean;
+export declare function isAtMentionable(ref: string, catalog: Record<string, unknown>, atMention: AtMention, refusals?: Readonly<Record<string, ModelEntryRefusal>>): boolean;
 /**
  * [ref] —— ref → **终端 catalog name**(拒因/日志的可读形)。
  *
@@ -144,7 +147,7 @@ export type ModelImageInput = (typeof MODEL_IMAGE_INPUTS)[number];
  *  · 目录行 `GET /v1/models` 的 `vision`:`yes` ⇒ `true`,`no` ⇒ `false`,`undeclared` ⇒ **键缺席**(不替没声明的模型答「收」也不答「不收」);
  *  · 运行期的带图预检 {@link modelSupportsImages}:只有明说 `no` 才出信号。
  * 此前两处各判各的,且对「没声明」答法相反(目录行报 false、预检放行)——客户端只读得到目录那一位,于是在手写、没声明 `input` 的
- * 条目上把用户的图拦在了本地,而引擎其实会把图交给模型。env 车道与配置中心车道恒写 `input`,分叉只落在手写目录条目上。
+ * 条目上把用户的图拦在了本地,而引擎其实会把图交给模型。env 车道与 web-admin 车道恒写 `input`,分叉只落在手写目录条目上。
  * `input` 不是数组(手写错形)与条目不在,同归 `undeclared`:没有可信的声明。
  */
 export declare function modelImageInput(model: {

package/dist/model-select.js

@@ -1,10 +1,17 @@
 import { expandTiers, parseModelMention, resolveTaskModel as coreResolveTaskModel } from "@sema-agent/core";
+import { DOMAIN_SCHEMAS } from "@sema-agent/settings-schema";
+const AT_MENTION_SEAT = DOMAIN_SCHEMAS.models.shape.atMention;
+export const DEFAULT_AT_MENTION = Object.freeze(AT_MENTION_SEAT.parse(undefined));
+export function readAtMention(raw) {
+    const r = AT_MENTION_SEAT.safeParse(raw);
+    return r.success ? r.data : undefined;
+}
 export const DEFAULT_MODEL_REF = "default";
 export function resolveMainModel(plane) {
     const expanded = expandTiers(plane.models, plane.tiers ?? {}) ?? plane.models;
     return coreResolveTaskModel({ model: DEFAULT_MODEL_REF }, { ...(expanded !== undefined ? { models: expanded } : {}) }).model;
 }
-export function resolveTaskModel(bodyModel, objective, catalog, allowlist, refusals) {
+export function resolveTaskModel(bodyModel, objective, catalog, atMention, refusals) {
     const mention = parseModelMention(objective, [...Object.keys(refusals ?? {}), ...Object.keys(catalog)]);
     const mentionUsable = mention.model !== undefined && Object.hasOwn(catalog, mention.model) ? mention.model : undefined;
     const explicit = typeof bodyModel === "string" ? matchCatalogModel(bodyModel, catalog, refusals) : undefined;
@@ -20,7 +27,7 @@ export function resolveTaskModel(bodyModel, objective, catalog, allowlist, refus
     const unknown = present && explicit === undefined && refusedExplicit === undefined;
     const model = explicit ?? mentionUsable ?? DEFAULT_MODEL_REF;
     const picked = explicit !== undefined ? { ref: explicit, source: "explicit", requested: repr } : mentionUsable !== undefined ? { ref: mentionUsable, source: "mention", requested: mentionUsable } : undefined;
-    const notAllowed = picked !== undefined && !isModelAllowlisted(picked.ref, catalog, allowlist, refusals)
+    const notAllowed = picked !== undefined && !isAtMentionable(picked.ref, catalog, atMention, refusals)
         ? { requested: picked.requested, resolved: terminalCatalogName(picked.ref, catalog, refusals) ?? picked.ref, source: picked.source }
         : undefined;
     return {
@@ -51,24 +58,22 @@ export function refusedCatalogEntry(ref, refusals) {
             return { name, refusal: r };
     return undefined;
 }
-export function isModelAllowlisted(ref, catalog, allowlist, refusals) {
-    if (allowlist === undefined || allowlist.length === 0)
-        return true;
-    const entry = catalogEntryOf(ref, catalog, refusals);
-    if (entry === undefined)
+export function isAtMentionable(ref, catalog, atMention, refusals) {
+    const name = terminalCatalogName(ref, catalog, refusals);
+    if (name === undefined)
         return true;
-    for (const name of allowlist) {
-        const allowed = catalogEntryOf(name, catalog, refusals);
-        if (allowed === undefined)
-            continue;
-        if (allowed === entry)
+    switch (atMention.mode) {
+        case "all":
             return true;
+        case "none":
+            return false;
+        case "only":
+            return atMention.models.includes(name);
+        default: {
+            const unhandled = atMention;
+            throw new Error(`atMention: unknown mode ${JSON.stringify(unhandled)}`);
+        }
     }
-    return false;
-}
-function catalogEntryOf(ref, catalog, refusals) {
-    const name = matchCatalogModel(ref, catalog, refusals);
-    return name === undefined ? undefined : catalog[name];
 }
 export function terminalCatalogName(ref, catalog, refusals) {
     const key = matchCatalogModel(ref, catalog, refusals);

package/dist/observability/metrics.d.ts

@@ -23,7 +23,7 @@ export declare class Metrics {
     /** Structured snapshot of the whole registry — the OTLP exporter maps this to OTel data points
      *  (counters→Sum monotonic, gauges/dynamic→Gauge, histograms→Histogram). Read-only copy. */
     snapshot(): MetricSnapshot;
-    /** Curated health summary (friendly JSON) for a lightweight fleet dashboard — the sema-registry's
+    /** Curated health summary (friendly JSON) for a lightweight fleet dashboard — the web-admin's
      *  fleet page fetches this per worker and renders cards + computes rates over polls (no Prometheus
      *  needed). Counters are cumulative totals; histograms are reported as averages (sum/count). */
     summarize(): MetricsSummary;

package/dist/org-memory-admission.d.ts

@@ -1,6 +1,6 @@
 /**
  * Org 记忆准入 resolver — server 侧对接 @sema-agent/core@5.13.0 `RunnerDeps.memoryScopeAdmission` seam。
- * 授权事实来自「目录」抽象:远程腿 = config-center per-principal caps 响应里的 `orgMemory` 段(形状
+ * 授权事实来自「目录」抽象:远程腿 = web-admin per-principal caps 响应里的 `orgMemory` 段(形状
  * 同源锚 = registry-core `PrincipalOrgMemoryWire`,zod schema 直接 safeParse);单机腿 = env JSON 静态表
  * (`MEMORY_ORG_DIRECTORY_JSON`,{@link parseOrgDirectoryStatic} 装载,启动期 fail-loud)。
  *

package/dist/plugins/approval-ask-store-file.d.ts

@@ -1,5 +1,6 @@
 import type { AskState } from "../approval-ask-machine.js";
-import type { AskCallCoordinate, AskRow, AskTerminalClaimIntent, AskTerminalClaimOutcome, AskTransitionPatch, ApprovalAskStore, BatchRow, BindGateInput, BindResult, DecideAskInput, DecideResult, EnsureAskResult, ExpireResult, NewAskRow } from "./approval-ask-store-sql.js";
+import type { SettleCause } from "../approval-deny-reasons.js";
+import type { AskCallCoordinate, AskRow, AskTerminalClaimIntent, AskTerminalClaimOpts, AskTerminalClaimOutcome, AskTransitionPatch, ApprovalAskStore, BatchRow, BindGateInput, BindResult, DecideAskInput, DecideResult, EnsureAskResult, ExpireResult, NewAskRow } from "./approval-ask-store-sql.js";
 /** 数据根下的目录名。**按店命名**,与兄弟 File 店同规(`approval-nonces` / `approval-ask-audit` /
  *  `approval-exemptions` / `resume-anchors` / `checkpoint-ctx` / …)—— 首版写的是族名 `approvals`,而那
  *  正是读者会去找**持久 park 行**的地方(它们其实在 `checkpoint-ctx`),且持久数据面的名字按硬 breaking
@@ -61,6 +62,7 @@ type JournalCall = {
     askId: string;
     batchId: string;
     intent: JournalV1ClaimIntent;
+    cause?: SettleCause;
 }
 /** NP-2 的部署政策拒(`claimTerminal(…, "refuse")`)—— 新动词而不是老动词带新意图,理由见 {@link JOURNAL_V1_CLAIM_INTENTS}。 */
  | {
@@ -162,7 +164,7 @@ export declare class FileApprovalAskStore implements ApprovalAskStore {
      * 「先编码、编码成功才一次性提交」同一条原子性)。
      */
     decideAsk(askId: string, batchId: string, decision: DecideAskInput): Promise<DecideResult>;
-    claimTerminal(askId: string, batchId: string, intent: AskTerminalClaimIntent): Promise<AskTerminalClaimOutcome>;
+    claimTerminal(askId: string, batchId: string, intent: AskTerminalClaimIntent, opts?: AskTerminalClaimOpts): Promise<AskTerminalClaimOutcome>;
     expireAsk(askId: string, batchId: string): Promise<ExpireResult>;
     bindBatch(batchId: string, askId: string, gate: BindGateInput): Promise<BindResult>;
     abortBatch(batchId: string): Promise<string[]>;

package/dist/plugins/approval-ask-store-file.js

@@ -182,7 +182,7 @@ export class FileApprovalAskStore {
             case "decideAsk":
                 return this.core.decideAsk(rec.askId, rec.batchId, rec.decision);
             case "claimTerminal":
-                return this.core.claimTerminal(rec.askId, rec.batchId, rec.intent);
+                return this.core.claimTerminal(rec.askId, rec.batchId, rec.intent, rec.cause !== undefined ? { cause: rec.cause } : undefined);
             case "claimTerminalRefuse":
                 return this.core.claimTerminal(rec.askId, rec.batchId, "refuse");
             case "expireAsk":
@@ -213,11 +213,11 @@ export class FileApprovalAskStore {
         const journalled = decision.updatedInput === undefined ? decision : { ...decision, updatedInput: encodeDecideUpdatedInput(decision.updatedInput) };
         return this.write({ op: "decideAsk", askId, batchId, decision: journalled }, (c) => this.core.decideAsk(c.askId, c.batchId, c.decision));
     }
-    async claimTerminal(askId, batchId, intent) {
+    async claimTerminal(askId, batchId, intent, opts) {
         switch (intent) {
             case "expire":
             case "cancel":
-                return this.write({ op: "claimTerminal", askId, batchId, intent }, (c) => this.core.claimTerminal(c.askId, c.batchId, c.intent));
+                return this.write({ op: "claimTerminal", askId, batchId, intent, ...(opts?.cause !== undefined ? { cause: opts.cause } : {}) }, (c) => this.core.claimTerminal(c.askId, c.batchId, c.intent, c.cause !== undefined ? { cause: c.cause } : undefined));
             case "refuse":
                 return this.write({ op: "claimTerminalRefuse", askId, batchId }, (c) => this.core.claimTerminal(c.askId, c.batchId, "refuse"));
             default: {

package/dist/plugins/approval-ask-store-memory.d.ts

@@ -25,7 +25,7 @@
  *  - resolveProvisional 故意不经 canAskTransition(同 SQL twin 头注：这是版本化补偿的例外通道）。
  */
 import { type AskState, type BatchState } from "../approval-ask-machine.js";
-import type { AskCallCoordinate, AskDecision, AskRow, AskTerminalClaimIntent, AskTerminalClaimOutcome, AskTransitionPatch, ApprovalAskStore, BatchRow, BindGateInput, BindResult, DecideAskInput, EnsureAskResult, DecideResult, ExpireResult, NewAskRow } from "./approval-ask-store-sql.js";
+import type { AskCallCoordinate, AskDecision, AskRow, AskTerminalClaimIntent, AskTerminalClaimOpts, AskTerminalClaimOutcome, AskTransitionPatch, ApprovalAskStore, BatchRow, BindGateInput, BindResult, DecideAskInput, EnsureAskResult, DecideResult, ExpireResult, NewAskRow } from "./approval-ask-store-sql.js";
 /**
  * [ref] 的 `updatedInput` **入店编码**——两 twin 共用的那一只(本函数是唯一真源)。
  *
@@ -88,8 +88,9 @@ export declare class InMemoryApprovalAskStore implements ApprovalAskStore {
      * 论证);await 后读到的行 ≥ CAS 线性化点,而非 pending 态无回边 ⇒ 败方读数自足(与 SQL 侧同一条
      * 单调性论证)。
      */
-    claimTerminal(askId: string, batchId: string, intent: AskTerminalClaimIntent): Promise<AskTerminalClaimOutcome>;
-    expireAsk(askId: string, batchId: string): Promise<ExpireResult>;
+    claimTerminal(askId: string, batchId: string, intent: AskTerminalClaimIntent, opts?: AskTerminalClaimOpts): Promise<AskTerminalClaimOutcome>;
+    /** `cause`(可选)= 转 park 的触发成因,赢下 PARKING 的同一步落进 `deniedReason`(SQL twin 同一条 UPDATE 的镜像;接口上的 `expireAsk` 不带它,只有 `claimTerminal(expire, { cause })` 带)。 */
+    expireAsk(askId: string, batchId: string, cause?: AskTerminalClaimOpts["cause"]): Promise<ExpireResult>;
     bindBatch(batchId: string, askId: string, gate: BindGateInput): Promise<BindResult>;
     deferReconcile(askId: string, expectedState: AskState, expectedRev: number, nowMs: number): Promise<boolean>;
     abortBatch(batchId: string): Promise<string[]>;

package/dist/plugins/approval-ask-store-memory.js

@@ -1,4 +1,5 @@
 import { canAskTransition } from "../approval-ask-machine.js";
+import { APPROVAL_ENDING_CAUSES } from "../approval-deny-reasons.js";
 import { askRowOnCall, assertDecideSettledBy, assertIdempotencyKeyShape, assertIntegralEpochMs, ApprovalAskReadAbortedError, claimTargetState, POLICY_REFUSAL_DECISION, projectAskTerminalClaimTruth } from "./approval-ask-store-sql.js";
 function applyPatch(row, patch) {
     if (patch.decision !== undefined)
@@ -152,10 +153,10 @@ export class InMemoryApprovalAskStore {
         ask.updatedAtMs = now;
         return { ok: true, row: { ...ask } };
     }
-    async claimTerminal(askId, batchId, intent) {
+    async claimTerminal(askId, batchId, intent, opts) {
         switch (intent) {
             case "expire": {
-                const res = await this.expireAsk(askId, batchId);
+                const res = await this.expireAsk(askId, batchId, opts?.cause);
                 if (res.won)
                     return { claimed: true, voidedSiblings: res.voidedSiblings };
                 break;
@@ -164,7 +165,7 @@ export class InMemoryApprovalAskStore {
                 const scoped = this.asks.get(askId);
                 if (scoped !== undefined && scoped.batchId !== batchId)
                     return { claimed: false, current: { state: "absent" } };
-                const won = await this.transitionAsk(askId, "STREAM_PENDING", "VOID", { updatedAtMs: this.now() });
+                const won = await this.transitionAsk(askId, "STREAM_PENDING", "VOID", { updatedAtMs: this.now(), ...(opts?.cause !== undefined ? { deniedReason: opts.cause } : {}) });
                 if (won)
                     return { claimed: true, voidedSiblings: [] };
                 break;
@@ -195,7 +196,7 @@ export class InMemoryApprovalAskStore {
         const cur = this.asks.get(askId);
         return { claimed: false, current: projectAskTerminalClaimTruth(cur !== undefined && cur.batchId === batchId ? { ...cur } : null) };
     }
-    async expireAsk(askId, batchId) {
+    async expireAsk(askId, batchId, cause) {
         const now = this.now();
         const batch = this.batches.get(batchId);
         if (!batch)
@@ -204,6 +205,8 @@ export class InMemoryApprovalAskStore {
         if (!ask || ask.state !== "STREAM_PENDING" || ask.batchId !== batchId)
             return { won: false, voidedSiblings: [] };
         ask.state = "PARKING";
+        if (cause !== undefined)
+            ask.deniedReason = cause;
         ask.rev += 1;
         ask.updatedAtMs = now;
         if (batch.state === "OPEN") {
@@ -215,6 +218,7 @@ export class InMemoryApprovalAskStore {
         for (const [id, r] of this.asks) {
             if (r.batchId === batchId && r.state === "STREAM_PENDING" && id !== askId) {
                 r.state = "VOID";
+                r.deniedReason = APPROVAL_ENDING_CAUSES.BATCH_SIBLING_WITHDRAWN;
                 r.rev += 1;
                 r.updatedAtMs = now;
                 voided.push(id);
@@ -247,6 +251,7 @@ export class InMemoryApprovalAskStore {
         for (const [id, r] of this.asks) {
             if (r.batchId === batchId && r.state === "PARKING" && id !== askId) {
                 r.state = "VOID";
+                r.deniedReason = APPROVAL_ENDING_CAUSES.BATCH_BOUND_ELSEWHERE;
                 r.rev += 1;
                 r.updatedAtMs = now;
                 voidedSiblings.push(id);
@@ -274,6 +279,7 @@ export class InMemoryApprovalAskStore {
         for (const [id, r] of this.asks) {
             if (r.batchId === batchId && r.state === "STREAM_PENDING") {
                 r.state = "VOID";
+                r.deniedReason = APPROVAL_ENDING_CAUSES.BATCH_ABORTED;
                 r.rev += 1;
                 r.updatedAtMs = now;
                 voided.push(id);

package/dist/plugins/approval-ask-store-sql.d.ts

@@ -42,6 +42,7 @@ import type { PgQueryFn } from "./pg-query.js";
 import { type SqlDriver, type SqlDialect } from "./sql-driver.js";
 import { type AskState, type BatchState } from "../approval-ask-machine.js";
 import type { HostSettledBy } from "../host-decision.js";
+import { type AskRowCause, type SettleCause } from "../approval-deny-reasons.js";
 import { type IndexSpec } from "./ensure-index.js";
 export type AskDecision = "approve" | "deny";
 export interface AskRow {
@@ -317,6 +318,15 @@ export interface ExpireResult {
  * WHERE 谓词 {@link pendingClaimWhere} 兑现,不是把不同 verb 塞进一个函数。
  */
 export type AskTerminalClaimIntent = "expire" | "cancel" | "refuse";
+/**
+ * 终局 claim 的可选实参:`cause` —— **赢下 `cancel`(VOID)/ `expire`(PARKING)时写进这一行 `denied_reason` 列的成因词**(决断口 410 / 晚答 404 / 跨副本的败方读数读同一列,
+ * 所以这一行自己记着「为什么」,读面不靠任何进程内的东西)。`cancel` 写终态成因({@link SettleCause} 里的 `run_cancelled` / `run_exited`),
+ * `expire` 写转 park 的触发成因({@link ParkTriggerCause}:`ttl_expired` / `broadcast_lost` / `stream_disconnected` / `undeliverable` / `shutdown_before_park`);缺席 ⇒ 列保持 NULL(读面缺席即缺席)。
+ * `refuse` 不读它(落的是一条决议,来源位 `policy`,不是结局成因);`expire` 撤兄弟时店自己写 `batch_sibling_withdrawn`(那是这条事务本身的事实)。
+ */
+export interface AskTerminalClaimOpts {
+    readonly cause?: SettleCause;
+}
 /**
  * `refuse` 意图落行的决议(NP-2)—— **部署政策拒**:deny + 结算来源 `policy`。来源词的型取 core 的 `HostSettledBy`
  * (core 改词 / 退词 ⇒ 这里 tsc 红);协调器交给 core 的那一只(`tool-approval.ts` 的 `UnattendedPolicyRefusal`)读的是
@@ -353,6 +363,10 @@ export type AskTerminalClaimCurrent = {
     /** S-558:赢家决议的**结算来源**(语义与两态读法见 {@link AskRow.settledBy})。**必填**(不是可选)——
      *  可选会让投影漏挑这一列时静默编译过,而漏挑的后果恰是本批要修的病:CAS 输家把赢家的策略拒读成人拒。 */
     settledBy: HostSettledBy | null;
+    /** 行上记着的成因,经问账行成因的唯一读口 `causeOfAskRow` 读出(`kind` 说它在这一行上的意思:VOID / DENIED = 终态成因,PARKING / PARKED = 转 park 的触发成因);
+     *  **只在读得出时在场**(没写 / 与 state 不配 ⇒ 缺席;DECIDED 的败方读数逐字不变)。CAS 输家据它按**行上那个成因**结算(而不是把别人撤的卡读成一次拒绝);
+     *  投影的唯一函数是 {@link projectAskTerminalClaimTruth},三 twin 不各自挑列,原始列值不出店层。 */
+    cause?: AskRowCause;
 };
 /**
  * 单次原子往返的答案(语义律的唯一规范陈述点 = core `checkpoint-store.ts` `claimTerminal` 契约 JSDoc,
@@ -424,7 +438,7 @@ export interface ApprovalAskStore {
      * `expireAsk`/`transitionAsk`(InMemory,单线程天然原子)——两向都成立的判据是**没有第二套谓词**。
      * 方法**必备**(本仓自有三形全实现,无 core 那侧的 presence 探测问题)。
      */
-    claimTerminal(askId: string, batchId: string, intent: AskTerminalClaimIntent): Promise<AskTerminalClaimOutcome>;
+    claimTerminal(askId: string, batchId: string, intent: AskTerminalClaimIntent, opts?: AskTerminalClaimOpts): Promise<AskTerminalClaimOutcome>;
     expireAsk(askId: string, batchId: string): Promise<ExpireResult>;
     bindBatch(batchId: string, askId: string, gate: BindGateInput): Promise<BindResult>;
     abortBatch(batchId: string): Promise<string[]>;
@@ -624,7 +638,7 @@ export declare class SqlApprovalAskStore implements ApprovalAskStore {
      *    在状态机上无回边 ⇒ 锁定读读到的恒 ≥ 线性化点,且 DECIDED 决议不可变 —— 答案自足。
      *  · 本事务在输臂上除批行 rev 自增外零写,rollback 无痕。
      */
-    claimTerminal(askId: string, batchId: string, intent: AskTerminalClaimIntent): Promise<AskTerminalClaimOutcome>;
+    claimTerminal(askId: string, batchId: string, intent: AskTerminalClaimIntent, opts?: AskTerminalClaimOpts): Promise<AskTerminalClaimOutcome>;
     /** [ref] 起 = {@link claimTerminal}(expire 意图)的薄投影 —— 律 2「在 claimTerminal 之上实现」的
      *  SQL 半场落笔处:谓词/事务/兄弟撤卡全在 claim 里,这里零第二套写路径。败方读数按既有返回形丢弃
      *  (`ExpireResult` 不携真相 —— 要真相的调用方直接用 claimTerminal;对账收敛器的 orphan 腿输了本就

package/dist/plugins/approval-ask-store-sql.js

@@ -1,5 +1,6 @@
 import { mysqlDriver, pgDriver, dialectJsonEncoder } from "./sql-driver.js";
 import { canAskTransition } from "../approval-ask-machine.js";
+import { APPROVAL_ENDING_CAUSES, causeOfAskRow } from "../approval-deny-reasons.js";
 import { isDupKeyError, isMissingColumnError } from "./sql-errors.js";
 import { decodeJsonColumn, foldJsonColumn, jsonColumnText, readJsonObjectColumn, readTriStateJsonValueColumn } from "./sql-json-column.js";
 import { ensureIndexes } from "./ensure-index.js";
@@ -70,12 +71,14 @@ export function claimTargetState(intent) {
 export function projectAskTerminalClaimTruth(row) {
     if (row === null || row.state === "STREAM_PENDING")
         return { state: "absent" };
+    const cause = causeOfAskRow(row);
     return {
         state: row.state,
         rev: row.rev,
         decision: row.decision,
         ...(row.updatedInput !== undefined ? { updatedInput: row.updatedInput } : {}),
         settledBy: row.settledBy,
+        ...(cause !== undefined ? { cause } : {}),
     };
 }
 export function askRowOnCall(row, call) {
@@ -501,7 +504,7 @@ export class SqlApprovalAskStore {
             throw new Error(`decideAsk: row vanished after commit (askId=${askId})`);
         return { ok: true, row };
     }
-    async claimTerminal(askId, batchId, intent) {
+    async claimTerminal(askId, batchId, intent, opts) {
         const to = claimTargetState(intent);
         if (!canAskTransition("STREAM_PENDING", to)) {
             throw new Error(`approval-ask-store.claimTerminal: illegal terminal claim STREAM_PENDING -> ${to} (askId=${askId})`);
@@ -522,12 +525,15 @@ export class SqlApprovalAskStore {
             }
             const askRes = intent === "refuse"
                 ? await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state = ${ph(dialect, 1)}, decision = ${ph(dialect, 2)}, settled_by = ${ph(dialect, 3)}, decided_at_ms = ${ph(dialect, 4)}, rev = rev + 1, updated_at_ms = ${ph(dialect, 5)} WHERE ${pendingClaimWhere(dialect, 6)}`, [to, POLICY_REFUSAL_DECISION.decision, POLICY_REFUSAL_DECISION.settledBy, now, now, askId, batchId])
-                : await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state = ${ph(dialect, 1)}, rev = rev + 1, updated_at_ms = ${ph(dialect, 2)} WHERE ${pendingClaimWhere(dialect, 3)}`, [
-                    to,
-                    now,
-                    askId,
-                    batchId,
-                ]);
+                : (intent === "cancel" || intent === "expire") && opts?.cause !== undefined
+                    ?
+                        await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state = ${ph(dialect, 1)}, denied_reason = ${ph(dialect, 2)}, rev = rev + 1, updated_at_ms = ${ph(dialect, 3)} WHERE ${pendingClaimWhere(dialect, 4)}`, [to, opts.cause, now, askId, batchId])
+                    : await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state = ${ph(dialect, 1)}, rev = rev + 1, updated_at_ms = ${ph(dialect, 2)} WHERE ${pendingClaimWhere(dialect, 3)}`, [
+                        to,
+                        now,
+                        askId,
+                        batchId,
+                    ]);
             if (askRes.affected !== 1) {
                 const sel = await conn.query(`SELECT ${askCols(dialect)} FROM ${APPROVAL_ASK_TABLE} WHERE ask_id = ${ph(dialect, 1)} AND batch_id = ${ph(dialect, 2)} FOR UPDATE`, [askId, batchId]);
                 await conn.rollback();
@@ -540,7 +546,7 @@ export class SqlApprovalAskStore {
             await conn.query(this.q(`UPDATE ${APPROVAL_BATCH_TABLE} SET state='ROUTING_UNBOUND', rev=rev+1, updated_at_ms=? WHERE batch_id=? AND state='OPEN'`, `UPDATE ${APPROVAL_BATCH_TABLE} SET state='ROUTING_UNBOUND', rev=rev+1, updated_at_ms=$1 WHERE batch_id=$2 AND state='OPEN'`), [now, batchId]);
             let voidedSiblings;
             if (this.db.dialect === "pg") {
-                const res = await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state='VOID', rev=rev+1, updated_at_ms=$1 WHERE batch_id=$2 AND state='STREAM_PENDING' AND ask_id<>$3 RETURNING ask_id`, [now, batchId, askId]);
+                const res = await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state='VOID', denied_reason=$4, rev=rev+1, updated_at_ms=$1 WHERE batch_id=$2 AND state='STREAM_PENDING' AND ask_id<>$3 RETURNING ask_id`, [now, batchId, askId, APPROVAL_ENDING_CAUSES.BATCH_SIBLING_WITHDRAWN]);
                 voidedSiblings = res.rows.map((r) => String(r.ask_id));
             }
             else {
@@ -548,7 +554,8 @@ export class SqlApprovalAskStore {
                 voidedSiblings = sel.rows.map((r) => String(r.ask_id));
                 if (voidedSiblings.length > 0) {
                     const inList = voidedSiblings.map(() => "?").join(", ");
-                    await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state='VOID', rev=rev+1, updated_at_ms=? WHERE ask_id IN (${inList}) AND state='STREAM_PENDING'`, [
+                    await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state='VOID', denied_reason=?, rev=rev+1, updated_at_ms=? WHERE ask_id IN (${inList}) AND state='STREAM_PENDING'`, [
+                        APPROVAL_ENDING_CAUSES.BATCH_SIBLING_WITHDRAWN,
                         now,
                         ...voidedSiblings,
                     ]);
@@ -593,7 +600,7 @@ export class SqlApprovalAskStore {
             }
             let voidedSiblings;
             if (this.db.dialect === "pg") {
-                const res = await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state='VOID', rev=rev+1, updated_at_ms=$1 WHERE batch_id=$2 AND state='PARKING' AND ask_id<>$3 RETURNING ask_id`, [now, batchId, askId]);
+                const res = await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state='VOID', denied_reason=$4, rev=rev+1, updated_at_ms=$1 WHERE batch_id=$2 AND state='PARKING' AND ask_id<>$3 RETURNING ask_id`, [now, batchId, askId, APPROVAL_ENDING_CAUSES.BATCH_BOUND_ELSEWHERE]);
                 voidedSiblings = res.rows.map((r) => String(r.ask_id));
             }
             else {
@@ -601,7 +608,7 @@ export class SqlApprovalAskStore {
                 voidedSiblings = sel.rows.map((r) => String(r.ask_id));
                 if (voidedSiblings.length > 0) {
                     const inList = voidedSiblings.map(() => "?").join(", ");
-                    await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state='VOID', rev=rev+1, updated_at_ms=? WHERE ask_id IN (${inList}) AND state='PARKING'`, [now, ...voidedSiblings]);
+                    await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state='VOID', denied_reason=?, rev=rev+1, updated_at_ms=? WHERE ask_id IN (${inList}) AND state='PARKING'`, [APPROVAL_ENDING_CAUSES.BATCH_BOUND_ELSEWHERE, now, ...voidedSiblings]);
                 }
             }
             await conn.commit();
@@ -631,7 +638,7 @@ export class SqlApprovalAskStore {
             }
             let voided;
             if (this.db.dialect === "pg") {
-                const res = await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state='VOID', rev=rev+1, updated_at_ms=$1 WHERE batch_id=$2 AND state='STREAM_PENDING' RETURNING ask_id`, [now, batchId]);
+                const res = await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state='VOID', denied_reason=$3, rev=rev+1, updated_at_ms=$1 WHERE batch_id=$2 AND state='STREAM_PENDING' RETURNING ask_id`, [now, batchId, APPROVAL_ENDING_CAUSES.BATCH_ABORTED]);
                 voided = res.rows.map((r) => String(r.ask_id));
             }
             else {
@@ -639,7 +646,7 @@ export class SqlApprovalAskStore {
                 voided = sel.rows.map((r) => String(r.ask_id));
                 if (voided.length > 0) {
                     const inList = voided.map(() => "?").join(", ");
-                    await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state='VOID', rev=rev+1, updated_at_ms=? WHERE ask_id IN (${inList}) AND state='STREAM_PENDING'`, [now, ...voided]);
+                    await conn.query(`UPDATE ${APPROVAL_ASK_TABLE} SET state='VOID', denied_reason=?, rev=rev+1, updated_at_ms=? WHERE ask_id IN (${inList}) AND state='STREAM_PENDING'`, [APPROVAL_ENDING_CAUSES.BATCH_ABORTED, now, ...voided]);
                 }
             }
             await conn.commit();

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

@@ -57,16 +57,6 @@ export declare class CachingSessionStore implements SessionStore {
     }) => Promise<SessionListItem[]>;
     readonly fork?: (sourceId: string, owner: string | null) => Promise<string | null>;
     readonly deleteSession?: (sessionId: string, owner: string | null) => Promise<boolean>;
-    /** K-5c (core 1.155 SessionStore.noteTaskRun seam) — core's Runner calls it at runTask START to record the latest
-     *  run per session (→ listSessions `lastRunId`). MUST be forwarded: the local backend's Runner store is THIS cache
-     *  wrapper, so without forwarding `noteTaskRun?.()` silently no-ops and lastRunId stays null (review BLOCKER). Pure
-     *  pass-through to the inner store's in-mem map — no cache interaction. (TiDB/PG don't implement it → not bound.)
-     *  Return type matches core's `SessionStore.noteTaskRun?(): void | Promise<void>` (review: don't narrow to void).
-     *  [ref](core 5.65 增量批):第三参 = engine runId。绑定用的是 `.bind(inner)`(整函数),运行期本就
-     *  三参全转 —— 这里把**声明**对齐到 core 的三参形,免得读这行类型的人以为缝上只有两参(fork-routing
-     *  的两参形正是在运行期真丢过第三参的那个病,同批修)。内店(LocalSessionStore)今日仍是两参消费,
-     *  runId 落地候 sessions 列表 wire 键的 spec 节拍(见本批提货报告件1b)。 */
-    readonly noteTaskRun?: (sessionId: string, taskId: string, runId?: string) => void | Promise<void>;
     /** Write-once auto-title (SQL twins + local sidecar carry it; pure pass-through). */
     readonly setTitleIfNull?: (sessionId: string, title: string) => Promise<boolean>;
     readonly probeTitle?: (sessionId: string) => Promise<"none" | "untitled" | "titled">;

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

@@ -11,7 +11,6 @@ export class CachingSessionStore {
     listSessions;
     fork;
     deleteSession;
-    noteTaskRun;
     setTitleIfNull;
     probeTitle;
     readInstructionSource;
@@ -62,8 +61,6 @@ export class CachingSessionStore {
             this.recordInstructionSource = ownerAware.recordInstructionSource.bind(inner);
         if (ownerAware.fork)
             this.fork = ownerAware.fork.bind(inner);
-        if (ownerAware.noteTaskRun)
-            this.noteTaskRun = ownerAware.noteTaskRun.bind(inner);
         if (ownerAware.getLeafId)
             this.getLeafId = ownerAware.getLeafId.bind(inner);
         if (ownerAware.getHead)

package/dist/plugins/file-run-store.js

@@ -499,9 +499,15 @@ export class FileRunStore {
             const sorted = [...arr].sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime() || (a.taskId < b.taskId ? 1 : a.taskId > b.taskId ? -1 : 0));
             const latest = sorted[0];
             const latestRunId = latest.result?.runId;
-            const times = arr.map((r) => r.createdAt.getTime());
-            const last = Math.max(...times);
-            const first = Math.min(...times);
+            let last = -Infinity;
+            let first = Infinity;
+            for (const r of arr) {
+                const t = r.createdAt.getTime();
+                if (t > last)
+                    last = t;
+                if (t < first)
+                    first = t;
+            }
             summaries.push({
                 sessionId,
                 owner: latest.owner,

package/dist/plugins/leader-run-store-sql.d.ts

@@ -12,8 +12,9 @@ export interface LeaderRunRecord {
     status: LeaderRunStatus;
     /** BL-4 属主(null = 匿名/单租)。GET 的 404 门读它。 */
     owner: string | null;
-    /** 运维列表面的可读预览(**不是**完整 objective —— 名字即语义,见 DDL 列注)。 */
-    objectivePreview: string;
+    /** 运维列表面的可读预览(**不是**完整 objective —— 名字即语义,见 DDL 列注)。一个事实位,与 run 行同形:`""` = 建过、剥完没有用户正文;
+     *  `null` = 没记录(列 NULL:更早版本 / 手改留下的行;本版写点只写 `""` 或正文)。 */
+    objectivePreview: string | null;
     result?: unknown;
     error?: string;
     startedAtMs: number;

package/dist/plugins/leader-run-store-sql.js

@@ -4,6 +4,7 @@ import { isDupKeyError } from "./sql-errors.js";
 import { mysqlDriver, pgDriver, dialectJsonEncoder } from "./sql-driver.js";
 import { decodeNullableJsonColumn, foldJsonColumn, jsonColumnText, readNonNullJsonValueColumn } from "./sql-json-column.js";
 import { ensureIndexes } from "./ensure-index.js";
+import { buildObjectivePreview } from "../user-authored-text.js";
 export const LEADER_RUN_TABLE = "leader_run";
 const LEADER_RUN_STATUSES = new Set(["running", "completed", "failed", "needs_human"]);
 export const LEADER_OBJECTIVE_PREVIEW_CHARS = 160;
@@ -86,7 +87,7 @@ function mapRow(r) {
         id,
         status: statusOf(r.status, id),
         owner: r.owner == null ? null : String(r.owner),
-        objectivePreview: r.objective_preview == null ? "" : String(r.objective_preview),
+        objectivePreview: r.objective_preview == null ? null : String(r.objective_preview),
         ...(result === undefined ? {} : { result }),
         ...(error === undefined ? {} : { error }),
         startedAtMs: Number(r.started_at_ms),
@@ -104,7 +105,7 @@ export class SqlLeaderRunStore {
     async createRun(input) {
         const id = uuidv7();
         const now = Date.now();
-        const preview = input.objective.slice(0, LEADER_OBJECTIVE_PREVIEW_CHARS);
+        const preview = buildObjectivePreview(input.objective, LEADER_OBJECTIVE_PREVIEW_CHARS);
         const params = [id, input.idemKey, input.owner, preview, "running", now];
         try {
             await this.db.query(this.q(`INSERT INTO ${LEADER_RUN_TABLE} (leader_run_id, idem_key, owner, objective_preview, status, started_at_ms) VALUES (?,?,?,?,?,?)`, `INSERT INTO ${LEADER_RUN_TABLE} (leader_run_id, idem_key, owner, objective_preview, status, started_at_ms) VALUES ($1,$2,$3,$4,$5,$6)`), params);