@sema-agent/server 7.147.0 → 7.149.0

package/dist/parked-decide.js

@@ -1,13 +1,16 @@
+import { FORK_SUBAGENT_TYPE, redeemWorkflowParks, subscribeWorkflow } from "@sema-agent/core";
 import { readClosedWordSeat } from "./approval-card.js";
 import { routeWorkflowPark } from "./orchestration/workflow-agent-session-index.js";
 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 } from "./gate-settlement.js";
-import { commitExecutionContext } from "./http/execution-context.js";
+import { buildSettlementEvidence, NO_SETTLEMENT_EVIDENCE } from "./gate-settlement.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) {
@@ -122,13 +125,32 @@ function refusesWhereUnrecordable(remember) {
         }
     }
 }
-function mintReviveArgs(row, knownAgentTypes) {
+function reviveDefinitionOf(row, reviveTool) {
+    if (row.agentType === undefined)
+        return { kind: "revivable", agentType: undefined };
+    const revivable = (reviveTool.ruleFace?.nameValues ?? []).filter((t) => t !== FORK_SUBAGENT_TYPE);
+    return revivable.includes(row.agentType) ? { kind: "revivable", agentType: row.agentType } : { kind: "unavailable" };
+}
+function denyAgentDefinitionUnavailable(taskId, rollback) {
+    return {
+        status: 409,
+        body: refusalBody({
+            errorCode: "decide.agent_definition_unavailable",
+            message: "this approval belongs to a background agent that was started from an agent definition the revive path cannot supply again: a definition sent on the request that started the run is not kept with the approval card, and a deployment definition may have been withdrawn since the agent stopped. Reviving the agent without it would resume it as a general-purpose agent, with a wider tool surface than its definition allowed, so the decision is NOT applied and nothing was resumed. The rollback field says what became of the approval: rolled_back means the card is still pending (it ends by expiry, or when the session's background agents are retired), failed means it had already ended, retry and lost mean read the pending list for its fate. Start the work from a built-in or deployment definition to get an agent whose approval can be decided here",
+            facts: {
+                taskId,
+                rollback,
+            },
+        }),
+    };
+}
+function mintReviveArgs(row, agentType) {
     return {
         prompt: row.description ?? "resume parked agent",
         run_in_background: true,
         name: backgroundAgentNameOf(row),
         description: row.description ?? "revived agent",
-        ...(row.agentType !== undefined && knownAgentTypes.has(row.agentType) ? { subagent_type: row.agentType } : {}),
+        ...(agentType !== undefined ? { subagent_type: agentType } : {}),
     };
 }
 export function buildParkedResumeOutcome(req) {
@@ -217,6 +239,103 @@ export function planWorkflowParkedDecide(origin, req) {
         },
     };
 }
