@sema-agent/server 7.148.0 → 7.150.0

package/dist/park-row-commit.d.ts

@@ -0,0 +1,67 @@
+/**
+ * **卡已提交之后,停驻的唯一提交点** —— run 行的停驻写(`setSuspended` / `setNeedsReview`:对本腿持有的这条行的 CAS,保 `task_active` 认领)。
+ *
+ * 引擎交回停驻之前已把卡落进 checkpoint 店(卡已提交):这条 run 此刻在等那张卡。腿的收场只由行的这一笔写回答,规则一句 ——
+ * **店答出的拒是答案,店的故障不是**(与续跑认领之后的提交同一条律、同一对类别词:店答出 = `refused`,店没答出来 = `faulted`;
+ * 判在写口的两只出口上,结构判 —— 交回值 vs 抛 —— 不读错误文案)。
+ *
+ * 停驻写的 CAS = **行仍归本腿(持有腿 `legId`,认领交给本腿的那一只)∧ 仍在跑(或已停在本词上)∧ 没挂取消请求**(三件的属主 = 店的两只写口,
+ * `run-store-sql.ts` 的 `setSuspended` 头注;内存 / 文件孪生同判)。第一笔与每一次再提交是**同一个形**:写;店答出「不」⇒ 读行、由行答 ——
+ *  · 行不在 ⇒ 兑现卡的 run 没了 ⇒ 作废卡(`card-void.ts` 的结算作废;卡的命运跟着行,行先、卡后);
+ *  · 行已终局(不论哪条腿持有)⇒ run 收场了 ⇒ 作废卡(已不 pending 的卡作废是空操作);
+ *  · 行归别的腿、还活着(在跑 / 停驻)⇒ 本腿先前那一笔落下了、卡被决、下一条腿接走了这条行(重开的同一张卡此刻归它)⇒ 停驻成立过,不写、卡不碰;
+ *  · 行归本腿、停在本词上 ⇒ 本腿先前那一笔落下了(一笔抛了的写结局未知)⇒ 停驻成立;
+ *  · 行归本腿、在跑、挂着取消请求(`POST /v1/runs/:id/cancel` 对在跑行只置旗)⇒ 取消先到:先作废卡、再落取消终局
+ *    (唯一铸点 `mintCancelledResult`,码 `cancelled`)—— 不把一次已答「取消中」的 run 停成可决的停驻;
+ *  · 行归本腿、在跑、没挂取消 ⇒ 店自相矛盾(CAS 说不、读说该写)= 不变量破 ⇒ 响亮记一次(`server.park.row-commit-contradicted`,带 taskId 与读到的词),
+ *    再当店故障处置(下面的再提交路)。
+ * 店故障(写 / 读 / 收场写抛:故障 / 超时 / 程序错)= `faulted` ⇒ **不收场**:不落 failed、不作废卡、认领原样留着,同一笔停驻再提交 ——
+ * 当拍一次,仍没答出 ⇒ 按心跳节拍续,直到店答出。上界 = 这台部署判活窗的两倍(`REAP_RUN_STALE_SEC`:一窗让这条不再有心跳的行落到既有的
+ * 失联判决射程里,一窗让判决落下、被下一次再提交读到 —— 读到即作废卡)。过了上界仍没答 ⇒ 停手,交既有出路:行由失联收割(`reapStale` /
+ * 观察口)按同一只判活窗收成 failed、放认领,卡由审批兜底收割按它的截止 / 绝对兜底时刻作废。不新造出路。
+ * 停驻的账本投影(停驻帧、它之前的用量差)不在这里:写口 `appendParkRow` 写不下只留痕,不改判词。
+ */
+import { type CardRef, type CardVoidPort } from "./card-void.js";
+import type { RunStore } from "./plugins/store-backend.js";
+import { type PersistedTaskResult, type RunRecord } from "./plugins/store-contracts.js";
+import type { ParkLedgerEventType } from "./trace/ledger-events.js";
+/**
+ * 一次停驻提交交回的读数(调用方按它收场,三形穷举):
+ *  · `parked` —— 停驻成立(这一笔落下,或本腿先前那一笔已落下 —— 此后行可能已交给接手腿);
+ *  · `pending` —— 店故障,再提交在续(行留 `running`、卡待决);
+ *  · `ended` —— 这条 run 没有停住、已收场:`row` = 提交点读到 / 写下之后读回的那一行(终局;`undefined` = 行不在),卡已交作废。
+ *    这次收场是不是取消,读行的码(`row.errorCode === "cancelled"`,终局码的唯一读法)。
+ */
+export type ParkCommitOutcome = {
+    readonly kind: "parked";
+} | {
+    readonly kind: "pending";
+} | {
+    readonly kind: "ended";
+    readonly row: RunRecord | undefined;
+};
+export interface ParkRowCommit {
+    readonly runStore: Pick<RunStore, "setSuspended" | "setNeedsReview" | "getRun" | "setTerminal">;
+    readonly taskId: string;
+    /** 停在哪个词上(同一扇门的词:`plan_review` 落 `needs_review`,其余落 `suspended`)。 */
+    readonly word: ParkLedgerEventType;
+    /** 落在行上的结果(店入口再封口;`null` = 这条腿手里没有停驻结果 —— 重开 / 放回 / 兜底腿)。 */
+    readonly result: PersistedTaskResult | null;
+    /** 这次停驻在等的那张卡(凭据 + 它应归的会话 = 本 run 的会话)。店答出 run 已收场 ⇒ 作废的就是它。 */
+    readonly card: CardRef;
+    /** 读卡 / 作废的 checkpoint 店(缺席 ⇒ 作废那一步响亮留痕,见 `card-void.ts`)。 */
+    readonly cards: CardVoidPort | undefined;
+    /** 探针行上的产地(`leg=<…>`)。 */
+    readonly leg: "bg" | "resume" | "sync";
+    /** 本腿的持有腿(`RunRecord.legId`):认领交给本腿的那一只 —— 建行 `createRun` 的 `{ ok: true, legId }`、续跑认领 `markResuming` 的交回值。
+     *  停驻写只许它落下;拒后判拿它比行上的那一只。不是读来的:读到的持有腿可能已是接手腿的。 */
+    readonly legId: string;
+    /** 这台部署的判活窗(ms,`REAP_RUN_STALE_SEC` × 1000,活配置);缺席 ⇒ 缺省窗(不经装配直接调用的嵌入方 / 夹具)。 */
+    readonly staleWindowMs: number | undefined;
+}
+/**
+ * 提交一次停驻(见模块头注)。不抛:第一笔抛 ⇒ 当拍再提交一次,仍抛 ⇒ 交回 `pending` 并起续提交;每一次失败、以及到上界停手,都经 F 类 tag
+ * `server.park.row-commit-deferred` 计数 + 探针行(detail `leg=<…> step=<first|again|retry|gave_up> err=<原句>`,不含凭据)。
+ */
+export declare function commitParkRow(c: ParkRowCommit): Promise<ParkCommitOutcome>;
+//# sourceMappingURL=park-row-commit.d.ts.map

