@sema-agent/server 7.132.0 → 7.133.0

package/dist/parked-decide.js

@@ -1,9 +1,11 @@
 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 } from "./security.js";
+import { backgroundScopesForCheckpointScope, decodeCheckpointScope, ownerOfCheckpointScope } from "./security.js";
 import { ASK_USER_QUESTION_TOOL_NAME } from "./approval-content-kind.js";
 import { sameSessionOccupant } from "./session-incarnation.js";
+import { refusalBody } from "./http/refusal-body.js";
 export async function findParkOrigin(sources, cp) {
     if (sources.agentStore !== undefined) {
         let match;
@@ -51,6 +53,33 @@ export async function findParkOrigin(sources, cp) {
         return undefined;
     }
 }
+export async function heldWorkflowParkDecisions(sources, hostSessionId, carried) {
+    const entries = [...(carried ?? [])];
+    const { workflowParkDecisions: decisions, checkpointStore: cs, workflowAgentSessionIndex: workflowIndex, workflowRunStore } = sources;
+    if (decisions !== undefined && cs !== undefined && workflowIndex !== undefined && workflowRunStore !== undefined) {
+        const own = new Set(entries.map((e) => String(e.token)));
+        const held = await decisions.listByHostSession(hostSessionId).then((rows) => ({ rows }), (err) => ({ err }));
+        if ("err" in held) {
+            recordFailOpen("server.workflow-park-decision.store-unreadable", `hostSessionId=${hostSessionId} err=${held.err instanceof Error ? held.err.message : String(held.err)}`);
+            return entries.length > 0 ? { workflowParkedResume: entries } : {};
+        }
+        for (const row of held.rows) {
+            if (own.has(String(row.token)))
+                continue;
+            const card = await cs.get(row.token).then((cp) => ({ cp }), (err) => ({ err }));
+            if ("err" in card) {
+                recordFailOpen("server.workflow-park-decision.card-unreadable", `runId=${row.runId} err=${card.err instanceof Error ? card.err.message : String(card.err)}`);
+                continue;
+            }
+            if (card.cp === null || card.cp.status !== "pending")
+                continue;
+            const origin = await findParkOrigin({ workflowIndex, workflowRunStore }, { token: row.token, scope: card.cp.scope, sessionId: card.cp.sessionId });
+            if (origin?.kind === "workflow")
+                entries.push({ runId: origin.runId, token: row.token, outcome: row.outcome });
+        }
+    }
+    return entries.length > 0 ? { workflowParkedResume: entries } : {};
+}
 function quiet(warn, event, fields) {
     try {
         warn?.(event, fields);
@@ -106,21 +135,25 @@ export function denyWorkflowParksUnreadable(origin) {
         case "older_engine":
             return {
                 status: 409,
-                body: {
-                    error: "this decision cannot be matched to the pending step it belongs to: the run's record was written by an earlier engine version, which did not record which run is waiting on each pending step — and that record is the only proof that the approval you are deciding belongs to this run. The decision is therefore NOT delivered, rather than answered with a receipt nothing can redeem: the approval card stays pending and nothing is forged. Resume the run itself instead — `Workflow({resumeFromRunId})` with the runId below — and once the resumed run is waiting on this step again it records itself as the one waiting, after which deciding here works normally. Only if the engine also refuses that resume is the run truly unrecoverable",
+                body: refusalBody({
                     errorCode: "decide.workflow_parks_unreadable",
-                    runId: origin.runId,
-                },
+                    message: "this decision cannot be matched to the pending step it belongs to: the run's record was written by an earlier engine version, which did not record which run is waiting on each pending step — and that record is the only proof that the approval you are deciding belongs to this run. The decision is therefore NOT delivered, rather than answered with a receipt nothing can redeem: the approval card stays pending and nothing is forged. Resume the run itself instead — `Workflow({resumeFromRunId})` with the runId below — and once the resumed run is waiting on this step again it records itself as the one waiting, after which deciding here works normally. Only if the engine also refuses that resume is the run truly unrecoverable",
+                    facts: {
+                        runId: origin.runId,
+                    },
+                }),
             };
         case "unreadable":
             return {
                 status: 409,
-                body: {
-                    error: "this decision cannot be matched to the pending step it belongs to: this run's record cannot be read (the list of pending steps the run owns is damaged: one of its entries is malformed, or it is not a list at all) — and that list is the only proof that the approval you are deciding belongs to this run. The decision is therefore NOT delivered, rather than answered with a receipt nothing can redeem: the approval card stays pending and nothing is forged. Resuming does not clear this: the damaged record keeps naming this step whatever runs after it, so the decision stays undeliverable until whoever operates this deployment repairs that record (the runId below); after that, deciding here works normally. When the response also carries readableHolderRunId, that run's record is readable and is the latest one waiting on this step — it is where the work can be carried on, but the damaged record above still keeps this decision from being delivered until that record is fixed",
+                body: refusalBody({
                     errorCode: "decide.workflow_parks_unreadable",
-                    runId: origin.runId,
-                    ...(origin.readableHolderRunId !== undefined ? { readableHolderRunId: origin.readableHolderRunId } : {}),
-                },
+                    message: "this decision cannot be matched to the pending step it belongs to: this run's record cannot be read (the list of pending steps the run owns is damaged: one of its entries is malformed, or it is not a list at all) — and that list is the only proof that the approval you are deciding belongs to this run. The decision is therefore NOT delivered, rather than answered with a receipt nothing can redeem: the approval card stays pending and nothing is forged. Resuming does not clear this: the damaged record keeps naming this step whatever runs after it, so the decision stays undeliverable until whoever operates this deployment repairs that record (the runId below); after that, deciding here works normally. When the response also carries readableHolderRunId, that run's record is readable and is the latest one waiting on this step — it is where the work can be carried on, but the damaged record above still keeps this decision from being delivered until that record is fixed",
+                    facts: {
+                        runId: origin.runId,
+                        ...(origin.readableHolderRunId !== undefined ? { readableHolderRunId: origin.readableHolderRunId } : {}),
+                    },
+                }),
             };
         default: {
             const unhandled = origin.cause;
@@ -131,11 +164,13 @@ export function denyWorkflowParksUnreadable(origin) {
 export function denyWorkflowParkForked(origin) {
     return {
         status: 409,
-        body: {
-            error: "this decision cannot be delivered: the same run was resumed more than once and every resumed copy listed in runIds is waiting on this same step, so there is no single run to hand the decision to. Nothing was delivered and the approval card stays pending. Resume one of the runs listed in runIds; once that run is waiting on this step again, deciding here works normally",
+        body: refusalBody({
             errorCode: "decide.workflow_park_forked",
-            runIds: [...origin.runIds],
-        },
+            message: "this decision cannot be delivered: the same run was resumed more than once and every resumed copy listed in runIds is waiting on this same step, so there is no single run to hand the decision to. Nothing was delivered and the approval card stays pending. Resume one of the runs listed in runIds; once that run is waiting on this step again, deciding here works normally",
+            facts: {
+                runIds: [...origin.runIds],
+            },
+        }),
     };
 }
 export function planWorkflowParkedDecide(origin, req) {
@@ -144,11 +179,13 @@ export function planWorkflowParkedDecide(origin, req) {
             ok: false,
             deny: {
                 status: 400,
-                body: {
-                    error: "remember:\"session\" is not supported for this approval: accepting it here only means the decision was handed on for delivery, not that the engine has applied it — an exemption granted now could outlive a decision the engine later rejects. Re-issue the decide without `remember`; the decision itself is accepted normally that way.",
+                body: refusalBody({
                     errorCode: "decide.workflow_remember_unsupported",
-                    runId: origin.runId,
-                },
+                    message: "remember:\"session\" is not supported for this approval: accepting it here only means the decision was handed on for delivery, not that the engine has applied it — an exemption granted now could outlive a decision the engine later rejects. Re-issue the decide without `remember`; the decision itself is accepted normally that way.",
+                    facts: {
+                        runId: origin.runId,
+                    },
+                }),
             },
         };
     }
@@ -158,11 +195,13 @@ export function planWorkflowParkedDecide(origin, req) {
             ok: false,
             deny: {
                 status: 409,
-                body: {
-                    error: "this run was started on its own rather than from a session, so this deployment has nowhere to deliver the decision. Nothing was decided and the approval is still pending — resume the run yourself with the runId below and decide it there",
+                body: refusalBody({
                     errorCode: "decide.workflow_host_unknown",
-                    runId: origin.runId,
-                },
+                    message: "this run was started on its own rather than from a session, so this deployment has nowhere to deliver the decision. Nothing was decided and the approval is still pending — resume the run yourself with the runId below and decide it there",
+                    facts: {
+                        runId: origin.runId,
+                    },
+                }),
             },
         };
     }
@@ -181,29 +220,31 @@ export function planWorkflowParkedDecide(origin, req) {
 function sessionGone(taskId) {
     return {
         status: 409,
-        body: {
-            error: "the session this agent belongs to was deleted (or deleted and started again under the same id) while its approval waited, so the approval no longer applies — nothing was resumed",
+        body: refusalBody({
             errorCode: "decide.not_parked",
-            taskId,
-        },
+            message: "the session this agent belongs to was deleted (or deleted and started again under the same id) while its approval waited, so the approval no longer applies — nothing was resumed",
+            facts: {
+                taskId,
+            },
+        }),
     };
 }
 export async function decideParkedAgent(deps, req, match) {
     const row = match.row;
     const rememberRoot = req.grantRemember !== undefined ? grantRootOf(row) : undefined;
     if (req.grantRemember !== undefined && rememberRoot === undefined) {
-        return { status: 400, body: { error: "remember cannot be applied: this parked agent row carries no root/parent session anchor for the exemption", errorCode: "decide.parked_remember_unsupported", taskId: match.handle } };
+        return { status: 400, body: refusalBody({ errorCode: "decide.parked_remember_unsupported", message: "remember cannot be applied: this parked agent row carries no root/parent session anchor for the exemption", facts: { taskId: match.handle } }) };
     }
     const pendingTool = req.pendingAction?.toolName;
     if (pendingTool === ASK_USER_QUESTION_TOOL_NAME && req.decision === "approve" && req.answer === undefined) {
-        return { status: 400, body: { error: "pending action is AskUserQuestion — approve requires body.answer (the operator's answers[]); deny needs none", errorCode: "decide.parked_answer_required", taskId: match.handle } };
+        return { status: 400, body: refusalBody({ errorCode: "decide.parked_answer_required", message: "pending action is AskUserQuestion — approve requires body.answer (the operator's answers[]); deny needs none", facts: { taskId: match.handle } }) };
     }
     if (row.name === undefined) {
-        return { status: 409, body: { error: "parked row carries no agent name — the revive path requires a named agent (row damaged?)", errorCode: "decide.row_unrevivable", taskId: match.handle } };
+        return { status: 409, body: refusalBody({ errorCode: "decide.row_unrevivable", message: "parked row carries no agent name — the revive path requires a named agent (row damaged?)", facts: { taskId: match.handle } }) };
     }
     const root = row.rootSessionId;
     if (root === undefined) {
-        return { status: 409, body: { error: "this agent's row carries no root session anchor — the revive path cannot tell which session this approval belongs to (row damaged?)", errorCode: "decide.row_unrevivable", taskId: match.handle } };
+        return { status: 409, body: refusalBody({ errorCode: "decide.row_unrevivable", message: "this agent's row carries no root session anchor — the revive path cannot tell which session this approval belongs to (row damaged?)", facts: { taskId: match.handle } }) };
     }
     const faceBefore = await deps.sessionFaceOf(root);
     if (faceBefore === undefined)
@@ -214,14 +255,14 @@ export async function decideParkedAgent(deps, req, match) {
     if (!claim.ok) {
         switch (claim.reason) {
             case "store_unreachable":
-                return { status: 503, body: { error: "the durable agent store is unreachable — retry", errorCode: "decide.store_unreachable", taskId: match.handle } };
+                return { status: 503, body: refusalBody({ errorCode: "decide.store_unreachable", message: "the durable agent store is unreachable — retry", facts: { taskId: match.handle } }) };
             case "claim_lost":
-                return { status: 409, body: { error: "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)", errorCode: "decide.claim_lost", taskId: match.handle } };
+                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":
             case "checkpoint_not_pending":
-                return { status: 409, body: { error: "the approval gate moved under this decide (re-parked or already settled) — re-check the pending list", errorCode: "decide.gate_moved", taskId: match.handle } };
+                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: match.handle } }) };
             default:
-                return { status: 409, body: { error: "the parked agent moved under this decide (stopped or already decided)", errorCode: "decide.not_parked", taskId: match.handle } };
+                return { status: 409, body: refusalBody({ errorCode: "decide.not_parked", message: "the parked agent moved under this decide (stopped or already decided)", facts: { taskId: match.handle } }) };
         }
     }
     const ticket = claim.ticket;
@@ -281,7 +322,7 @@ export async function decideParkedAgent(deps, req, match) {
         toolCallId: `drv-${ticket.claimId}`,
         ...(surface.mountsCallerTool !== undefined ? { mountsCallerTool: surface.mountsCallerTool } : {}),
         ...(deps.approverSeatFor !== undefined && seatRoot !== undefined
-            ? { onAsk: deps.approverSeatFor({ owner: decodeCheckpointScope(req.scope) ?? null, taskId: match.handle, sessionId: seatRoot }) }
+            ? { onAsk: deps.approverSeatFor({ owner: ownerOfCheckpointScope(req.scope), taskId: match.handle, sessionId: seatRoot }) }
             : {}),
         reviveClaim: {
             row: { ...ticket.row, parkClaimId: ticket.claimId },
@@ -302,12 +343,14 @@ export async function decideParkedAgent(deps, req, match) {
         const disp = await rollback("execute_threw");
         return {
             status: 500,
-            body: {
-                error: `revive failed before the resume was driven: ${e instanceof Error ? e.message : String(e)}`,
+            body: refusalBody({
                 errorCode: "decide.revive_failed",
-                taskId: match.handle,
-                rollback: disp,
-            },
+                message: `revive failed before the resume was driven: ${e instanceof Error ? e.message : String(e)}`,
+                facts: {
+                    taskId: match.handle,
+                    rollback: disp,
+                },
+            }),
         };
     }
     const isErr = typeof receipt === "object" && receipt !== null && receipt.isError === true;
@@ -319,23 +362,27 @@ export async function decideParkedAgent(deps, req, match) {
             const cause = readClosedWordSeat(receiptDetails, "cause");
             return {
                 status: 422,
-                body: {
-                    error: typeof content === "string" ? content : "the parked resume failed during startup",
+                body: refusalBody({
                     errorCode: "parked_resume.startup_failed",
-                    taskId: match.handle,
-                    rollback: disp,
-                    ...(cause !== undefined ? { cause } : {}),
-                },
+                    message: typeof content === "string" ? content : "the parked resume failed during startup",
+                    facts: {
+                        taskId: match.handle,
+                        rollback: disp,
+                        ...(cause !== undefined ? { cause } : {}),
+                    },
+                }),
             };
         }
         return {
             status: 409,
-            body: {
-                error: typeof content === "string" ? content : "revive was rejected by the delegation tool",
+            body: refusalBody({
                 errorCode: "decide.revive_rejected",
-                taskId: match.handle,
-                rollback: disp,
-            },
+                message: typeof content === "string" ? content : "revive was rejected by the delegation tool",
+                facts: {
+                    taskId: match.handle,
+                    rollback: disp,
+                },
+            }),
         };
     }
     return { status: 200, body: { taskId: match.handle, status: "resuming", decision: req.decision } };

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

@@ -19,15 +19,22 @@
  *    这里的第 ② 条是同一条事实在交座这一处的判据(规则只写在这里,腿只负责读两次)。根删除时把子孙的 parked 卡一并作废 = S-790 件 B
  *    (`boot/session-faces.ts` 的删除协调器)。
  *  · 只对**一层**行填座(`rootSessionId` 在场且 = `parentSessionId`:派它的 run 就是根会话的 run,列表正是那个 run 的挂载)。更深的行
- *    (孙代:派它的是一个子代,它的挂载是继承裁剪后的子集,行上读不出来)不填 —— 用 boot 期那只裸 Agent、无座 = core 的 fail-closed 臂;
+ *    (孙代:派它的是一个子代,它的挂载是继承裁剪后的子集,行上读不出来)不填 —— 无座 = core 的 fail-closed 臂;
  *    行上带继承组成是 core #1112(7.32.x)的半场,到货再改读行。
  * 近似如实记:重解的列表是**部署缺省**那一份,读不回那一 run 的逐请求差异(`settings.webSearch` 后端、center overlay 场景)——
  * 座只判 bundle 实例的成员性,继承面是 `[...web, ...scaffolds]`,那两项差异不改变谁在面内。
+ *
+ * **属主来源(S-1770 / S-1808)与交座是两个独立判据**:赎回工具的停驻挂点(复活的子代再要审批时停驻,`plugins/session-store.ts`)按委派继承律定宿主行属主,
+ * 律要的是**委派树根的见证**:根 id(行上本来就带 `rootSessionId`)+ 判断那一刻读到的根行住客(赎回腿 claim 前后两读的那一位 —— 两读不是同一位时赎回腿整条拒,
+ * 走不到这里;读数缺席 ⇒ 见证不带住客,挂点那一刻根行在 ⇒ 停驻否决)。所以**每一行**都交出它({@link ScenarioContext} 的 `delegationRoot`):交座的一层行以
+ * `{ sessionId: root, delegationRoot }` 重解,不交座的行(更深的行、根住客已变的一层行、读数缺席)以 `{ delegationRoot }` 重解 —— 只喂停驻挂点,不挂任何会话级设施、
+ * 不带 principal,交座判据(上面三条)一个字不动。行上没有根 ⇒ boot 期那只裸 Agent(没有根可交 ⇒ 律给哨兵)。挂点那一刻根行已不在 ⇒ 律给哨兵;在而不是见证的那一位
+ * (批准之后删了、同 id 被重新登记)⇒ 停驻否决 —— 两件都在挂点那一侧判,与这里无关。
  */
 import { type BackgroundAgentRecord, type ToolSpec } from "@sema-agent/core";
 import type { Scenario } from "./capabilities/scenarios.js";
 import { type SessionFace } from "./session-incarnation.js";
-/** 一次赎回用的面:驱动的 Agent 工具 + (一层行时)与它同出一张列表的继承座。 */
+/** 一次赎回用的面:驱动的 Agent 工具(它的停驻挂点绑着行上的根)+ (交座时)与它同出一张列表的继承座。 */
 export interface ParkedReviveSurface {
     readonly reviveTool: ToolSpec;
     /** 缺席 = 不交座(core fail-closed:复活的子代不继承任何场景层工具)。 */

package/dist/parked-revive-surface.js

@@ -7,18 +7,21 @@ export function createParkedReviveSurface(defaultScenario) {
         return undefined;
     return (row, identity) => {
         const root = row.rootSessionId;
-        if (root === undefined || row.parentSessionId !== root)
+        if (root === undefined)
             return { reviveTool: bootTool };
-        const face = identity.root;
-        if (face === undefined || !sameSessionOccupant(face.before, face.after))
-            return { reviveTool: bootTool };
-        if ((face.before.owner ?? undefined) !== identity.principal || (face.after.owner ?? undefined) !== identity.principal)
-            return { reviveTool: bootTool };
-        const tools = defaultScenario({}, identity.principal, { sessionId: root }).tools;
+        const seated = holdsSeat(row.parentSessionId === root, identity);
+        const delegationRoot = { sessionId: root, incarnation: identity.root?.after.incarnation ?? null };
+        const tools = (seated ? defaultScenario({}, identity.principal, { sessionId: root, delegationRoot }) : defaultScenario({}, undefined, { delegationRoot })).tools;
         const reviveTool = agentOf(tools);
         if (reviveTool === undefined)
             return { reviveTool: bootTool };
-        return { reviveTool, mountsCallerTool: (t) => tools.includes(t) };
+        return seated ? { reviveTool, mountsCallerTool: (t) => tools.includes(t) } : { reviveTool };
     };
 }
+function holdsSeat(oneLevel, identity) {
+    const face = identity.root;
+    if (!oneLevel || face === undefined || !sameSessionOccupant(face.before, face.after))
+        return false;
+    return (face.before.owner ?? undefined) === identity.principal && (face.after.owner ?? undefined) === identity.principal;
+}
 //# sourceMappingURL=parked-revive-surface.js.map

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

@@ -6,7 +6,7 @@
  * `TaskSpec.allowedTools`(`task-settings.ts` 的 `applyTaskSettings`),运维的 `APPROVAL_GRANT` 投 `RunnerDeps.allowedTools`
  * (`boot/runner-deps.ts` 的部署姿态座席族)。本口的 `behavior` 型直接是 core 的 `PermissionRule["behavior"]`(不手抄:core 收窄,这里跟着收窄)。
  *
- * 为什么住在一只叶模块里(不留在 `task-settings.ts`):本模块只 import core 与 `text-bidi.ts`(纯叶),读者引它不成环。
+ * 为什么住在一只叶模块里(不留在 `task-settings.ts`):本模块只 import core 与契约包 settings-schema(纯叶),读者引它不成环。
  */
 import { type PathRuleBases, type PermissionRule, type ToolPolicy } from "@sema-agent/core";
 /** 一张表里规则条数的上限 —— 请求腿 wire 门(`task-settings.ts` 的 deny / ask 两桶判形)读的也是这一个名字:core 的缺省帽是 256,

package/dist/permission-rule-list.js

@@ -1,5 +1,5 @@
 import { createPermissionRulePolicy } from "@sema-agent/core";
-import { CONTROL_AND_BIDI_STRIP_RE } from "./text-bidi.js";
+import { stripControlAndBidi } from "@sema-agent/settings-schema";
 export const MAX_PERMISSION_RULES_PER_LIST = 1_000;
 export function createRuleListPolicy(names, behavior, source, pathBases) {
     try {
@@ -10,7 +10,7 @@ export function createRuleListPolicy(names, behavior, source, pathBases) {
         });
     }
     catch (e) {
-        const coreMsg = (e instanceof Error ? e.message : String(e)).replace(CONTROL_AND_BIDI_STRIP_RE, "");
+        const coreMsg = stripControlAndBidi(e instanceof Error ? e.message : String(e));
         throw new Error(`${source.replace("settings.", "")} has rule(s) core cannot compile — ${coreMsg}`, { cause: e });
     }
 }

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

@@ -22,7 +22,7 @@ export declare const ASK_JOURNAL_COMPACT_GROWTH = 2;
  * 账本的**动词闭集**([ref] 形)。运行期的词表判定与编译期的穷尽 `switch` 读同一份:
  * 往这里加一个词,{@link FileApprovalAskStore.replayOp} 的 switch 立刻编译红(漏一口不可能发布)。
  */
-declare const JOURNAL_OPS: readonly ["ensureAsk", "transitionAsk", "decideAsk", "claimTerminal", "claimTerminalRefuse", "expireAsk", "bindBatch", "abortBatch", "deferReconcile", "resolveProvisional", "deleteByTask"];
+declare const JOURNAL_OPS: readonly ["ensureAsk", "transitionAsk", "decideAsk", "claimTerminal", "claimTerminalRefuse", "expireAsk", "bindBatch", "abortBatch", "deferReconcile", "resolveProvisional", "deleteByTask", "reapSettledAsks", "reapEmptyBatches"];
 type JournalOpWord = (typeof JOURNAL_OPS)[number];
 /** 运行期词表(上面的数组)与类型面动词维({@link JournalCall})的**双向**对表 —— 任一边加词而另一边
  *  没跟上,这个别名解析成 `never`,{@link JOURNAL_OP_TABLE_GATE} 的赋值当场编译红。 */
@@ -96,6 +96,17 @@ type JournalCall = {
 } | {
     op: "deleteByTask";
     taskId: string;
+}
+/** 留存律的问账两半(挂靠集落成数组;Set 不是 JSON)。更老的读者不认这两个动词 ⇒ 拒启并点名出路(与 `claimTerminalRefuse` 同一条降级纪律)。 */
+ | {
+    op: "reapSettledAsks";
+    cutoffMs: number;
+    limit: number;
+    keepAnchors: string[];
+} | {
+    op: "reapEmptyBatches";
+    cutoffMs: number;
+    limit: number;
 };
 export declare class FileApprovalAskStore implements ApprovalAskStore {
     /** 语义内核(转移判定的唯一真源)。本类对它只做两件事:重放、代理。 */
@@ -171,6 +182,10 @@ export declare class FileApprovalAskStore implements ApprovalAskStore {
     deferReconcile(askId: string, expectedState: AskState, expectedRev: number, nowMs: number): Promise<boolean>;
     resolveProvisional(askId: string, from: AskState, to: AskState, patch: AskTransitionPatch): Promise<boolean>;
     deleteByTask(taskId: string): Promise<void>;
+    /** 留存律的问行半场(谓词在内核,见接口注)。空的一次(内核的纯读选择为空)不落账本、不碰内存;否则照常「先落账、再翻内存」。 */
+    reapSettledAsks(cutoffMs: number, limit: number, keepAnchors: ReadonlySet<string>): Promise<number>;
+    /** 留存律的批行半场(同上)。 */
+    reapEmptyBatches(cutoffMs: number, limit: number): Promise<number>;
     listByState(state: AskState, limit: number): Promise<AskRow[]>;
     listPendingByTask(taskId: string, signal?: AbortSignal): Promise<AskRow[]>;
     listPendingBySession(sessionId: string, owner: string | null, signal?: AbortSignal): Promise<AskRow[]>;

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

@@ -21,6 +21,8 @@ const JOURNAL_OPS = [
     "deferReconcile",
     "resolveProvisional",
     "deleteByTask",
+    "reapSettledAsks",
+    "reapEmptyBatches",
 ];
 const JOURNAL_OP_WORDS = new Set(JOURNAL_OPS);
 export const JOURNAL_OP_TABLE_GATE = true;
@@ -159,6 +161,11 @@ export class FileApprovalAskStore {
             refuse("call record without a clock reading");
         if (probe.op === "claimTerminal" && !JOURNAL_V1_CLAIM_INTENT_WORDS.has(String(raw.intent)))
             refuse("claimTerminal intent outside this build's journal set (a newer server wrote it)");
+        if (probe.op === "reapSettledAsks") {
+            const anchors = raw.keepAnchors;
+            if (!Array.isArray(anchors) || !anchors.every((a) => typeof a === "string"))
+                refuse("reapSettledAsks record without a string-array keepAnchors");
+        }
         const rec = raw;
         this.pinnedNow = rec.t;
         try {
@@ -197,6 +204,10 @@ export class FileApprovalAskStore {
                 return this.core.resolveProvisional(rec.askId, rec.from, rec.to, rec.patch);
             case "deleteByTask":
                 return this.core.deleteByTask(rec.taskId);
+            case "reapSettledAsks":
+                return this.core.reapSettledAsks(rec.cutoffMs, rec.limit, new Set(rec.keepAnchors));
+            case "reapEmptyBatches":
+                return this.core.reapEmptyBatches(rec.cutoffMs, rec.limit);
             default: {
                 const unreachable = rec;
                 throw new Error(`FileApprovalAskStore: unreachable journal op ${JSON.stringify(unreachable)}`);
@@ -244,6 +255,16 @@ export class FileApprovalAskStore {
     async deleteByTask(taskId) {
         return this.write({ op: "deleteByTask", taskId }, (c) => this.core.deleteByTask(c.taskId));
     }
+    async reapSettledAsks(cutoffMs, limit, keepAnchors) {
+        if (this.core.planReapSettledAsks(cutoffMs, limit, keepAnchors).length === 0)
+            return 0;
+        return this.write({ op: "reapSettledAsks", cutoffMs, limit, keepAnchors: [...keepAnchors].sort() }, (c) => this.core.reapSettledAsks(c.cutoffMs, c.limit, new Set(c.keepAnchors)));
+    }
+    async reapEmptyBatches(cutoffMs, limit) {
+        if (this.core.planReapEmptyBatches(cutoffMs, limit).length === 0)
+            return 0;
+        return this.write({ op: "reapEmptyBatches", cutoffMs, limit }, (c) => this.core.reapEmptyBatches(c.cutoffMs, c.limit));
+    }
     listByState(state, limit) {
         return this.core.listByState(state, limit);
     }

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

@@ -6,7 +6,7 @@
  *
  * 🔴 **S-384:本类同时是 `FileApprovalAskStore` 的内核**(local 车道的持久形不再是「第二份手抄」——
  * 它把本类**原样**包起来,每次写前先把**调用本身**落 JSONL、重放时用同一只内核重放同一串调用)。
- * 为此本类多了三件、且**只**多这三件(全是数据面,零转移判定):
+ * 为此本类多了这几件、且**只**多这几件(全是数据面,零转移判定):
  *  · {@link InMemoryApprovalAskStore.constructor} 的可注入钟 `now` —— 五个动词(decideAsk / claimTerminal /
  *    expireAsk / bindBatch / abortBatch)原先直读 `Date.now()`,那是重放路上唯一的不确定源:同一串调用
  *    重放出来的 `updatedAtMs`/`decidedAtMs` 必须与当初**逐字节**相同,否则「重放等价」是假的。
@@ -16,6 +16,8 @@
  *  · {@link InMemoryApprovalAskStore.exportRows} / {@link InMemoryApprovalAskStore.importRows} —— 压实用的
  *    整本快照口(纯搬行,不经任何谓词)。压实要把「一串调用」折成「一串终局行」,没有这一对就只能在
  *    File 形里另写一套「哪些行还算数」的判据 —— 那才是第二份手抄。
+ *  · {@link InMemoryApprovalAskStore.planReapSettledAsks} / {@link InMemoryApprovalAskStore.planReapEmptyBatches} —— 两只留存动词的
+ *    **纯读选择**(删哪些行)。File 形据它判「这一次有没有东西可删」,空的一次不落账本;删除本身仍是接口动词,与选择共用这一只。
  *
  * 行为口径与 `SqlApprovalAskStore` 逐条对齐:
  *  - ensureAsk 幂等 upsert(ask_id 已在 ⇒ 返回既有行,不改写;batch 行若不存在则以 OPEN 补齐）。
@@ -106,6 +108,21 @@ export declare class InMemoryApprovalAskStore implements ApprovalAskStore {
     resolveProvisional(askId: string, from: AskState, to: AskState, patch: AskTransitionPatch): Promise<boolean>;
     deleteByTask(taskId: string): Promise<void>;
     getBatch(batchId: string): Promise<BatchRow | null>;
+    /**
+     * 留存律的问行半场(谓词见接口注,与 SQL twin 的 `DELETE … LIMIT` 同答)。方法体全同步(零 `await`)⇒ File 形把它当一次落账的调用
+     * 重放时逐字复现(cutoff / limit / 挂靠集都是调用实参,不读钟)。
+     */
+    reapSettledAsks(cutoffMs: number, limit: number, keepAnchors: ReadonlySet<string>): Promise<number>;
+    /** 留存律的批行半场(谓词见接口注,与 SQL twin 同答;同上,全同步)。 */
+    reapEmptyBatches(cutoffMs: number, limit: number): Promise<number>;
+    /**
+     * 两只留存动词会删哪些行(纯读,零写)。File 形据此判「这一次有没有东西可删」—— 空的一次不落账本(否则每次清扫都往账本里写一条什么都
+     * 没做的调用)。与删除共用这一只选择,没有第二份谓词。选哪几只:按 `(updatedAtMs, id)` 升序取前 `limit` 只 —— 确定性只为重放,律本身
+     * 不依赖次序(SQL twin 不排序)。
+     */
+    planReapSettledAsks(cutoffMs: number, limit: number, keepAnchors: ReadonlySet<string>): readonly string[];
+    /** {@link reapEmptyBatches} 的选择(同上)。 */
+    planReapEmptyBatches(cutoffMs: number, limit: number): readonly string[];
 }
 export type { AskDecision, AskState, BatchState };
 //# sourceMappingURL=approval-ask-store-memory.d.ts.map

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

@@ -1,6 +1,6 @@
-import { canAskTransition } from "../approval-ask-machine.js";
+import { ASK_TERMINAL, 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";
+import { askRowOnCall, assertDecideSettledBy, assertIdempotencyKeyShape, assertIntegralEpochMs, assertReapBounds, ApprovalAskReadAbortedError, claimTargetState, POLICY_REFUSAL_DECISION, projectAskTerminalClaimTruth } from "./approval-ask-store-sql.js";
 function applyPatch(row, patch) {
     if (patch.decision !== undefined)
         row.decision = patch.decision;
@@ -359,5 +359,37 @@ export class InMemoryApprovalAskStore {
         const b = this.batches.get(batchId);
         return b ? { ...b } : null;
     }
+    async reapSettledAsks(cutoffMs, limit, keepAnchors) {
+        const ids = this.planReapSettledAsks(cutoffMs, limit, keepAnchors);
+        for (const id of ids)
+            this.asks.delete(id);
+        return ids.length;
+    }
+    async reapEmptyBatches(cutoffMs, limit) {
+        const ids = this.planReapEmptyBatches(cutoffMs, limit);
+        for (const id of ids)
+            this.batches.delete(id);
+        return ids.length;
+    }
+    planReapSettledAsks(cutoffMs, limit, keepAnchors) {
+        assertReapBounds(cutoffMs, limit);
+        const anchored = (r) => keepAnchors.has(r.taskId) || keepAnchors.has(r.sessionId) || keepAnchors.has(r.sourceTaskId);
+        return [...this.asks.values()]
+            .filter((r) => ASK_TERMINAL.has(r.state) && !r.provisional && r.updatedAtMs < cutoffMs && !anchored(r))
+            .sort((a, b) => a.updatedAtMs - b.updatedAtMs || (a.askId < b.askId ? -1 : a.askId > b.askId ? 1 : 0))
+            .slice(0, limit)
+            .map((r) => r.askId);
+    }
+    planReapEmptyBatches(cutoffMs, limit) {
+        assertReapBounds(cutoffMs, limit);
+        const occupied = new Set();
+        for (const r of this.asks.values())
+            occupied.add(r.batchId);
+        return [...this.batches.values()]
+            .filter((b) => b.updatedAtMs < cutoffMs && !occupied.has(b.batchId))
+            .sort((a, b) => a.updatedAtMs - b.updatedAtMs || (a.batchId < b.batchId ? -1 : a.batchId > b.batchId ? 1 : 0))
+            .slice(0, limit)
+            .map((b) => b.batchId);
+    }
 }
 //# sourceMappingURL=approval-ask-store-memory.js.map

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

@@ -268,6 +268,8 @@ export type DecideResult = {
  *  隐式截断 —— 两方言不同答;这里改成两方言同一句 TypeError(响亮,点名字段与值),铸点侧(`tool-approval.ts`
  *  的 deadline 铸点)负责给整数,本守卫只拦漏网。 */
 export declare function assertIntegralEpochMs(field: string, value: number): void;
+/** 留存动词两只的入参门(三 twin 同判):cutoff 是整数毫秒、limit 是正整数(limit 在 SQL twin 里内联进语句)。 */
+export declare function assertReapBounds(cutoffMs: number, limit: number): void;
 export declare function assertIdempotencyKeyShape(key: string): void;
 /** `settled_by` 列宽 = 这一格的唯一尺(两方言 DDL 与下面的形门读同一个常量,不手抄第二份)。 */
 export declare const MAX_SETTLED_BY_CHARS = 16;
@@ -510,6 +512,21 @@ export interface ApprovalAskStore {
     getByIdempotencyKey(taskId: string, key: string): Promise<AskRow | null>;
     resolveProvisional(askId: string, from: AskState, to: AskState, patch: AskTransitionPatch): Promise<boolean>;
     deleteByTask(taskId: string): Promise<void>;
+    /**
+     * **审批账本留存律的问账半场之一:问行**(律、节律与「还能动的 run」一处成文在 `approval-ask-retention.ts`;维护 tick 是唯一调用方)。
+     * 删至多 `limit` 只**结了**的问行 —— `state ∈ ASK_TERMINAL` ∧ `provisional = false`(provisional 行还能被 {@link resolveProvisional} 改判,没结)
+     * ∧ `updatedAtMs < cutoffMs` ∧ 行挂靠的三格(`taskId` / `sessionId` / `sourceTaskId`)都不在 `keepAnchors`(还能动的东西的挂靠集:
+     * 它还会回读这些行 —— 会话授权的争议判据 {@link listByCall} 把「这次调用在腿内没有行」读成可以代答)。非终态行多老都不删(它们归对账器
+     * 与起服收敛)。只删不改。
+     * 一条语句:要么删了并交回删掉的行数,要么一行没删就抛。三形同答(InMemory = 内核;File 形把这次调用照常落成一条账本动词,
+     * 空的一次不落;SQL 两方言 = 一条 `DELETE … LIMIT`,行谓词,多副本同扫只是一方删到零行)。
+     */
+    reapSettledAsks(cutoffMs: number, limit: number, keepAnchors: ReadonlySet<string>): Promise<number>;
+    /**
+     * **问账半场之二:批行**。删至多 `limit` 只批里已经**没有任何问行**、且自己的 `updatedAtMs < cutoffMs` 的批 —— 批是问的容器,问走光了它才走。
+     * 一条语句,同上;三形同答。
+     */
+    reapEmptyBatches(cutoffMs: number, limit: number): Promise<number>;
     /** 🔴 车1 追加(不在设计定稿 §4 的接口字面清单里):设计的 `ApprovalAskStore` 接口本身没有批读方法,
      *  但 §6 测试钉(3/6/7 条)要求断言批行的 state/boundAskId 变化——没有读口就无法验证 store 真做对了
      *  它自己承诺的事。加一个纯观测方法(不改变任何写路径行为),SQL 双方言 + InMemory 三形都实现,
@@ -667,6 +684,14 @@ export declare class SqlApprovalAskStore implements ApprovalAskStore {
     deferReconcile(askId: string, expectedState: AskState, expectedRev: number, nowMs: number): Promise<boolean>;
     resolveProvisional(askId: string, from: AskState, to: AskState, patch: AskTransitionPatch): Promise<boolean>;
     deleteByTask(taskId: string): Promise<void>;
+    /**
+     * 留存律的问行半场(谓词见接口注)。一条带 `LIMIT` 的 `DELETE`(PG 无 `DELETE … LIMIT` ⇒ `ctid IN (SELECT … LIMIT)`,与
+     * `permission-rule-store-sql.ts` 的清扫同形);终态闭集从 {@link ASK_TERMINAL} 展开成占位符,不在 SQL 里手抄态名;挂靠集对三格各一句
+     * (MySQL `NOT IN (?, …)` 三次展开、PG 同一只 `text[]` 参数用三次 `<> ALL`),空集不加。`limit` 先过整数门再内联(本仓常量,门只防将来的误用)。
+     */
+    reapSettledAsks(cutoffMs: number, limit: number, keepAnchors: ReadonlySet<string>): Promise<number>;
+    /** 留存律的批行半场(谓词见接口注):一条带 `LIMIT` 的 `DELETE`,批里有没有问 = 对问表的 `NOT EXISTS`。 */
+    reapEmptyBatches(cutoffMs: number, limit: number): Promise<number>;
     getBatch(batchId: string): Promise<BatchRow | null>;
 }
 /** MySQL-protocol(TiDB)绑定。 */