+function parkedChildResumedReceipt(taskId, decision, evidence) {
+    return { status: 200, body: { taskId, status: "resuming", decision, ...evidence } };
+}
+const LIVE_REDEEM_RECEIPTS = new Map();
+async function runChannelEnded(runId, scope) {
+    const channel = subscribeWorkflow(runId, scope)[Symbol.asyncIterator]();
+    while (!(await channel.next()).done) {
+    }
+}
+function holdLiveReceipt(run, token, fingerprint, answer) {
+    let byToken = LIVE_REDEEM_RECEIPTS.get(run.id);
+    if (byToken === undefined) {
+        byToken = new Map();
+        LIVE_REDEEM_RECEIPTS.set(run.id, byToken);
+        const book = byToken;
+        const drop = () => {
+            if (LIVE_REDEEM_RECEIPTS.get(run.id) === book)
+                LIVE_REDEEM_RECEIPTS.delete(run.id);
+        };
+        void run.ended().then(drop, (err) => {
+            recordFailOpen("server.workflow-live-receipt.channel-unreadable", `runId=${run.id} err=${err instanceof Error ? err.message : String(err)}`);
+            drop();
+        });
+    }
+    byToken.set(token, { fingerprint, answer });
+}
+const copyOf = (r) => ({ status: r.status, body: { ...r.body } });
+export async function deliverToHoldingRun(origin, d) {
+    const entry = d.restated ? { token: d.token } : { token: d.token, outcome: d.outcome };
+    const scope = origin.run.scope;
+    return answerOfParkDelivery(await redeemWorkflowParks(origin.runId, scope, [entry]), { id: origin.runId, ended: () => runChannelEnded(origin.runId, scope) }, d);
+}
+export async function answerOfParkDelivery(delivery, run, d) {
+    const runId = run.id;
+    switch (delivery.kind) {
+        case "live":
+            return { kind: "answered", answer: answerOfLiveResult(delivery.results[0], run, d) };
+        case "suspending":
+            await delivery.ended;
+            return { kind: "resume_lane" };
+        case "not_active":
+            return { kind: "resume_lane" };
+        case "not_armed":
+            throw new Error(`workflow run ${runId} answered not_armed to a decision for a card it holds — a run without a checkpoint seat cannot have parked one; refusing to guess where the decision goes`);
+        default: {
+            const unhandled = delivery;
+            throw new Error(`unhandled workflow park delivery: ${JSON.stringify(unhandled)}`);
+        }
+    }
+}
+function answerOfLiveResult(word, run, d) {
+    const runId = run.id;
+    if (word === undefined)
+        throw new Error(`workflow run ${runId} answered a live delivery without a result for the one decision it was handed`);
+    switch (word) {
+        case "driving": {
+            if (d.restated)
+                throw new Error(`workflow run ${runId} drove a parked call on an acknowledgement — an acknowledgement never authorizes a drive`);
+            const answer = parkedChildResumedReceipt(runId, d.decision, NO_SETTLEMENT_EVIDENCE);
+            holdLiveReceipt(run, d.token, d.fingerprint, answer);
+            return copyOf(answer);
+        }
+        case "already_taken": {
+            const held = LIVE_REDEEM_RECEIPTS.get(runId)?.get(d.token);
+            if (held !== undefined && held.fingerprint === d.fingerprint)
+                return copyOf(held.answer);
+            return {
+                status: 409,
+                body: refusalBody({
+                    errorCode: "decide.claim_lost",
+                    message: "another decision for this approval was already handed to the run that is waiting on it and is being applied — re-check the pending list",
+                    facts: { runId },
+                }),
+            };
+        }
+        case "settled":
+        case "not_parked_here":
+            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: { runId } }) };
+        case "unreadable":
+            return { status: 503, body: refusalBody({ errorCode: "decide.store_unreachable", message: "the state of this approval could not be read just now, so the run waiting on it kept waiting and nothing was decided — retry", facts: { runId } }) };
+        case "kept_parked":
+            if (!d.restated)
+                throw new Error(`workflow run ${runId} kept a parked call that was handed a decision — the engine keeps a park only on an acknowledgement`);
+            return {
+                status: 400,
+                body: refusalBody({
+                    errorCode: "decide.parked_restatement_unsupported",
+                    message: "mcpServers / a2aPeers cannot be applied: the run this approval belongs to is still running, and its waiting step continues with the MCP / A2A tables the run already has — re-issue the decide without them to continue it that way",
+                    facts: { runId },
+                }),
+            };
+        default: {
+            const unhandled = word;
+            throw new Error(`unhandled workflow park delivery result: ${String(unhandled)}`);
+        }
+    }
+}
 function sessionGone(taskId) {
     return {
         status: 409,
@@ -229,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 } }) };
 }
@@ -239,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);
     }
@@ -268,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;
@@ -278,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":
@@ -311,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;
@@ -322,6 +458,10 @@ export async function decideParkedAgent(deps, req, match) {
         await rollback("revive_surface_threw");
         throw e;
     }