package/dist/park-row-commit.js

@@ -0,0 +1,76 @@
+import { voidPendingCard } from "./card-void.js";
+import { LIVENESS_HEARTBEAT_MS } from "./config-invariants.js";
+import { RUN_STALE_SEC_DEFAULT } from "./run-stale-default.js";
+import { mintCancelledResult } from "./run-cancel-context.js";
+import { errorText } from "./observability/err-text.js";
+import { recordFailOpen } from "./observability/fail-open.js";
+import { isTerminalRunStatus } from "./plugins/store-contracts.js";
+const DEFERRED_TAG = "server.park.row-commit-deferred";
+const CONTRADICTED_TAG = "server.park.row-commit-contradicted";
+const VOID_TAG = "server.park.held-card-void-failed";
+const CANCELLED_WHILE_PARKING = "cancelled before its park was committed (the pending approval was settled)";
+const PARK_WRITE = {
+    suspended: (s, taskId, result, legId) => s.setSuspended(taskId, result, legId),
+    needs_review: (s, taskId, result, legId) => s.setNeedsReview(taskId, result, legId),
+};
+async function ended(c, row, at) {
+    await voidPendingCard(c.card, c.cards, VOID_TAG, `leg=${c.leg} at=${at}`);
+    return { kind: "ended", row };
+}
+async function settleByRow(c, row) {
+    if (row === undefined || isTerminalRunStatus(row.status))
+        return ended(c, row, "park_commit_refused");
+    if (row.legId !== c.legId)
+        return { kind: "parked" };
+    if (row.status !== "running")
+        return { kind: "parked" };
+    if (row.cancelRequested) {
+        await voidPendingCard(c.card, c.cards, VOID_TAG, `leg=${c.leg} at=park_commit_cancelled`);
+        const cancelled = mintCancelledResult({ taskId: c.taskId, sessionId: row.sessionId, startedAtMs: Date.parse(row.createdAt), message: CANCELLED_WHILE_PARKING, cause: "cancel_verb" });
+        await c.runStore.setTerminal(c.taskId, "failed", cancelled, CANCELLED_WHILE_PARKING);
+        return { kind: "ended", row: await c.runStore.getRun(c.taskId) };
+    }
+    recordFailOpen(CONTRADICTED_TAG, `leg=${c.leg} taskId=${c.taskId} word=${c.word} status=${row.status} holder=self cancel=false`);
+    throw new Error(`park commit: the store refused the ${c.word} write of run ${c.taskId} while its row reads as this leg's, running, with no cancel request`);
+}
+async function attempt(c) {
+    if ((await PARK_WRITE[c.word](c.runStore, c.taskId, c.result, c.legId)) !== false)
+        return { kind: "parked" };
+    return settleByRow(c, await c.runStore.getRun(c.taskId));
+}
+export async function commitParkRow(c) {
+    try {
+        return await attempt(c);
+    }
+    catch (e) {
+        recordFailOpen(DEFERRED_TAG, `leg=${c.leg} step=first err=${errorText(e)}`);
+    }
+    try {
+        return await attempt(c);
+    }
+    catch (e) {
+        recordFailOpen(DEFERRED_TAG, `leg=${c.leg} step=again err=${errorText(e)}`);
+    }
+    continueParkCommit(c);
+    return { kind: "pending" };
+}
+function continueParkCommit(c) {
+    const untilMs = Date.now() + 2 * (c.staleWindowMs ?? RUN_STALE_SEC_DEFAULT * 1000);
+    let inFlight = false;
+    const timer = setInterval(() => {
+        if (inFlight)
+            return;
+        inFlight = true;
+        void attempt(c).then(() => clearInterval(timer), (e) => {
+            inFlight = false;
+            if (Date.now() < untilMs) {
+                recordFailOpen(DEFERRED_TAG, `leg=${c.leg} step=retry err=${errorText(e)}`);
+                return;
+            }
+            clearInterval(timer);
+            recordFailOpen(DEFERRED_TAG, `leg=${c.leg} step=gave_up err=${errorText(e)}`);
+        });
+    }, LIVENESS_HEARTBEAT_MS);
+    timer.unref?.();
+}
+//# sourceMappingURL=park-row-commit.js.map

package/dist/parked-decide.d.ts

@@ -16,8 +16,10 @@ import type { ParkedReviveSurfaceFactory } from "./parked-revive-surface.js";
 import type { RebuiltInheritedGate } from "./boot/parked-revive-gate.js";
 import { type WorkflowRunParkKey, type WorkflowAgentSessionIndex } from "./orchestration/workflow-agent-session-index.js";
 import type { WorkflowParkDecisionStore, WorkflowParkOutcome } from "./orchestration/workflow-park-decision.js";
+import { type ApprovalLegOrigin } from "./approval-leg-origin.js";
 import type { SessionFace } from "./session-incarnation.js";
-import { type ExecutionCommitDeps, type RootedExecutionContext } from "./http/execution-context.js";
+import { type CardSettlePort } from "./card-settle-stored-scope.js";
+import { type ClaimFace, type ExecutionCommitDeps, type RootedExecutionContext } from "./http/execution-context.js";
 import type { GateIdentity } from "./checkpoint-identity.js";
 /**
  * 本腿的**装配前提**(`createHttpServer` 起服拒的拒句;规则见 {@link ParkedDecideDeps} 的 `execution`):接了本腿(`parkedReviveSurface` 在场)的部署,
@@ -155,8 +157,8 @@ export declare function findParkedAgentForCheckpoint(agentStore: BackgroundAgent
 }): Promise<ParkedAgentMatch | undefined>;
 export interface ParkedDecideDeps {
     agentStore: BackgroundAgentStore;
-    /** `expire`:[ref] deny 作废复活不了的卡(按卡自己的 scope CAS);`get`:引擎的 claim / 对账读卡。 */
-    checkpointStore: Pick<CheckpointStore, "get" | "expire">;
+    /** `expire` + `peekScopeByToken` + 状态读:[ref] deny 作废复活不了的卡(`expireCardUnderStoredScope`:先读状态、再按店里该卡的属主格 CAS);`get`:引擎的 claim / 对账读卡。 */
+    checkpointStore: Pick<CheckpointStore, "get" | "expire"> & CardSettlePort;
     /** 与 reaper/scenarios 同一个 registry(claim/rollback 的 CAS 与 in-memory handle 收敛在同处;[ref] 作废之后的对账也是它)。 */
     registry: Pick<TaskRegistry, "claimParkedAgent" | "rollbackParkedClaim" | "reconcileParkedAgents">;
     /** [ref](core 7.32.0):按**行**解析赎回面 —— 驱动哪一只 Agent 工具(生产装配,与 spawn 同源:subRunner / bg opts /
@@ -188,19 +190,19 @@ export interface ParkedDecideDeps {
         owner: string | null;
         taskId: string;
         sessionId: string;
-        executionLane: import("./execution-lane-caps.js").ExecutionLane;
-    }) => NonNullable<ToolExecuteContext["onAsk"]>;
+    } & ApprovalLegOrigin) => NonNullable<ToolExecuteContext["onAsk"]>;
     /**
      * 边界 9 的执行上下文(设计 §3.2;与提交腿 / 续跑家族同一只解析器、同一只写口)—— 本腿对根会话的住客**一读一判**:
      *  · `resolve` —— **认领之前**按行的根取上下文:解析器那一次行读(执行席:住客 + 格)就是本腿对根会话的**唯一一读**;根行不在 ⇒ `gone`
-     *    (本腿答既有的 `decide.not_parked`);其余拒(mirror / 车道不再服务 / 主体的车道裁定)按续跑家族的折叠律答好交回(`answer`)—— 不认领、不驱动。
+     *    (本腿答既有的 `decide.not_parked`);其余拒(mirror / 车道不再服务 / 主体的车道裁定)按续跑家族的折叠律答好交回(`answer`);店没答出来 ⇒ 本腿交来的这一面
+     *    `face` 的瞬时答复(`answer`,与认领那一笔撞店故障同答)—— 不认领、不驱动。
      *    成功形的 `occupant` **必有**:接本腿的部署必须带执行席(无席的会话店交不出这一读;`createHttpServer` 在装配时拒无席形);
      *  · `commitDeps` —— 认领之后 `commitExecutionContext` 读的部署件:唯一写口按那一读的住客定址写 / 再读(化身 ∧ 属主),这就是认领之后对根住客的
      *    **唯一一判**(拒 ⇒ 先回滚认领)。写口放行的那一位就是赎回面的根住客见证;写口之后本腿不再读根。
      * 复活子代的审批席带这只上下文的车道(`approverSeatFor` 的 `executionLane`)。
      */
     execution: {
-        resolve: (root: string) => Promise<{
+        resolve: (root: string, face: ClaimFace) => Promise<{
             readonly ok: true;
             readonly ctx: RootedExecutionContext & {
                 readonly occupant: SessionFace;

package/dist/parked-decide.js

@@ -5,10 +5,12 @@ import { recordFailOpen } from "./observability/fail-open.js";
 import { defaultSubagentTailBus } from "./fleet/subagent-tail-bus.js";
 import { backgroundScopesForCheckpointScope, decodeCheckpointScope, ownerOfCheckpointScope } from "./security.js";
 import { ASK_USER_QUESTION_TOOL_NAME, isEngineQuestionRow } from "./approval-content-kind.js";
+import { approvalLegOriginOf } from "./approval-leg-origin.js";
 import { refusalBody, resumeRefusalFacts } from "./http/refusal-body.js";
 import { backgroundAgentNameOf } from "./background-agent-name.js";
 import { buildSettlementEvidence, NO_SETTLEMENT_EVIDENCE } from "./gate-settlement.js";
-import { commitExecutionContext } from "./http/execution-context.js";
+import { CARD_EXPIRE_OUTCOME, expireCardUnderStoredScope } from "./card-settle-stored-scope.js";
+import { cardWaitingRefusalAnswer, commitExecutionContext, faultedAnswerOf, isRootSessionGoneRefusal } from "./http/execution-context.js";
 import { EXECUTION_PLACEMENT_SEAT_CARRIERS } from "./execution-placement.js";
 export const PARKED_REVIVE_EXECUTION_SEAT_REQUIRED = `the parked-agent revive leg (parkedReviveSurface) needs a session store with an execution placement seat (sessionStorage.executionPlacement) — after the claim, the root session's occupant is judged only by the write on that seat; ${EXECUTION_PLACEMENT_SEAT_CARRIERS}; refusing to start rather than revive parked agents with nobody judging the root session's occupant after the claim`;
 export async function findParkOrigin(sources, cp) {
@@ -346,6 +348,15 @@ function sessionGone(taskId) {
         }),
     };
 }
+function parkedClaimFaultAnswer(taskId) {
+    return { status: 503, body: refusalBody({ errorCode: "decide.store_unreachable", message: "the stored state this decision needs could not be read or written just now (the store failed) — nothing was decided and the agent is still waiting for it; retry", facts: { taskId } }) };
+}
+function parkedRedeemFace(taskId) {
+    return {
+        refused: (refusal) => (isRootSessionGoneRefusal(refusal) ? sessionGone(taskId) : cardWaitingRefusalAnswer(refusal)),
+        faulted: () => parkedClaimFaultAnswer(taskId),
+    };
+}
 function gateMoved(taskId) {
     return { status: 409, body: refusalBody({ errorCode: "decide.gate_moved", message: "the approval gate moved under this decide (re-parked or already settled) — re-check the pending list", facts: { taskId } }) };
 }
@@ -356,7 +367,7 @@ function revivabilityOf(row, taskId) {
     return { kind: "revivable", root: row.rootSessionId };
 }
 async function voidUnrevivableCard(deps, req, match) {
-    const voided = await deps.checkpointStore.expire(req.token, req.scope);
+    const voided = (await expireCardUnderStoredScope(deps.checkpointStore, req.token)) === CARD_EXPIRE_OUTCOME.expired;
     if (!voided) {
         return gateMoved(match.handle);
     }
@@ -385,7 +396,8 @@ export async function decideParkedAgent(deps, req, match) {
     if (revivability.kind === "unrevivable")
         return req.decision === "deny" ? voidUnrevivableCard(deps, req, match) : revivability.approveRefusal;
     const root = revivability.root;
-    const resolved = await deps.execution.resolve(root);
+    const face = parkedRedeemFace(match.handle);
+    const resolved = await deps.execution.resolve(root, face);
     if (!resolved.ok)
         return resolved.gone ? sessionGone(match.handle) : resolved.answer;
     const execution = resolved.ctx;
@@ -395,7 +407,7 @@ export async function decideParkedAgent(deps, req, match) {
     if (!claim.ok) {
         switch (claim.reason) {
             case "store_unreachable":
-                return { status: 503, body: refusalBody({ errorCode: "decide.store_unreachable", message: "the durable agent store is unreachable — retry", facts: { taskId: match.handle } }) };
+                return face.faulted();
             case "claim_lost":
                 return { status: 409, body: refusalBody({ errorCode: "decide.claim_lost", message: "the parked agent is already claimed — either a concurrent decide won (re-check the pending list), or a stale claim is pending automatic cleanup (retry after the stale-claim window)", facts: { taskId: match.handle } }) };
             case "binding_broken":
@@ -428,7 +440,14 @@ export async function decideParkedAgent(deps, req, match) {
         await rollback("claimed_token_moved");
         return gateMoved(match.handle);
     }
-    const placementRefusal = await commitExecutionContext(deps.execution.commitDeps, { kind: "parked", taskId: match.handle, rollback, goneAnswer: sessionGone(match.handle) }, execution);
+    let placementRefusal;
+    try {
+        const refusal = await commitExecutionContext(deps.execution.commitDeps, { kind: "parked", taskId: match.handle, rollback }, execution);
+        placementRefusal = refusal === null ? null : face.refused(refusal);
+    }
+    catch (e) {
+        placementRefusal = faultedAnswerOf(e, face.faulted);
+    }
     if (placementRefusal)
         return placementRefusal;
     let surface;
@@ -457,7 +476,7 @@ export async function decideParkedAgent(deps, req, match) {
         ...(surface.mountsCallerTool !== undefined ? { mountsCallerTool: surface.mountsCallerTool } : {}),
         ...(surface.onBackgroundChildEvent !== undefined ? { onBackgroundChildEvent: surface.onBackgroundChildEvent } : {}),
         ...(deps.approverSeatFor !== undefined && seatRoot !== undefined
-            ? { onAsk: deps.approverSeatFor({ owner: ownerOfCheckpointScope(req.scope), taskId: match.handle, sessionId: seatRoot, executionLane: execution.lane }) }
+            ? { onAsk: deps.approverSeatFor({ owner: ownerOfCheckpointScope(req.scope), taskId: match.handle, sessionId: seatRoot, ...approvalLegOriginOf(execution) }) }
             : {}),
         reviveClaim: {
             row: { ...ticket.row, parkClaimId: ticket.claimId },

package/dist/peer-directory.d.ts

@@ -18,7 +18,7 @@
  *
  * ⚠️ **共享的是谓词,不是最终集合**(codex 对抗复审 r1 ② 采纳,如实收窄 —— 稿里与本注初版都写成了
  * 「两面集合相等」,那是**过度承诺**):两面在下面这些地方按设计给出不同的集合,逐条都不是 bug ——
- *  · **fleet-wide 调用方**:`GET /v1/sessions` 对 service-token / dev-open 形不钉 owner、还认 `?owner=`
+ *  · **fleet-wide 调用方**:`GET /v1/sessions` 对不报主体的 service-token / dev-open 调用方不钉 owner、还认 `?owner=`
  *    (运维视图);目录**只**按 core 递进来的那一个 scope 分区,永不跨;
  *  · **分页与搜索**:那条路由有 `?limit`/`?cursor`/`?q=`,目录是一次定量读(见 {@link PEER_DIRECTORY_CAP});
  *  · **peer 可寻址性过滤**:语法外 / 非小写规范形 / 与别条会话折到同一只箱的 id 都不入目录(下面那道

package/dist/peer-seat.d.ts

@@ -66,7 +66,7 @@ export type PeerBinding = {
     readonly url: string;
     readonly cardUrl?: string;
 };
-/** Why the seat refused a question. Closed: a new word is a new arm of `answer`'s switch. */
+/** Why the seat refused a question. Closed: a word belongs to a row of the seat's per-kind table (or to the handle row's own two refusals). */
 export type PeerSeatRefusalReason = "handle_not_held" | "binding_mismatch" | "kind_env" | "kind_vault" | "kind_assertion" | "kind_unknown";
 /**
  * The desk's own failures, each loud:

package/dist/peer-seat.js

@@ -151,67 +151,60 @@ export function createPeerDesk(opts = {}) {
                 return { kind: "carry", env: entry.pieces };
         }
     };
-    const handleIdOf = (ref) => {
-        switch (ref.kind) {
-            case "handle":
-                return ref.id;
-            case "env":
-            case "vault":
-            case "assertion":
-                return undefined;
-            default: {
-                const unknownKind = ref;
-                void unknownKind;
-                return undefined;
-            }
-        }
+    const notMintedHold = () => {
+        throw new Error("peer desk: hold of a reference this desk did not mint — not held");
     };
-    const seat = Object.freeze({
-        hold: (ref) => {
-            const id = handleIdOf(ref);
-            if (id === undefined)
-                throw new Error("peer desk: hold of a reference this desk did not mint — not held");
-            const entry = table.get(id);
-            if (entry === undefined)
-                throw new Error("peer desk: hold of a handle whose entry is gone — not held (a hold never revives an entry)");
-            entry.engineHolds += 1;
-        },
-        release: (ref) => {
-            const id = handleIdOf(ref);
-            if (id === undefined)
-                throw new Error("peer desk: release of a reference this desk did not mint — nothing released");
-            const entry = table.get(id);
-            if (entry === undefined || entry.engineHolds === 0)
-                throw new Error("peer desk: release of a handle with no counted engine hold — nothing released");
-            entry.engineHolds -= 1;
-            dropIfUnheld(id, entry);
+    const notMintedRelease = () => {
+        throw new Error("peer desk: release of a reference this desk did not mint — nothing released");
+    };
+    const notMinted = (reason) => ({
+        answer: (_ref, question) => refuse(question.peer, reason),
+        hold: notMintedHold,
+        release: notMintedRelease,
+    });
+    const seatKinds = {
+        handle: {
+            answer: (ref, question) => {
+                const target = question.peer;
+                const entry = table.get(ref.id);
+                if (entry === undefined)
+                    return refuse(target, "handle_not_held");
+                if (!sameBinding(entry.binding, bindingOf(target)))
+                    return refuse(target, "binding_mismatch");
+                return carry(entry);
+            },
+            hold: (ref) => {
+                const id = ref.id;
+                if (id === undefined)
+                    return notMintedHold();
+                const entry = table.get(id);
+                if (entry === undefined)
+                    throw new Error("peer desk: hold of a handle whose entry is gone — not held (a hold never revives an entry)");
+                entry.engineHolds += 1;
+            },
+            release: (ref) => {
+                const id = ref.id;
+                if (id === undefined)
+                    return notMintedRelease();
+                const entry = table.get(id);
+                if (entry === undefined || entry.engineHolds === 0)
+                    throw new Error("peer desk: release of a handle with no counted engine hold — nothing released");
+                entry.engineHolds -= 1;
+                dropIfUnheld(id, entry);
+            },
         },
-        answer: async (question) => {
-            const target = question.peer;
-            const ref = target.credentials;
-            if (ref === undefined)
-                return { kind: "carry" };
-            switch (ref.kind) {
-                case "handle": {
-                    const entry = table.get(ref.id);
-                    if (entry === undefined)
-                        return refuse(target, "handle_not_held");
-                    if (!sameBinding(entry.binding, bindingOf(target)))
-                        return refuse(target, "binding_mismatch");
-                    return carry(entry);
-                }
-                case "env":
-                    return refuse(target, "kind_env");
-                case "vault":
-                    return refuse(target, "kind_vault");
-                case "assertion":
-                    return refuse(target, "kind_assertion");
-                default: {
-                    const unknownKind = ref;
-                    void unknownKind;
-                    return refuse(target, "kind_unknown");
-                }
-            }
+        env: notMinted("kind_env"),
+        vault: notMinted("kind_vault"),
+        assertion: notMinted("kind_assertion"),
+    };
+    const unknownKind = notMinted("kind_unknown");
+    const rowOf = (ref) => (Object.hasOwn(seatKinds, ref.kind) ? seatKinds[ref.kind] : unknownKind);
+    const seat = Object.freeze({
+        hold: (ref) => rowOf(ref).hold(ref),
+        release: (ref) => rowOf(ref).release(ref),
+        answer: async (question, signal) => {
+            const ref = question.peer.credentials;
+            return ref === undefined ? { kind: "carry" } : rowOf(ref).answer(ref, question, signal);
         },
     });
     return Object.freeze({

package/dist/plugins/adoption-log-sql.d.ts

@@ -193,9 +193,9 @@ export declare class SqlAdoptionLogStore implements AdoptionLogStore {
     /**
      * 收编弧的 advisory 锁(183 I1 的 form b 形:「与任何活写互斥」在 SQL 侧 = 一次只有一个副本在推这条弧)。
      *
-     * **非阻塞取 + 有界轮询**(tidb-pool 的 `acquireEnsureSchemaLock` 同款判据:阻塞式 GET_LOCK 会把并发
-     * 调用方全部park 在 TiDB 的悲观锁行上,既耗它的重试预算又饿死应用自己的 FOR UPDATE 路)。取不到 ⇒
-     * 返回 `undefined`,调用方按「在飞」应答 —— **不假装成功,也不无限等**。
+     * **非阻塞取 + 有界轮询**(阻塞式 GET_LOCK 会把并发调用方全部 park 在 TiDB 的悲观锁行上,既耗它的重试预算又饿死应用自己的 FOR UPDATE 路)。
+     * 取锁走本仓**唯一的取锁器**(`ensure-schema-lock-policy.ts` 的 {@link acquireAdvisoryLockWithin}):探针句、答案读法、TiDB「悲观锁重试上限」
+     * 读成「别人持着」、坏连接计数全在那里,本店不自带第二只探针。取不到 ⇒ 返回 `undefined`,调用方按「在飞」应答 —— **不假装成功,也不无限等**。
      *
      * 🔴 入参 `name` 是**逻辑**锁名(`adoptionLockName(fromPrincipal)`);真正发给引擎的是它被
      * {@link qualifyAdoptionLockName} 限定到本库之后的形([ref]:两方言键空间不等价)。限定发生在

package/dist/plugins/adoption-log-sql.js

@@ -1,6 +1,7 @@
 import { writeLogText } from "../observability/logger.js";
 import { createHash } from "node:crypto";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
+import { acquireAdvisoryLockWithin, releaseAdvisoryLock } from "./ensure-schema-lock-policy.js";
 import { ensureIndexes } from "./ensure-index.js";
 export const ADOPTION_LOG_TABLE = "adoption_log";
 export const ADOPTION_PHASE = {
@@ -77,6 +78,18 @@ const PG_ADOPTION_LOCK_CLASS = 4907;
 function pgLockObjectKey(name) {
     return createHash("sha256").update(name).digest().readInt32BE(0);
 }
+function arcLockId(dialect, qualifiedName) {
+    switch (dialect) {
+        case "mysql":
+            return { dialect, name: qualifiedName };
+        case "pg":
+            return { dialect, keys: [PG_ADOPTION_LOCK_CLASS, pgLockObjectKey(qualifiedName)] };
+        default: {
+            const unreachable = dialect;
+            throw new Error(`unreachable SQL dialect: ${String(unreachable)}`);
+        }
+    }
+}
 export function adoptionLockName(fromPrincipal) {
     return `sema_adoption:${createHash("sha256").update(fromPrincipal).digest("hex").slice(0, 32)}`;
 }
@@ -188,30 +201,17 @@ export class SqlAdoptionLogStore {
     }
     async withLock(name, fn, attempts = 20, sleepMs = 100) {
         const conn = await this.db.connect();
-        let held = false;
-        let lockName = "";
+        let held;
         try {
-            lockName = qualifyAdoptionLockName(await this.resolveLockKeyspace(conn), name);
-            for (let i = 0; i < attempts && !held; i += 1) {
-                const res = await conn.query(this.q("SELECT GET_LOCK(?, 0) AS got", "SELECT pg_try_advisory_lock($1, $2) AS got"), this.db.dialect === "mysql" ? [lockName] : [PG_ADOPTION_LOCK_CLASS, pgLockObjectKey(lockName)]);
-                const got = res.rows[0]?.got;
-                held = got === 1 || got === true || got === "1";
-                if (!held)
-                    await new Promise((r) => setTimeout(r, sleepMs));
-            }
-            if (!held)
+            const lock = arcLockId(this.db.dialect, qualifyAdoptionLockName(await this.resolveLockKeyspace(conn), name));
+            if (!(await acquireAdvisoryLockWithin(conn, lock, "adoption-log", attempts, sleepMs)))
                 return undefined;
+            held = lock;
             return await fn(conn);
         }
         finally {
-            if (held) {
-                try {
-                    await conn.query(this.q("SELECT RELEASE_LOCK(?) AS released", "SELECT pg_advisory_unlock($1, $2) AS released"), this.db.dialect === "mysql" ? [lockName] : [PG_ADOPTION_LOCK_CLASS, pgLockObjectKey(lockName)]);
-                }
-                catch (releaseErr) {
-                    writeLogText("stderr", "[adoption-log] releasing the adoption arc lock failed (it auto-frees when the connection closes):", releaseErr);
-                }
-            }
+            if (held !== undefined)
+                await releaseAdvisoryLock(conn, held, "adoption-log");
             conn.release();
         }
     }

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

@@ -715,7 +715,7 @@ export declare function ensurePgApprovalAskSchema(q: PgQueryFn): Promise<void>;
  *
  * 判据 = **能力探测**(恒空的 `WHERE 1=0` 读)+ **方言的缺列错误码**(判据属主 `sql-errors.ts` 的
  * {@link isMissingColumnError});其余错误**原样 rethrow**,一个字都不加工 —— 把一次瞬时故障诊断成「缺列」的拒因
- * 比它要挡的缺陷更贵([ref] 那两轮收窄的结论逐字继承)。拒因的出路是**闭集三条**(与整库对账同一份,{@link describeProbedTableDrift}),没有销毁性的一条。
+ * 比它要挡的缺陷更贵([ref] 那两轮收窄的结论逐字继承)。拒因的出路是**闭集三条**(与整库对账同一份,{@link probedMissingColumnRefusal}),没有销毁性的一条。
  *
  * 🔴 位置与两条先例同款:**不在** `ensureSchema` 里(那条通道的契约是「只发 CREATE」,有运行时门看着),
  * 放在 DDL 之后、任何路由装配之前;且**只在流内审批协议真会上场时**跑(判据 = 与协调器同一个符号

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

@@ -4,7 +4,7 @@ import { ASK_TERMINAL, canAskTransition } from "../approval-ask-machine.js";
 import { DECIDED_VIA } from "@sema-agent/core";
 import { APPROVAL_ENDING_CAUSES, askRowEndingCause, askRowParkTrigger } from "../approval-deny-reasons.js";
 import { isDupKeyError, isMissingColumnError } from "./sql-errors.js";
-import { describeProbedTableDrift } from "./schema-drift-sentence.js";
+import { probedMissingColumnRefusal } from "./schema-drift-sentence.js";
 import { decodeJsonColumn, foldJsonColumn, jsonColumnText, readJsonObjectColumn, readTriStateJsonValueColumn } from "./sql-json-column.js";
 import { ensureIndexes } from "./ensure-index.js";
 import { isExecutionLane } from "../execution-lane-caps.js";
@@ -334,7 +334,7 @@ export async function assertApprovalAskRuleMaterialSchema(query, dialect) {
     catch (err) {
         if (!isMissingColumnError(err, dialect))
             throw err;
-        throw new Error(`${APPROVAL_ASK_TABLE} is missing the #363 rule-material columns (rule_command / rule_scope_root) and/or the S-26 edited-input column (updated_input) — refusing to start. ` +
+        throw await probedMissingColumnRefusal(query, dialect, [APPROVAL_ASK_TABLE], `${APPROVAL_ASK_TABLE} is missing the #363 rule-material columns (rule_command / rule_scope_root) and/or the S-26 edited-input column (updated_input) — refusing to start. ` +
             `A parked approval's late decision can now carry \`persistRule\` ("don't ask again"), and the row is where the ` +
             `adjudicated command and the project root of the authorization site live; a decision's edited input (ctrl+g) is ` +
             `persisted on the row too, so a replica that does not hold the waiting leg replays the approved bytes; every ask-row ` +
@@ -342,9 +342,7 @@ export async function assertApprovalAskRuleMaterialSchema(query, dialect) {
             `is persisted, the replay list stays empty, late decisions 404) while /v1/capabilities still reports it active. ` +
             `The table holds IN-FLIGHT approval asks (cards awaiting an answer) plus settled bookkeeping; the durable park face ` +
             `(checkpoint rows) and the persisted rules themselves are untouched, so an in-flight card falls back to the durable gate ` +
-            `(\`POST /v1/approvals/:sessionId/decide\`) until the columns exist.\n` +
-            `Underlying probe error: ${err instanceof Error ? err.message : String(err)}\n\n` +
-            (await describeProbedTableDrift(query, dialect, [APPROVAL_ASK_TABLE])));
+            `(\`POST /v1/approvals/:sessionId/decide\`) until the columns exist.`, err);
     }
 }
 function askCols(dialect) {

package/dist/plugins/approval-exemption-skill-cutoff.d.ts

@@ -0,0 +1,64 @@
+import type { Logger } from "../observability/logger.js";
+import type { RetiredSchemaProbeTarget } from "./schema-consistency.js";
+import type { SqlDialect } from "./sql-driver.js";
+import { StoreBootRefusalError } from "./store-contracts.js";
+/** 被判的行的 wire 工具名 —— 引擎 `Skill` 工具的名字,core 导出(不手抄;core 改名 ⇒ 谓词跟着走)。 */
+export declare const SKILL_EXEMPTION_TOOL_NAME: string;
+/** 第一只落截点、删截点之前的行的版本(一次性迁移 M46 的引入版本;登记表 M46 行在时两者逐字相同 —— `test/approval-exemption-skill-cutoff.test.ts` 钉)。拒句点名的出路版本下限。 */
+export declare const SKILL_EXEMPTION_CUTOFF_SINCE = "7.148.0";
+/** local 车道的截点文件(数据根顶层;文件名沿用 M46 —— 7.148.0 起的数据根里已经是它)。 */
+export declare const LOCAL_SKILL_EXEMPTION_CUTOFF_FILE = "one-time-migration-M46.marker";
+/** 截点之前的行写下时的意思与今天读法的差 —— SQL 拒句与 local 读数段同一句。 */
+export declare const PRE_CUTOFF_SKILL_EXEMPTION_CONSEQUENCE: string;
+/** 判用的读口:一句带参数的查询 ⇒ 行。 */
+type CutoffQuery = (sql: string, params?: readonly unknown[]) => Promise<Array<Record<string, unknown>>>;
+/**
+ * **SQL 截点的唯一读者**(常设臂与一次性迁移 M46 的删句同读;调用方先确认标记表在):行不在 ⇒ `undefined`(缺席);行在而读不出时刻 ⇒ 拒启 {@link StoreBootRefusalError}
+ * —— 不按「此刻」、也不按「没有」猜(非法时刻进比较,驱动把它写成 `NULL`,`created_at < NULL` 数出 0 = 静默放行)。拒句只带读到的数值与出路。
+ */
+export declare function readSqlSkillExemptionCutoff(query: CutoffQuery, dialect: SqlDialect): Promise<number | undefined>;
+/**
+ * SQL 腿的拒启:这只库里有首次放行早于截点(或截点缺席)的 `Skill` 豁免行,而本构建已不带删它们的一次性迁移。**具名类型**(族基类 {@link StoreBootRefusalError}:
+ * 起服降级臂不吞、开库等待窗不重试);码与退役 schema / 列册对账同一个 `config.schema_mismatch`。拒句只带行数、截点与工具名(行的会话 / 放行人不进句子)。
+ */
+export declare class LegacySkillExemptionsPresentError extends StoreBootRefusalError {
+    /** 截点之前的 `Skill` 行数。 */
+    readonly rows: number;
+    /** 截点(ISO 时刻;`null` = 这只库没记截点:从没在落截点的版本上起过服)。 */
+    readonly cutoff: string | null;
+    /** 机读码(与退役 schema / 列册对账的拒启同一个)。 */
+    readonly code = "config.schema_mismatch";
+    constructor(
+    /** 截点之前的 `Skill` 行数。 */
+    rows: number, 
+    /** 截点(ISO 时刻;`null` = 这只库没记截点:从没在落截点的版本上起过服)。 */
+    cutoff: string | null);
+}
+/**
+ * SQL 腿的判(纯读,**唯一一只**;律见文件头):读截点({@link readSqlSkillExemptionCutoff};标记表不在 ⇒ 缺席,读不出 ⇒ 拒 —— `carried` 也判,建表之前)→
+ * `carried`(本构建还带 M46)或豁免表不在(新库,建表之前)⇒ 无事 → 数截点之前的 `Skill` 行(截点缺席 ⇒ 全部 `Skill` 行)→ 非零 ⇒ 拒。
+ * 谓词与 M46 的删句同一条,比较在库里做(`created_at < ?`,参数是截点的 `Date`)。读抛 ⇒ 原样上抛(判不了 ⇒ 不放行;不是确定的拒启表态)。
+ */
+export declare function judgeSqlSkillExemptionCutoff(query: CutoffQuery, dialect: SqlDialect, carried: boolean): Promise<void>;
+/**
+ * **探针口**(SQL 腿的判唯一的读处;唯一调用点 = `store-backend.ts` 的 `withRetiredSchemaProbe`,先于第一条 CREATE):借一条连接判一次、用完即还(拒时连接也已归还);
+ * `carried`(本构建还带 M46)⇒ 只验截点读得出、不数行(存量行交给 M46 删)。不取 `ensureSchema` 那把锁:纯读。
+ */
+export declare function assertSkillExemptionCutoffHeldOnPool(target: RetiredSchemaProbeTarget, carried: boolean): Promise<void>;
+/** local 截点文件正文 ⇒ T0(epoch 毫秒);读不出时刻 ⇒ `undefined`(调用方决定拒形:准入点名文件拒、M46 的腿拒并给「删掉再起」)。 */
+export declare function skillExemptionCutoffOfText(text: string): number | undefined;
+/** 写截点文件(原子、`required`:目录项没证落盘也算没写成 ⇒ 抛)。本车道截点文件唯一的写口:准入的锁内一步与 M46 的腿同调。 */
+export declare function writeLocalSkillExemptionCutoff(path: string, cutoffMs: number): void;
+/**
+ * 截点之前的 `Skill` 行所在的会话数(`cutoffMs` 缺席 ⇒ 任一 `Skill` 行都算):逐只日志经店的唯一读者 {@link readExemptionLog} 重放(同一套撤销 / 首次放行读法);
+ * 闸合上的日志不算(店对那只会话拒读、照问)。坏行的披露走 `warn`(缺席 ⇒ 日志接缝;同一次起服里店的 hydrate 会再披露一次)。
+ */
+export declare function localSkillExemptionSessionsBefore(root: string, cutoffMs: number | undefined, warn?: Logger["warn"]): number;
+/** 豁免日志目录的指纹(文件名 · 字节数 · 修改时刻;按名排序)—— 准入与锁内「没动」核对比同一只(锁内不再重放日志)。 */
+export declare function exemptionLogFingerprints(root: string): string[];
+/** 截点在 local 上的动作(准入判、锁内做):`lay` = 截点缺席,落「此刻」;`none` = 不写。 */
+export type SkillExemptionCutoffAction = "none" | "lay";
+/** **落截点**(锁内;准入的读数核过之后、抬引擎版本高水位之前;唯一调用点 = 数据根准入的锁内一步)。写不进 ⇒ 抛(抬之前拒)。 */
+export declare function settleLocalSkillExemptionCutoff(physicalRoot: string, action: SkillExemptionCutoffAction, now?: () => number): void;
+export {};
+//# sourceMappingURL=approval-exemption-skill-cutoff.d.ts.map