+    const definition = reviveDefinitionOf(row, surface.reviveTool);
+    if (definition.kind === "unavailable") {
+        return denyAgentDefinitionUnavailable(match.handle, await rollback("agent_definition_unavailable"));
+    }
     if (req.remember !== undefined && rememberRoot !== undefined) {
         try {
             await req.remember.anchor(rememberRoot);
@@ -334,8 +474,9 @@ export async function decideParkedAgent(deps, req, match) {
     const ctx = {
         toolCallId: `drv-${ticket.claimId}`,
         ...(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 },
@@ -350,7 +491,7 @@ export async function decideParkedAgent(deps, req, match) {
     defaultSubagentTailBus.forgetHandle(match.handle);
     let receipt;
     try {
-        receipt = await surface.reviveTool.execute(mintReviveArgs(row, deps.knownAgentTypes ?? new Set()), ctx);
+        receipt = await surface.reviveTool.execute(mintReviveArgs(row, definition.agentType), ctx);
     }
     catch (e) {
         const disp = await rollback("execute_threw");
@@ -399,6 +540,6 @@ export async function decideParkedAgent(deps, req, match) {
             }),
         };
     }
-    return { status: 200, body: { taskId: match.handle, status: "resuming", decision: req.decision, ...buildSettlementEvidence({ at: "agent_revived", gate: req.selectedGate }) } };
+    return parkedChildResumedReceipt(match.handle, req.decision, buildSettlementEvidence({ at: "agent_revived", gate: req.selectedGate }));
 }
 //# sourceMappingURL=parked-decide.js.map

package/dist/parked-revive-surface.d.ts

@@ -30,14 +30,20 @@
  * 一层行)以 `{ delegationRoot }` 重解 —— 只喂 relay,不挂任何会话级设施、不带 principal,交座判据(上面三条)一个字不动。行上没有根 ⇒ boot 期那只裸 Agent(没有根可交 ⇒ 不接 relay)。
  * 复活的子代再要审批时的停驻挂点(`plugins/session-store.ts`)不读见证:引擎交它那一行自己的属主,挂点只比对(core 7.62.0 [ref];根见证在挂点的读法随 [ref] P-5 退役)。
  */
-import { type BackgroundAgentRecord, type ToolSpec } from "@sema-agent/core";
+import { type BackgroundAgentRecord, type ToolExecuteContext, type ToolSpec } from "@sema-agent/core";
 import type { Scenario } from "./capabilities/scenarios.js";
 import type { SessionFace } from "./session-incarnation.js";
-/** 一次赎回用的面:驱动的 Agent 工具(它的完成 relay 绑着行上的根)+ (交座时)与它同出一张列表的继承座。 */
+/** 一次赎回用的面:驱动的 Agent 工具(它的完成 relay 绑着行上的根)+ (交座时)与它同出一张列表的继承座 + 进程级后台子代观察者。 */
 export interface ParkedReviveSurface {
     readonly reviveTool: ToolSpec;
     /** 缺席 = 不交座(core fail-closed:复活的子代不继承任何场景层工具)。 */
     readonly mountsCallerTool?: (tool: ToolSpec) => boolean;
+    /**
+     * 进程级后台子代观察者 —— 与 `RunnerDeps.onBackgroundChildEvent` **同一只实例**(fleet 的后台子代发布器,行的 spawn / tick / 终态帧与 `bg_notification` 只经它)。
+     * 引擎经 Runner 起跑的工具调用由 Runner 把它填进 `ToolExecuteContext`;赎回腿自己驱动 `execute`、ctx 由赎回腿铸 ⇒ 由本面带进去,复活的那一轮与首轮
+     * 进同一只发布器(发布器按实例持每只子代的溯源,换一只实例 = 终态找不到 spawn 时记下的行)。缺席 = 这条部署没有观察者(Runner 那一侧同样缺席)。
+     */
+    readonly onBackgroundChildEvent?: NonNullable<ToolExecuteContext["onBackgroundChildEvent"]>;
 }
 /**
  * 按行解析赎回面的入参身份:`principal` = 权威 principal(取 checkpoint 的 scope 列,不取行上有损的 `row.scope`);`rootOccupant` = 写口放行的那一位
@@ -50,8 +56,12 @@ export interface ParkedReviveSurfaceIdentity {
 /** 按行解析赎回面。 */
 export type ParkedReviveSurfaceFactory = (row: BackgroundAgentRecord, identity: ParkedReviveSurfaceIdentity) => ParkedReviveSurface;
 /**
- * 赎回面工厂。入参 = **内建** default 场景工厂(stage-07 在 center overlay 盖名之前取的那一只;赎回要的是与 spawn 同源的生产装配)。
+ * 赎回面工厂。入参 = **内建** default 场景工厂(stage-07 在 center overlay 盖名之前取的那一只;赎回要的是与 spawn 同源的生产装配)+ 进程级后台子代观察者
+ * (`RunnerDeps.onBackgroundChildEvent` 那一只,见 {@link ParkedReviveSurface.onBackgroundChildEvent};每一行的面都带它,与交不交座无关)。键必填、值可为 `undefined`:
+ * 调用方必须表态这条部署有没有观察者 —— 修前正是「没人交」静默成了复活轮零帧。
  * 内建 bundle 里没有 Agent 工具 ⇒ `undefined`(park 本就不可达,赎回腿不接线)。
  */
-export declare function createParkedReviveSurface(defaultScenario: Scenario): ParkedReviveSurfaceFactory | undefined;
+export declare function createParkedReviveSurface(defaultScenario: Scenario, observer: {
+    readonly onBackgroundChildEvent: ParkedReviveSurface["onBackgroundChildEvent"] | undefined;
+}): ParkedReviveSurfaceFactory | undefined;
 //# sourceMappingURL=parked-revive-surface.d.ts.map

package/dist/parked-revive-surface.js

@@ -1,20 +1,21 @@
 import { DEFAULT_SUBAGENT_TOOL_NAME } from "@sema-agent/core";
 const agentOf = (tools) => tools.find((t) => t.name === DEFAULT_SUBAGENT_TOOL_NAME);
-export function createParkedReviveSurface(defaultScenario) {
+export function createParkedReviveSurface(defaultScenario, observer) {
     const bootTool = agentOf(defaultScenario({}).tools);
     if (bootTool === undefined)
         return undefined;
+    const observed = observer.onBackgroundChildEvent !== undefined ? { onBackgroundChildEvent: observer.onBackgroundChildEvent } : {};
     return (row, identity) => {
         const root = row.rootSessionId;
         if (root === undefined)
-            return { reviveTool: bootTool };
+            return { reviveTool: bootTool, ...observed };
         const seated = holdsSeat(row.parentSessionId === root, identity);
         const delegationRoot = { sessionId: root, owner: identity.rootOccupant.owner, incarnation: identity.rootOccupant.incarnation };
         const tools = (seated ? defaultScenario({}, identity.principal, { sessionId: root, delegationRoot }) : defaultScenario({}, undefined, { delegationRoot })).tools;
         const reviveTool = agentOf(tools);
         if (reviveTool === undefined)
-            return { reviveTool: bootTool };
-        return seated ? { reviveTool, mountsCallerTool: (t) => tools.includes(t) } : { reviveTool };
+            return { reviveTool: bootTool, ...observed };
+        return seated ? { reviveTool, mountsCallerTool: (t) => tools.includes(t), ...observed } : { reviveTool, ...observed };
     };
 }
 function holdsSeat(oneLevel, identity) {

package/dist/peer-directory.d.ts

@@ -18,24 +18,22 @@
  *
  * ⚠️ **共享的是谓词,不是最终集合**(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 都不入目录(下面那道
  *    单射门),那条路由照列;
  *  · **墓碑**:目录会多出「正在删除中」的 `deleted` 记录,那条路由不列;
- *  · **席位差**:那条路由还有 `runStore.listSessions` 的 legacy 兜底,本席刻意不并(见装配点的注)。
+ *  · **席位差**:无。那条路由与本席读同一只会话店 lister(run 店不列会话,路由没有兜底)。
  * 机器钉因此只钉「同一 principal、无 q、无分页、量在 cap 内」那一格的集合相等(它是那条承重条款的
  * 可执行投影),别把它读成两面恒等。
  *
- * ⚠️ 与设计稿的第二处收紧(亲读实现推翻稿面):稿里把谓词写成 `principal-gate.ts runOwnerReadable`。
- * 亲读两只函数后不成立 —— `runOwnerReadable(p, owner, cfg)` 对 `owner === null` **无条件**放行
+ * ⚠️ 与设计稿的第二处收紧(亲读实现推翻稿面):稿里把谓词写成 `principal-gate.ts qualsOf`。
+ * 亲读两只函数后不成立 —— `qualsOf(p, owner, cfg)` 对 `owner === null` **无条件**放行
  * (`principal-gate.ts:136-137`,函数体第一行),而**列表面**的第三条件由 store 的
- * `owner = ? OR owner IS NULL` 承载,开关是 `legacyUnownedAmnestyOpen(deployment, gateOwner)`
- * (`security.ts:119`,它的头注逐字:
- * 「单独存在的唯一理由是**列表面**……单实体读/写点一律用三条件齐的 `legacyUnownedSessionOk`」)。
- * 拿 `runOwnerReadable` 当列表谓词会让目录比 `GET /v1/sessions` **多列出**别人的无主会话 —— 正好违反
- * 稿子自己那条对拍。所以这里用的是列表面那一只:`legacyUnownedAmnestyOpen` + 同一个 lister。
+ * `owner = ? OR owner IS NULL` 承载,开关是面表列表面 `session.list` 的 `j4` 格(`owner-faces.ts` 的 `listFilterOf` 派生 `includeUnowned`)。
+ * 拿单行读面的放行集当列表谓词会让目录比 `GET /v1/sessions` **多列出**别人的无主会话 —— 正好违反
+ * 稿子自己那条对拍。所以这里用的是列表面那一行:`listFilterOf("session.list", …)` + 同一个 lister(与 `GET /v1/sessions` 同一行面表)。
  *
  * ## scope 轴
  *

package/dist/peer-directory.js

@@ -1,6 +1,7 @@
 import { PEER_SESSION_RECORD_SCHEMA_VERSION, isPeerSessionId, normalizePeerName, peerSessionBoxHandle, SESSION_BOX_PREFIX, } from "@sema-agent/core";
 import { sessionTempoOfRunStatus } from "./plugins/store-contracts.js";
-import { legacyUnownedAmnestyOpen } from "./security.js";
+import { claimCallerOf } from "./security.js";
+import { listFilterOf, recoveredSubject } from "./owner-faces.js";
 export const PEER_DIRECTORY_CAP = 200;
 function displayNameOf(candidate, sessionId) {
     return candidate != null && normalizePeerName(candidate) !== "" ? candidate : `session-${sessionId.slice(0, 8)}`;
@@ -13,7 +14,7 @@ export function createPeerDirectory(ctx) {
     return {
         listPeerSessions: async (access) => {
             const scope = access.scope;
-            const includeUnowned = legacyUnownedAmnestyOpen({ requirePrincipal }, scope);
+            const { includeUnowned } = listFilterOf("session.list", claimCallerOf(recoveredSubject(scope), { requirePrincipal }));
             const answers = await lister({ owner: scope, ...(includeUnowned ? { includeUnowned: true } : {}), limit: PEER_DIRECTORY_CAP + 1 });
             const rows = answers.map((a) => a.row);
             const occupantOf = new Map(answers.map((a) => [a.row.sessionId, a.occupant.incarnation ?? null]));

package/dist/permission-rule-vocab.d.ts

@@ -1,14 +1,59 @@
-import type { RuleBehavior } from "@sema-agent/core";
 /**
- * 一张审批卡的**一键整工具同意**能落在这只工具名上吗 —— 仅当没有任何规则词替这个名字说话:它自己没有规则文法(`ruleToolGrammarOf` 答 undefined),
- * 也不在 shell 面上(`COARSE_SHELL_TOOLS`:`Bash` 与 `Monitor`,它们的命令按 `Bash(…)` 规则判)。引擎为卡铸整工具候选恰在这个条件下(没有规则文法、
- * 也不回答任何规则词的调用);一张 shell 卡上的一键整工具同意 = 对每一个程序的常驻许可,路径 / 名字 / 主机工具的卡各有自己的那一形。
+ * [ref] + [ref](core `e298c9e0`,随 7.2.x 提货生效;[ref])—— 规则车道**闭词表的单一属主**。
+ *
+ * 为什么要一个模块而不是各处各写一份 `z.enum([...])`:同一张词表此前在四处各抄一份字面量
+ * (`approval-card.ts` 两腿的 offer schema、`http/routes/rules.ts` 的直通票口行形、
+ * `plugins/permission-rule-store-sql.ts` 的 `rules_json` 读/写形),core 给 `PersistedRuleMatch` 加两员
+ * (wildcard / subpath)、给 `PersistedRuleTool` 加 Read 时,四份抄件**没有一份**会编译红 —— zod 的 enum
+ * 只是运行期的一个 Set,静默把一次上游语义扩张翻成一整类合法行的拒收([ref] 词表纪律说的正是这形:
+ * 未知词必须是**编译**错,不是运行期一个安静的 false)。
+ *
+ * (7.53.x 及以前:每张表在这里转录一份、各带一条双向全等钉;7.54.0 起值本身由 core 导出,见下一段。)
+ *
+ * ⚠️ 转录**不是**判据:一个词在表里只说「这是 core 定义的一员」,不说「本仓每条腿都接受它」。逐腿的收窄
+ * (例如卡编辑臂对 `subpath` 的拒)写在那条腿自己的穷举 `switch` 里,并各带理由。
  *
- * 读者:卡素材铸点的派生事实一致性(`tool-approval.ts`:整工具候选的工具过不了 ⇒ 丢整只候选,卡上不渲一格按不动的「不再询问」)。
- * 卡编辑面不读它:引擎的编辑门对任何整工具规则一律拒(编辑只改命令规则),编辑面的形闭集(`rules-consent.ts`)跟着恒拒 —— 那张闭集里「shell 卡上一键整只 shell」
- * 的理由就是本谓词的理由,不另写一份判据。方向 fail-closed:答不出 ⇒ 不是。
+ * 🔴 **core 7.54.0([ref] 阶段一 K1 / K1b)起,词表的值本身是 core 的包根导出**(`PERSISTED_RULE_MATCHES` / `RULE_OFFER_BATCH_MEMBER_KINDS` /
+ * `UNCOVERED_SEGMENT_REASONS` / `EDITED_RULE_BREADTH_WARNING_CODES` / `RULE_APPROVAL_RECORD_SCHEMA`,以及 `RULE_APPROVAL_KINDS` / `RULE_APPROVAL_STATES` /
+ * `IMPORTED_SETTINGS_LAYERS` / `RULE_ADD_ORIGINS`)—— 本模块此前的五份转录(各带一条 `Exact<>` 全等钉)随之退役,各消费点直接
+ * import core 的值(一个词一处拼写,在引擎里)。本模块只留**不是词表**的那几件:卡形(工具的卡形与匹配词的逐员表态)、直接写口的逐员表态、撤销后的存活词。
+ *
+ * 持久规则行的工具位**没有**本仓的谓词:「一条持久规则能点名哪只工具」由引擎的校验器从规则文本重投影答(两只店的读写腿、直通票口、直写口都经它);
+ * 整工具形(`match: "tool"`,`command: ""`)对任何引擎认得的工具名成立。此前这里有一只「工具有没有规则文法」的谓词,
+ * 引擎把裸工具名读成整工具规则之后它与校验器分家(无文法工具的整工具行写不进 SQL 店、导不进直通票口)—— 已退役。
  */
-export declare function cardTakesWholeToolConsent(tool: string): boolean;
+import { ruleToolGrammarOf } from "@sema-agent/core";
+import type { RuleBehavior } from "@sema-agent/core";
+/**
+ * 一张审批卡的**卡形** —— 卡上那格「不再询问」说的是哪一种规则。词与定义取自 core 的卡形(`CardRuleForm`,offer 工厂与同意入口共读的那一答):
+ * 命令规则词(`Bash`)的卡铸命令规则;名字文法 / 主机文法工具的卡铸**那一条精确值规则**(`Skill(<名>)` / `WebFetch(domain:<主机>)`);
+ * 没有任何规则词替它说话的工具的卡铸整工具规则(`tool`);其余 —— 路径工具(不铸路径候选)、shell 面上命令规则词的兄弟(`Monitor`:它的命令按 `Bash(…)` 规则判,
+ * 一张 shell 卡上的一键整工具同意 = 对每一个程序的常驻许可)—— 没有卡形。型从 core 的文法词派生(路径文法不是卡形,`tool` 是 core 的第四个词),本仓不抄词表。
+ */
+export type CardRuleForm = Exclude<NonNullable<ReturnType<typeof ruleToolGrammarOf>>, "path"> | "tool";
+/**
+ * 这只工具的卡形(core 判官 `cardRuleFormOf` 不在包根导出面上 —— 依赖方向门禁深路径 —— 本函数按它的同一份定义读包根导出的 `ruleToolGrammarOf`)。
+ * 读者:卡素材铸点的派生事实一致性(`tool-approval.ts`:一只候选的匹配词的卡形 ≠ 这张卡的工具的卡形 ⇒ 丢整只候选,卡上不渲一格按不动的「不再询问」)。
+ * 卡编辑面不读它:引擎的编辑门只改命令规则,编辑面的形闭集(`rules-consent.ts`)对其余各形恒拒。方向 fail-closed:答不出 ⇒ 没有卡形。
+ */
+export declare function cardRuleFormOf(tool: string): CardRuleForm | undefined;
+/**
+ * 每个持久规则匹配词属于哪一种卡形 —— `undefined` = 引擎从不为一张卡铸这一形(名字前缀 / 子域:名字 / 主机工具的卡只铸那一条精确值规则;路径两形:路径工具的卡不铸候选)。
+ * `Record` 穷举:core 给 `PersistedRuleMatch` 加员时这里编译红,新词由人表态([ref] 词表纪律);表态成 `undefined` 是恒丢,不会悄悄放宽。
+ */
+export declare const CARD_RULE_FORM_OF_MATCH: {
+    readonly exact: "command";
+    readonly prefix: "command";
+    readonly wildcard: "command";
+    readonly pattern: "command";
+    readonly tool: "tool";
+    readonly name: "name";
+    readonly host: "domain";
+    readonly name_prefix: undefined;
+    readonly subdomain: undefined;
+    readonly path: undefined;
+    readonly subpath: undefined;
+};
 /**
  * [ref] —— `RuleBehavior` 每一员在**无同意仪式的直接写口**(`POST /v1/rules`)上的逐员表态。
  *

package/dist/permission-rule-vocab.js

@@ -1,7 +1,35 @@
 import { COARSE_SHELL_TOOLS, ruleToolGrammarOf } from "@sema-agent/core";
-export function cardTakesWholeToolConsent(tool) {
-    return ruleToolGrammarOf(tool) === undefined && !COARSE_SHELL_TOOLS.includes(tool);
+export function cardRuleFormOf(tool) {
+    const grammar = ruleToolGrammarOf(tool);
+    switch (grammar) {
+        case "command":
+        case "name":
+        case "domain":
+            return grammar;
+        case "path":
+            return undefined;
+        case undefined:
+            return COARSE_SHELL_TOOLS.includes(tool) ? undefined : "tool";
+        default: {
+            const unknown = grammar;
+            void unknown;
+            return undefined;
+        }
+    }
 }
+export const CARD_RULE_FORM_OF_MATCH = {
+    exact: "command",
+    prefix: "command",
+    wildcard: "command",
+    pattern: "command",
+    tool: "tool",
+    name: "name",
+    host: "domain",
+    name_prefix: undefined,
+    subdomain: undefined,
+    path: undefined,
+    subpath: undefined,
+};
 export const DIRECT_RULE_WRITE_ADMITS = {
     allow: false,
     deny: true,

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

@@ -1,25 +1,3 @@
-/**
- * [ref] I2(form b 位)—— **SQL 收编日志**:phase 真源与被迁的行**同库**。
- *
- * 🔴 为什么 phase 必须住 SQL 而不是一个 sidecar 文件(183 r3 按 codex r2-F2):发起收编的那个 pod 在两条
- * 腿之间被摧毁时,进程本地的标记会与已经半迁移的 SQL 状态**分家** —— 接棒副本读不到「迁到哪了」。
- * 标记与行同事务 ⇒ 崩溃后接棒副本按日志续跑,分家形不存在。
- *
- * ── 幂等身份 = DB 约束,不是「查了再插」(小票 v2/F2)────────────────────────────────────────────
- * `from_principal` 上有 **UNIQUE**(183 D7「拒二次收编」的 DB 强形)。发起走 **insert-or-fetch 原子形**:
- * 一条 `INSERT … ON CONFLICT DO NOTHING` / `INSERT IGNORE`,再按 `from_principal` 读回行。
- * **禁 SELECT-then-INSERT** —— 那两句之间的窗正是两个并发同参 POST 各插一行(或各读到空)的地方,
- * 而 UNIQUE 让「谁插进去了」由数据库仲裁,`affected` 就是判别式。
- * 同 from 异 to ⇒ 读回的行 `to_principal` 不等 ⇒ typed conflict(调用方看到的是 409,不是「成功」)。
- *
- * ── 列的口径 ────────────────────────────────────────────────────────────────────────────────────
- *  · `legs` / `configs` / `report` 是 **TEXT 不是 JSON 列**:`report` 是 `immutableReport` 的落库形,
- *    契约是「逐字节恒同」;JSON 列会按引擎自己的规范形重排键序,而 TEXT 是「存什么读什么」。
- *    (workflow_run.run / workflow_journal.result 同款先例,理由同源:String()→JSON.parse 的字节面。)
- *  · 时间列一律 `_ms BIGINT`(schema-naming 门 ② 咬 `_at BIGINT`)。
- *  · `phase` 是**单调**推进的阶段号,不是乐观锁计数 —— 但它的推进走的就是 CAS(`WHERE phase = :expect`),
- *    所以它同时是那把锁。命名不叫 `rev`,因为它不守卫「行内容有没有变」,而守卫「弧走到哪了」。
- */
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import { type SqlDriver, type SqlExec, type SqlTxConn } from "./sql-driver.js";
@@ -215,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,5 +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 = {
@@ -32,6 +34,7 @@ export const TIDB_ADOPTION_LOG_STATEMENTS = [
    ) COLLATE utf8mb4_bin`,
 ];
 export const ADOPTION_LOG_INDEXES = [
+    { table: `${ADOPTION_LOG_TABLE}`, name: "uq_adoption_log_from", columns: ["from_principal"], unique: true },
     { table: `${ADOPTION_LOG_TABLE}`, name: "idx_adoption_log_state", columns: ["state"] },
 ];
 export async function ensurePgAdoptionLogSchema(q) {
@@ -75,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)}`;
 }
@@ -130,7 +145,7 @@ export class SqlAdoptionLogStore {
                 await conn.rollback();
             }
             catch (rollbackErr) {
-                console.warn("[adoption-log] rollback after a failed rebind transaction also failed:", rollbackErr);
+                writeLogText("stderr", "[adoption-log] rollback after a failed rebind transaction also failed:", rollbackErr);
             }
             throw err;
         }
@@ -147,7 +162,7 @@ export class SqlAdoptionLogStore {
                 await conn.rollback();
             }
             catch (rollbackErr) {
-                console.warn("[adoption-log] rollback after a failed sweep transaction also failed:", rollbackErr);
+                writeLogText("stderr", "[adoption-log] rollback after a failed sweep transaction also failed:", rollbackErr);
             }
             throw err;
         }
@@ -186,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) {
-                    console.warn("[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-retired-delete-by-task-m50.d.ts

@@ -0,0 +1,7 @@
+/** 退役的那只账本动词(只在重放认它;写口不会再写)。 */
+export declare const RETIRED_DELETE_BY_TASK_OP_M50 = "deleteByTask";
+/** M50 的窗在 `today`(UTC 日历日 YYYY-MM-DD)开着没有:开 ⇒ 按旧读法重放;关 ⇒ {@link retiredDeleteByTaskClosedWhyM50} 那一句拒。 */
+export declare function retiredDeleteByTaskReplayOpenM50(today: string): boolean;
+/** 窗关之后的拒因(接在账本拒句里,拒句本身带账本路径与通用出路):点名本条、窗的最后一天与那一版之前的出路 —— 版本与日期都读登记行,不手写第二份。 */
+export declare function retiredDeleteByTaskClosedWhyM50(): string;
+//# sourceMappingURL=approval-ask-retired-delete-by-task-m50.d.ts.map