@sema-agent/server 7.75.4 → 7.76.0

package/USAGE.md

@@ -755,21 +755,37 @@ A2A_SERVE_BLOCKING_WAIT_MS=45000             # blocking:true 的服务端等待
 SEMA_PARENT_PID=$$      # 壳把自己的 pid 传给它 spawn 出来的引擎
 ```
 
-- **缺席 = 整件不装配**(opt-in)。不设 = 和以前**逐字节一致**,存量部署零变化。
-- **探活** = `process.kill(pid, 0)`(不投递任何信号,只问"这个 pid 在不在")。`ESRCH` = 父不在;
-  **`EPERM` = 父还活着**(进程在,只是本进程无权给它发信号 —— 父跑在另一个 uid 下时很常见)。
-- **连续两拍**(拍频固定 **15s**)都是 `ESRCH` 才判死,单拍抖动不误杀。判死后走的是**和 `SIGTERM`
-  逐字同一条**优雅排空腿(`DRAIN_GRACE_MS` 那条):in-flight 的 run 照常结算 / park,不是裸退出。
-- **拍频不开旋钮**(15s 写死)。有真需求再议 —— 这里刻意不增殖一个只有一个人会调的键。
-- 日志:装配时一行 `parent_watch_armed`(带 `pid`),自退时一行 `parent_watch_exit`(带两拍的时间戳)。
+`DB_BACKEND=local` 上还多一层痛:那只孤儿抱着 `<数据根>/LOCK` 不放(判定持锁人是否还在用的就是
+`process.kill(pid,0)`,所以**活着的孤儿是合法持锁人**),于是此后每一只新壳起自己的引擎都撞
+`another instance (pid N) owns this data dir` —— 用户看到的是"壳崩过一次以后就再也起不来了"。
+
+- **缺席 = 整件不装配**(opt-in)。不设 = 和以前**逐字节一致**,存量部署零变化。systemd / launchd /
+  容器托管的引擎本来就 reparent 到 1,**不要**给它们设这个键。
+- **判死 = 两支,任一成立即判死**(拍频固定 **2s**):
+  - **被过继走**(强身份):`process.ppid` 不再是引擎启动那一刻的那个值 —— 生我的进程没了,内核就把我
+    过继给 init(或容器里的 subreaper)。判据刻意**不是** `ppid == 1`:收养者未必是 1,而且壳自己就是
+    pid 1 的容器形里 `== 1` 会在开机第一拍误杀一台健康引擎。
+  - **pid 不存在**(弱身份):`process.kill(pid, 0)` 抛 `ESRCH`(不投递任何信号,只问"这个 pid 在不在")。
+    **`EPERM` = 父还活着**(进程在,只是本进程无权给它发信号 —— 父跑在另一个 uid 下时很常见)。
+- **单拍即判,不去抖**:两支读的都是内核直答,不是会抖的采样值。判死后走的是**和 `SIGTERM` 逐字同一条**
+  优雅排空腿(`DRAIN_GRACE_MS` 那条):in-flight 的 run 照常结算 / park,不是裸退出;收尾链里的
+  `backend.close()` 才是把 `LOCK` 真正还回去的那一步。**实测**:壳挨 `kill -9` 到引擎退干净(退出码 0)
+  且 `LOCK` 消失 ≈ **2s**,部署面按 **≤5s** 用。
+- **拍频不开旋钮**(2s 写死)。有真需求再议 —— 这里刻意不增殖一个只有一个人会调的键。
+- 日志:装配时一行 `parent_watch_armed`(`info`,带 `pid` / `ppidAtArm` / `intervalMs`),判死时一行
+  `parent_watch_exit`(**`warn`** —— 非计划内的停机,带 `reason: "reparented" | "esrch"`),随后就是那条
+  `draining_started`。
 - 坏值(`0` / 负数 / 小数 / 非数字 / 超过 `2147483647`)**拒启并指路**:`0` 和负数在 `process.kill` 里的
   语义是**进程组**,超出 int32 的值 `process.kill` 根本收不下(会变成"armed 了但永远探不动")。要关掉就
-  **不设**这个键。探活若给出既不是 `ESRCH` 也不是 `EPERM` 的 errno,会打一条(仅一条)
-  `parent_watch_probe_error` 并按"父还活着"处理 —— 监视此时是失效的,那行日志就是它唯一的告警。
-- 🔴 **已知残余(不收窄,两条)**:① 两拍窗口(≤30s)内父 pid 被系统**复用**时,探活看到的是新进程,
-  监视判"父还活着"而不自退;② 父进程退出后成了**僵尸**(它自己的上级不回收子进程 —— 容器里的朴素
-  PID 1 是典型;终端 / launchd / systemd 不在此列),pid 表项仍在,探活同样判"活着"。两条同源:
-  `kill(pid, 0)` 是**弱身份**判据。这条腿是**尽力自愈**,不是强一致的父子生命周期绑定。
+  **不设**这个键。探活若给出既不是 `ESRCH` 也不是 `EPERM` 的 errno,会打一条(仅一条)**`warn` 档**
+  `parent_watch_probe_error` 并按"父还活着"处理 —— 弱身份那一支此时是失效的(强身份支不受影响),那行
+  日志就是它唯一的告警。
+- 🔴 **已知残余(不收窄,两条)**:① 引擎**还在 boot**(监视腿装在 `listen()` 之后)时父就死了**且**成了
+  **僵尸**(它自己的上级不回收子进程 —— 容器里的朴素 PID 1 是典型;终端 / launchd / systemd 不在此列)
+  —— 强身份支没有"变化"可看,弱身份支被僵尸的 pid 表项骗住,两支都不触发;② 壳经一层 **wrapper** spawn
+  引擎却仍传自己的 pid 时,wrapper 先退会让强身份支判死一台壳还活着的引擎(约定是**壳直接 spawn 引擎**,
+  别把这个键设成非直接父的 pid)。这条腿是**尽力自愈**,不是强一致的父子生命周期绑定 —— 要强一致,该由
+  壳侧开一条持有型管道并在断开时收尸。
 
 **可选 — 附着租约自退(`ENGINE_AUTO_EXIT`,默认关)**
 

package/dist/boot/reapers.d.ts

@@ -20,7 +20,7 @@ import type { Logger } from "../observability/logger.js";
 import type { Metrics } from "../observability/metrics.js";
 import type { WorkflowNotifyGate, WorkflowNotifyJournalStore } from "../orchestration/workflow-notify-journal.js";
 import type { TaskAttachmentStore } from "../plugins/task-attachment-store.js";
-import type { CheckpointStoreFull, CostQuotaStore, ImageBake, RateLimiterStore, ServiceWorkflowJournalStore, StoreBackend, ToolResultStoreFull } from "../plugins/store-backend.js";
+import type { ApprovalNonceStore, CheckpointStoreFull, CostQuotaStore, ImageBake, RateLimiterStore, ServiceWorkflowJournalStore, StoreBackend, ToolResultStoreFull } from "../plugins/store-backend.js";
 import type { ToolApprovalCoordinator } from "../tool-approval.js";
 /** [ref] / [ref]§五(sema-comms `audits/failopen-governance-176.md` §7 "Z 类 1 条"):default consecutive-failure
  *  count before a reaper leg's swallowed error gets a `warn` line. The ~15 `.catch(() => undefined)` sites
@@ -96,6 +96,10 @@ export interface ReapersCtx {
      *  (`boot/permission-rules-audit.ts` 的 `DormantRuleCounter` 是同一条判据的先例)。
      *  生产传的仍是整只束(结构上满足这个窄口)。 */
     permissionRuleStores: PermissionRuleRetentionSweeper | undefined;
+    /** S-280 直连门 nonce 的消费记录店 —— 本 tick 只用它的**到期清扫**一手。行至多活 ~150 秒(= 证明还能被
+     *  受理的最后一刻),所以存量是「到达率 × TTL」而不是历史总量,清扫无需分批。无 backend 的 env-only
+     *  部署 ⇒ undefined ⇒ 本腿零调用(那种部署也没有 durable 审批门)。 */
+    approvalNonceStore: ApprovalNonceStore | undefined;
     /** 晚绑(server 造出来才有)——见文件头「位置即契约」①。 */
     getRunDenySweep: () => ((now: number) => Promise<void>) | undefined;
 }

package/dist/boot/reapers.js

@@ -56,7 +56,7 @@ export function createPlacementAwareReapSessions(deps) {
     };
 }
 export function startReapers(ctx) {
-    const { config, logger, metrics, localRoot, backend, subRunner, runStore, checkpointStore, rateLimiter, costQuota, toolResultStore, fileHistoryStore, taskAttachmentStore, imageBakes, worktreeReap, workflowNotifyGate, workflowRecoverOpts, workflowJournalStore, sqlWorkflowRunStore, workflowNotifyJournal, rosterStore, backgroundAgentStore, mailboxStore, toolApproval, permissionRuleStores, getRunDenySweep, } = ctx;
+    const { config, logger, metrics, localRoot, backend, subRunner, runStore, checkpointStore, rateLimiter, costQuota, toolResultStore, fileHistoryStore, taskAttachmentStore, imageBakes, worktreeReap, workflowNotifyGate, workflowRecoverOpts, workflowJournalStore, sqlWorkflowRunStore, workflowNotifyJournal, rosterStore, backgroundAgentStore, mailboxStore, toolApproval, permissionRuleStores, approvalNonceStore, getRunDenySweep, } = ctx;
     const leg = (p) => {
         if (p !== undefined)
             trackMaintenanceLeg(p);
@@ -80,6 +80,7 @@ export function startReapers(ctx) {
     const runsReapStaleGuard = createThrottledReaperCatch("runs_reap_stale", logger);
     const e2bOrphanGuard = createThrottledReaperCatch("e2b_orphan_reclaim", logger);
     const checkpointsReapExpiredGuard = createThrottledReaperCatch("checkpoints_reap_expired", logger);
+    const approvalNonceReapExpiredGuard = createThrottledReaperCatch("approval_nonce_reap_expired", logger);
     const runsFailSuspendedExpiredCheckpointGuard = createThrottledReaperCatch("runs_fail_suspended_expired_checkpoint", logger);
     const runDenySweepGuard = createThrottledReaperCatch("run_deny_sweep", logger);
     const runsReapSuspendedGuard = createThrottledReaperCatch("runs_reap_suspended", logger);
@@ -208,6 +209,10 @@ export function startReapers(ctx) {
             leg(getRunDenySweep()?.(Date.now())
                 .then(() => runDenySweepGuard.onSuccess(), runDenySweepGuard.onError));
         }
+        leg(approvalNonceStore
+            ?.reapExpired()
+            .then(reapCount("approval_nonces_reaped_total", {}))
+            .then(() => approvalNonceReapExpiredGuard.onSuccess(), approvalNonceReapExpiredGuard.onError));
         if (config.approvalTimeoutSec > 0) {
             leg(runStore
                 ?.reapSuspended(config.approvalTimeoutSec * 1000)

package/dist/boot/shutdown.js

@@ -143,11 +143,15 @@ export function installShutdownHandlers(ctx) {
     });
     process.on("SIGHUP", onSighup);
     if (config.parentPid !== undefined) {
+        const parentWatchSink = {
+            info: (event, fields) => logger.info(event, fields),
+            warn: (event, fields) => logger.warn(event, fields),
+        };
         parentWatch = createParentWatch({
             pid: config.parentPid,
             isStopped: () => closing || draining,
             drain: drainThenShutdown,
-            log: (event, fields) => logger.info(event, fields),
+            log: (level, event, fields) => parentWatchSink[level](event, fields),
         });
     }
     if (config.engineAutoExit) {

package/dist/config-catalog.js

@@ -380,7 +380,7 @@ export const CONFIG_CATALOG = [
     r("SEMA_FAILOPEN_PROBE", "observability", "path", "F 类 fail-open 命中的探针文件路径(在场时逐次追加 fail-open 行;缺席只走计数+一次性 warn)"),
     r("SEMA_NODE_MIRROR", "orchestration", "url", "SANDBOX_PKG_SOURCE=custom 的显式 node 分发镜像地址"),
     r("SEMA_NPM_REGISTRY", "orchestration", "url", "SANDBOX_PKG_SOURCE=custom 的显式 npm registry 地址"),
-    r("SEMA_PARENT_PID", "limitsHttp", "number", "引擎 parent 监视(壳 pid;连续两拍 ESRCH 判死走 drain 腿;0/负数语义完全不同 ⇒ 拒启)", { derivedDefaultNote: "缺席 ⇒ 整件不装配", configKey: "parentPid" }),
+    r("SEMA_PARENT_PID", "limitsHttp", "number", "引擎 parent 监视(壳 pid;被过继走或该 pid 不存在即判死,走 SIGTERM 同一条 drain 腿;0/负数语义完全不同 ⇒ 拒启)", { derivedDefaultNote: "缺席 ⇒ 整件不装配", configKey: "parentPid" }),
     r("SEMA_PIP_INDEX", "orchestration", "url", "SANDBOX_PKG_SOURCE=custom 的显式 pip index 地址"),
     r("SEMA_REGISTRY_ADMIN_TOKEN", "integrations", "secret", "写 center 的管理凭证(仅 boot 上报执行公钥用;刻意不入 ServiceConfig —— 不进 configHash/日志面)", { danger: SEC, scope: "bootstrap-only" }),
     r("SEMA_REGISTRY_DRY_RUN", "integrations", "boolean", "center 腿 dry-run(拉而不应用)", { staticDefault: "false" }),

package/dist/config-types.d.ts

@@ -1492,16 +1492,18 @@ export interface ServiceConfigFlat {
      *  T11 stands, just bounded instead of immediate. A SECOND SIGHUP (or SIGTERM) escalates to the normal drain
      *  path. Default 120s, floor 5s. Env: SIGHUP_IDLE_GRACE_MS. */
     sighupIdleGraceMs: number;
-    /** [ref](黑板 [ref]):引擎 **parent 监视**。壳自 spawn 引擎的同机形里,壳被 SIGKILL(崩溃/强杀,
+    /** [ref](判据 S-292 改版):引擎 **parent 监视**。壳自 spawn 引擎的同机形里,壳被 SIGKILL(崩溃/强杀,
      *  没有任何清理钩子)后引擎被 reparent 到 init 而**继续活着** —— 孤儿引擎占端口、占库连接、占模型
-     *  配额,而且再没有人会给它发 SIGTERM(T11 的进程组腿只覆盖信号送得到的形)。设了本键 = 引擎每 15s
-     *  用 `process.kill(pid, 0)` 探一拍这个 pid,**连续两拍** ESRCH(父不在)才判死;判死后走与 SIGTERM
+     *  配额、抱着 `LOCAL_DATA_ROOT/LOCK`(活孤儿是合法持锁人 ⇒ 下一只壳的引擎必撞锁),而且再没有人会给
+     *  它发 SIGTERM(T11 的进程组腿只覆盖信号送得到的形)。设了本键 = 引擎每 2s 自查一拍,**两支任一成立
+     *  即判死**:① `process.ppid` 不再是启动那一刻的值(被过继走,强身份);② `process.kill(pid, 0)` 抛
+     *  `ESRCH`(弱身份)。`EPERM` = 进程在、只是本进程无权给它发信号 ⇒ **算活着**。判死后走与 SIGTERM
      *  **逐字同一条** graceful drain 腿(in-flight run 的结算 / park 语义与人工停机一致),不是裸
-     *  `process.exit`。`EPERM` = 进程在、只是本进程无权给它发信号 ⇒ **算活着**。
+     *  `process.exit`。
      *  **缺席 ⇒ 整件不装配**(opt-in;存量部署逐字零变化);**非正整数 ⇒ 拒启**(带指路文案)。
-     *  拍频固定 15s,不开 interval 旋钮(有真需求再议,防旋钮增殖)。
-     *  已知残余(成文,不收窄):两拍窗口内 pid 被系统复用 ⇒ 探活看到的是**新**进程,监视判"父还活着"
-     *  而不自退。监视是**尽力自愈**、不是强一致的父子生命周期绑定。 Env: `SEMA_PARENT_PID`。 */
+     *  拍频固定 2s,不开 interval 旋钮(有真需求再议,防旋钮增殖)。
+     *  已知残余(成文,不收窄)见 `src/parent-watch.ts` 头注(boot 窗内的僵尸父 / 中间 wrapper 进程两形)。
+     *  监视是**尽力自愈**、不是强一致的父子生命周期绑定。 Env: `SEMA_PARENT_PID`。 */
     parentPid?: number;
     /** [ref](黑板 [ref]②):引擎**附着租约自退**总开关。壳自 spawn 引擎的本机形里,壳退出之后引擎
      *  继续活着 = 占端口/占库连接/占模型配额的孤儿。设了本键 = 引擎每 15s 自查一次「还有没有人附着」,

package/dist/http/routes/approvals-assistant.js

@@ -7,6 +7,7 @@ import { isParkedRunStatus } from "../../plugins/store-contracts.js";
 import { principalFrom, decodeCheckpointScope, PRINCIPAL_TOKEN_HEADER, APPROVAL_MAC_HEADER, APPROVAL_MAC_KID_HEADER } from "../../security.js";
 import { verifyDirectDoorProof } from "../../principal-jwt.js";
 import { MAX_APPROVAL_REASON_CHARS } from "../../approval-hmac.js";
+import { MAX_APPROVAL_NONCE_CHARS } from "../../plugins/approval-nonce-store.js";
 import { redactedPreview, redactSecrets } from "../../trace/redact.js";
 import { redactRiskDescriptor } from "../../observability/run-terminal-log.js";
 import { fleetRunLabels } from "../../fleet/fleet-bus.js";
@@ -363,6 +364,21 @@ async function handleApprovalsAssistantBody(req, res, url, ctx, miss) {
                 sendError(res, 413, "reason_too_large", `reason too large (max ${MAX_APPROVAL_REASON_CHARS} chars)`);
                 return;
             }
+            if (body.boundCallId !== undefined) {
+                if (typeof body.boundCallId !== "string" || body.boundCallId.length === 0) {
+                    sendError(res, 400, "request.field_invalid", "boundCallId must be a non-empty string (the single-use nonce the signer folded into cnf.bnd and the HMAC envelope)");
+                    return;
+                }
+                if (body.boundCallId.length > MAX_APPROVAL_NONCE_CHARS) {
+                    sendError(res, 400, "request.field_invalid", `boundCallId too large (max ${MAX_APPROVAL_NONCE_CHARS} chars)`);
+                    return;
+                }
+                if (!deps.config.directDoorActive) {
+                    sendError(res, 400, "request.field_conflict", "boundCallId (the plan_review nonce) is only valid on a direct-door worker — a BFF worker carries no decision proof to bind it to");
+                    return;
+                }
+            }
+            const planNonce = typeof body.boundCallId === "string" ? body.boundCallId : undefined;
             const run = await deps.runStore.getRun(taskId);
             if (!run) {
                 if (deps.config.directDoorActive) {
@@ -374,14 +390,22 @@ async function handleApprovalsAssistantBody(req, res, url, ctx, miss) {
                 return;
             }
             let deciderPrincipal = principal;
+            let singleUse;
             if (deps.config.directDoorActive) {
+                const store = deps.approvalNonceStore;
+                if (store === undefined) {
+                    sendError(res, 501, "capability.store_required", "plan_review on a direct-door worker requires a durable approval-nonce store (DB_BACKEND=mysql|pg|local) — without it the single-use proof nonce cannot be enforced, and this worker will not accept a replayable proof");
+                    return;
+                }
+                const storeNowMs = await store.nowMs();
                 const hdr = (n) => { const h = req.headers[n]; return Array.isArray(h) ? h[0] : h; };
-                const proof = verifyDirectDoorProof({ jwt: hdr(PRINCIPAL_TOKEN_HEADER), mac: hdr(APPROVAL_MAC_HEADER), kid: hdr(APPROVAL_MAC_KID_HEADER) }, { sessionId: run.sessionId, decision, reason: typeof body.reason === "string" ? body.reason : null }, deps.config, { actionBinding: false });
+                const proof = verifyDirectDoorProof({ jwt: hdr(PRINCIPAL_TOKEN_HEADER), mac: hdr(APPROVAL_MAC_HEADER), kid: hdr(APPROVAL_MAC_KID_HEADER) }, { sessionId: run.sessionId, boundCallId: planNonce ?? null, decision, reason: typeof body.reason === "string" ? body.reason : null }, deps.config, { actionBinding: false, nowSec: Math.floor(storeNowMs / 1000) });
                 if (!proof.ok) {
                     sendError(res, proof.status, proof.errorCode, proof.error);
                     return;
                 }
                 deciderPrincipal = proof.principal;
+                singleUse = proof.singleUse === undefined ? undefined : { proof: proof.singleUse, store };
             }
             const operators = deps.config.operatorPrincipals;
             const explicitOperator = explicitOperatorOk(deciderPrincipal, operators);
@@ -390,6 +414,18 @@ async function handleApprovalsAssistantBody(req, res, url, ctx, miss) {
                 sendError(res, 404, "not_found.run", "task not found");
                 return;
             }
+            if (singleUse !== undefined) {
+                const { proof: onceOnly, store } = singleUse;
+                const fresh = await store.consume(run.sessionId, onceOnly.nonce, onceOnly.acceptedBeforeMs);
+                if (!fresh) {
+                    sendError(res, 409, "approval_replayed", "this decision proof has already been used (its single-use nonce is spent) — mint a fresh nonce and re-sign; a replayed plan_review is never applied");
+                    return;
+                }
+                if ((await store.nowMs()) >= onceOnly.acceptedBeforeMs) {
+                    sendError(res, 401, "principal_unverified", "principal token stopped being acceptable while this decision was being recorded — re-sign with a fresh nonce and retry");
+                    return;
+                }
+            }
             const out = await resumePlanReview(run.sessionId, decision, decision === "edit" ? body.editedPlan : undefined, typeof body.reason === "string" ? body.reason : undefined, req, { taskId, principalPresent: principal !== undefined }, true, { principal: deciderPrincipal, explicitOperator });
             sendResumeOutcome(res, out, deps.logger);
             return;

package/dist/http/server.d.ts

@@ -5,7 +5,7 @@ import type { TaskRequestBody } from "./wire-types.js";
 import type { ServiceConfig } from "../config-types.js";
 import { type RestartSignal, type SessionMirrorRuling } from "../config-center/facade.js";
 import { type OwnerAwareSessionStore } from "../security.js";
-import type { RunStore, ImageIndex, ImageBake, CheckpointStoreFull, ResumeAnchorStore, ApprovalExemptionStore, ServiceSessionPolicyStore, ServiceFileHistoryStore, ToolResultStoreFull, StoreBackend } from "../plugins/store-backend.js";
+import type { RunStore, ImageIndex, ImageBake, CheckpointStoreFull, ResumeAnchorStore, ApprovalExemptionStore, ApprovalNonceStore, ServiceSessionPolicyStore, ServiceFileHistoryStore, ToolResultStoreFull, StoreBackend } from "../plugins/store-backend.js";
 import type { RuleConsentLane } from "../rules-consent.js";
 import { type MemorySyncRequest, type MemorySyncResponse } from "../memory-sync.js";
 import type { TaskAttachmentStore } from "../plugins/task-attachment-store.js";
@@ -122,6 +122,10 @@ export interface ServiceStoreDeps {
     /** Per-session approval exemption store — enables decide body `remember:"session"` + the
      *  exemptions list/revoke surfaces on /v1/approvals. The ask-gate probe is wired separately (main.ts). */
     approvalExemptionStore?: ApprovalExemptionStore;
+    /** S-280:直连门审批证明的**一次性消费记录**(`plan_review` 的 nonce)。每条 store 车道都供,所以在任何
+     *  `DB_BACKEND` 上都在场;缺席只出现在装配缝(桩 deps)—— 那时直连门的 plan_review **拒**(501,见
+     *  `routes/approvals-assistant.ts` 的消费点),绝不静默受理一份结构上可重放的证明。BFF 门不读这只店。 */
+    approvalNonceStore?: ApprovalNonceStore;
     /** Durable-checkpoint store ([ref], core 1.67): durable F4 suspend/resume. When present, the resume
      *  endpoint + suspended-run surfacing are active. Set only when DURABLE_APPROVAL + a TiDB pool. */
     checkpointStore?: CheckpointStoreFull;

package/dist/main.js

@@ -368,6 +368,7 @@ async function main() {
     const runStore = backend ? backend.run() : undefined;
     const resumeAnchorStore = backend ? backend.resumeAnchor() : undefined;
     const approvalExemptionStore = backend ? backend.approvalExemption() : undefined;
+    const approvalNonceStore = backend ? backend.approvalNonce() : undefined;
     const taskTimeoutSec = Math.floor(parseNumOrFailNonNegative("TASK_TIMEOUT_SEC", process.env.TASK_TIMEOUT_SEC || "0"));
     const capEnv = (name) => {
         const r = parseCapEnv(name, process.env[name]);
@@ -502,7 +503,7 @@ async function main() {
         config, logger, metrics, localRoot, backend, subRunner, runStore, checkpointStore,
         rateLimiter, costQuota, toolResultStore, fileHistoryStore, taskAttachmentStore, imageBakes, worktreeReap,
         workflowNotifyGate, workflowRecoverOpts, workflowJournalStore, sqlWorkflowRunStore, workflowNotifyJournal, rosterStore,
-        backgroundAgentStore, mailboxStore, toolApproval, permissionRuleStores,
+        backgroundAgentStore, mailboxStore, toolApproval, permissionRuleStores, approvalNonceStore,
         getRunDenySweep: () => runDenySweep,
     });
     const ttlMs = config.retentionSweep.intervalSec * 1000 * RETENTION_LEASE_TTL_FACTOR;
@@ -605,6 +606,7 @@ async function main() {
         runStore,
         resumeAnchorStore: resumeAnchorStore ? resumeAnchorStore : undefined,
         approvalExemptionStore: approvalExemptionStore ? approvalExemptionStore : undefined,
+        approvalNonceStore: approvalNonceStore ? approvalNonceStore : undefined,
         checkpointStore,
         sessionPolicyStore: sessionPolicyStore ? sessionPolicyStore : undefined,
         ruleConsent,

package/dist/parent-watch.d.ts

@@ -1,54 +1,86 @@
 /**
- * [ref](黑板 [ref]):引擎 **parent 监视**。
+ * 引擎 **parent 监视**([ref] 建座,S-292 改判据)。
  *
  * ## 防的是什么
  *
  * 壳(cli/TUI/桌面)自 spawn 引擎的**同机形**里,壳被 SIGKILL(崩溃、`kill -9`、OOM killer)之后没有
  * 任何清理钩子跑得起来:引擎被 reparent 到 init,**继续活着** —— 占端口、占库连接池、占模型配额,而且
- * 再没有人会给它发 SIGTERM(T11 的"骑进程组"腿只覆盖信号送得到的形;SIGKILL 那一路本来就无钩)。
- * 于是引擎给自己装一只**自查**腿:定期问一句"当年生我的那个 pid 还在吗",不在就**自己**走正常停机。
+ * 再没有人会给它发 SIGTERM。`DB_BACKEND=local` 上还多一层:那只孤儿抱着 `LOCAL_DATA_ROOT/LOCK`
+ * (core `FileStorageBackend` 的 pidfile,失效判定是 `process.kill(pid,0)` ⇒ **活孤儿是合法持锁人**),
+ * 于是此后每一只新壳起自己的引擎都撞锁 fatal「another instance (pid N) owns this data dir」—— 用户看到
+ * 的是「壳崩过一次以后就再也起不来了」。持锁 pid 不存在时 core 已自动剪陈旧锁,缺的只有「父死、子活」
+ * 这一形。所以引擎给自己装一只**自查**腿:定期问一句"生我的那个还在吗",不在就**自己**走正常停机。
  *
  * ## 机制(逐条都是契约)
  *
  *  1. **opt-in**:`SEMA_PARENT_PID` 缺席 ⇒ 整件不装配(`boot/shutdown.ts` 连 `createParentWatch` 都不调)。
- *     存量部署逐字零变化。坏值拒启在 `config.ts` 的 `parentPidEnv()`。
- *  2. **探活 = `process.kill(pid, 0)`**:0 号信号不投递任何信号,只做"这个 pid 存在吗 + 我能不能给它
- *     发信号"的检查。两种失败方向**语义相反**,写反了后果不对称:
- *       · `ESRCH` = 没有这个进程 ⇒ 父**不在**(这是我们要抓的);
- *       · `EPERM` = 进程**在**,只是本进程无权给它发信号(父跑在另一个 uid 下 —— systemd/su/容器里
- *         很常见)⇒ **算活着**。把 EPERM 当"不在",每台这种机器上的引擎会在开机后两拍内自杀。
- *  3. **连续两拍才判死**:单拍抖动(探活恰好撞上一次瞬时错误)不误杀。任何一拍看到"活着"就清零。
+ *     存量部署逐字零变化 —— systemd / launchd / 容器托管的引擎本来就 reparent 到 1,自退是事故。
+ *     坏值(非正整数 / 超 int32)⇒ **启动期拒**,在 `config.ts` 的 `parentPidEnv()`。
+ *  2. **判死 = 两支合取口一句,任一成立即判死**,每 {@link PARENT_WATCH_INTERVAL_MS} 一拍:
+ *
+ *       · **强身份支 `reparented`**:`process.ppid` 不再是装配那一刻的那个值。生我的进程没了,内核就把
+ *         我过继给 init(或容器里的 subreaper)—— 这是**内核对亲子关系的直答**,不依赖 pid 的身份。
+ *         判据刻意**不写成 `ppid === 1`**:① 收养者未必是 1(PID 1 是 subreaper 的容器里不是);
+ *         ② 壳本身就是 pid 1 的容器形里(`SEMA_PARENT_PID=1`),`=== 1` 会在**开机第一拍**把一台健康
+ *         引擎判死。「不再是生我的那个」两种形都答得对,而且不需要任何特判。
+ *         🔴 **前提**(codex 复审 R1 [high],验真后修):这一支只有在「被监视的 pid 就是生我的那个」时
+ *         才等价于「它没了」。壳经一层 wrapper spawn 引擎却仍传**自己**的 pid 时,引擎的直接父是
+ *         wrapper —— wrapper 先退会让这一支把一台**壳还活着**的健康引擎连同 in-flight run 一起关掉。
+ *         前提在**装配那一刻**就能一次判完(`ppidAtArm === pid`),所以它是**装配期的开关**而不是每拍
+ *         的特判:不成立 ⇒ 强身份支整条不装,只留弱身份支(它在那一形下语义仍然正确),并且 armed 那行
+ *         改打 **warn** —— 覆盖面被降级了不许静默。
+ *       · **弱身份支 `esrch`**:`process.kill(parentPid, 0)` 抛 `ESRCH`。0 号信号不投递任何信号,只做
+ *         "这个 pid 存在吗 + 我能不能给它发信号"的检查。两种失败方向**语义相反**,写反了后果不对称:
+ *           - `ESRCH` = 没有这个进程 ⇒ 父**不在**(这是我们要抓的);
+ *           - `EPERM` = 进程**在**,只是本进程无权给它发信号(父跑在另一个 uid 下 —— systemd/su/容器里
+ *             很常见)⇒ **算活着**。把 EPERM 当"不在",每台这种机器上的引擎会在开机后一拍内自杀。
+ *
+ *     强身份支**先判**:它成立时这一拍连探活都不发 —— 弱判据没有资格给一个已经被过继走的进程改口
+ *     (僵尸父那一形里 `kill(pid,0)` 恰恰恒成功)。
+ *  3. **单拍即判,不去抖**。[ref] 定稿是「15s 一拍、连续两拍才判死」(上界 30s),S-292 整条退役:
+ *     部署面的判据是「壳挂了 ≤5s 内数据根重新可用」,而 `ESRCH` / `ppid` 都不是会抖的读数(两者都是
+ *     内核的直答,不是采样值)。去抖买不到确定性,只买到 15s 的延迟和一个 30s 长的 pid-复用窗口。
  *  4. **判死后走 `drain`**,即 `boot/shutdown.ts` 里 SIGTERM 用的那一条 `drainThenShutdown` —— in-flight
- *     run 的结算 / park 语义与人工停机**逐字一致**。本模块自己**从不** `process.exit`。
+ *     run 的结算 / park 语义与人工停机**逐字一致**,而且收尾链里的 `backend.close()` 才是把 `LOCK`
+ *     真正还回去的那一步。本模块自己**从不** `process.exit`。已有停机属主(`isStopped`)时站下不重入。
  *  5. **interval 必须 unref**:监视腿不得成为"进程本该退出却退不掉"的理由(与 drain tick 刻意不 unref
  *     的取向相反 —— 那一只 tick 就是停机驱动,这一只只是观察者)。
+ *  6. **日志分档**([ref] 响亮律):装配 = `info`;判死与探活自坏 = `warn`(非计划内的停机、以及"这条腿
+ *     此刻是失效的",都不许混在 info 流里)。档位是**闭集** {@link ParentWatchLogLevel},装配层用
+ *     `Record<ParentWatchLogLevel, …>` 派发 ⇒ 新增一档是编译错,不会静默落进 info。
  *
  * ## 已知残余(成文,现版不收窄)
  *
- *  · **pid 复用**:两拍窗口(≤30s)内父 pid 被系统复用,探活看到的是新进程,监视会判"父还活着"而不自退。
- *  · **僵尸父进程**(codex 复审 H,本机 perl fork 实测证实):`kill(pid, 0)` 只证明 **pid 表项**在,不证明
- *    进程还在跑 —— 父退出但**没被它自己的父进程 wait 回收**时留下 zombie(`ps STAT=Z`),表项还在,于是
- *    每一拍都判"活着",监视永不触发。触发条件是壳的**上级**不回收子进程(容器里的朴素 PID 1 是典型),
- *    终端 / launchd / systemd 起的壳不在此列。
- *
- * 两条都源于同一个根:`kill(pid, 0)` 是**弱身份**判据。收窄需要一个真身份锚(`process.ppid` 变化、
- * starttime、pidfd、或壳侧持有型管道),那是**机制换代**而不是参数微调,归设计属主裁。本件在定稿里
- * 就是**尽力自愈**、不是强一致的父子生命周期绑定 —— 要强一致,该由壳侧开一条持有型管道并在断开时收尸。
+ *  · **装配前就死掉的父**:监视腿装在 `listen()` 之后,`ppidAtArm` 也是那一刻取的。父在 boot 途中就死
+ *    **且**成了僵尸(它自己的上级不回收子进程)时,强身份支没有"变化"可看、弱身份支被僵尸的 pid 表项
+ *    骗住,两支都不触发。父只是普通地死掉(被回收)时弱身份支照样抓得到 —— 只有"boot 窗内 + 僵尸"这个
+ *    交集漏。要收口需要壳侧一条**持有型管道**(壳退出=管道 EOF),那是机制换代,归设计属主裁。
+ *  · **中间包装进程**:壳经一层 wrapper spawn 引擎(壳传自己的 pid,而引擎的直接父是 wrapper)时,强身份
+ *    支整条不装(见上,装配期判定 + warn),于是这一形退回 [ref] 的老覆盖面:僵尸壳抓不到。约定仍是
+ *    **壳直接 spawn 引擎**(`node dist/main.js`)—— 那一形两支都在。
  */
-/** 探活拍频。**固定值,不开 env 旋钮**(设计定稿:有真需求再议,防旋钮增殖)。 */
-export declare const PARENT_WATCH_INTERVAL_MS = 15000;
+/** 探活拍频。**固定值,不开 env 旋钮**(设计定稿:有真需求再议,防旋钮增殖)。
+ *  2s 的出处 = 部署面预算「壳挂掉后 ≤5s 数据根重新可用」减去一次 drain 的余量。 */
+export declare const PARENT_WATCH_INTERVAL_MS = 2000;
+/** 日志档位闭集。装配层按 `Record<ParentWatchLogLevel, …>` 派发 —— 新增一档必须在那里显式安置(编译错)。 */
+export type ParentWatchLogLevel = "info" | "warn";
+/** 判死缘由闭集(上 `parent_watch_exit` 的 `reason` 键,运维按它区分两支)。 */
+export type ParentDeathReason = "reparented" | "esrch";
 export interface ParentWatchDeps {
     /** 被监视的父 pid(`config.parentPid`,已在 config 层校验为正整数)。 */
     pid: number;
     /** 探活 seam:抛错 = 探活失败(`.code` 携 errno)。缺省 = `process.kill(pid, 0)`。
      *  存在的理由不是"可配置",是 `ESRCH`/`EPERM` 两支在测试里没有确定性的自然触发法。 */
     probe?: (pid: number) => void;
+    /** 亲子关系 seam:缺省 = `process.ppid`(**活读**,不是 boot 时的快照 —— 实测过继后当场变)。
+     *  存在的理由与 `probe` 相同:reparent 在进程内测试里没有确定性的触发法。 */
+    readPpid?: () => number;
     /** 已有停机属主(`closing || draining`)时监视腿站下:一次正在进行的优雅 drain 不该被"父也没了"
      *  升级成第二信号硬停(那会斩掉 in-flight leg —— 与本件"和人工停机逐字一致"的取向相反)。 */
     isStopped: () => boolean;
     /** 判死出口 = SIGTERM 那条 graceful drain。 */
     drain: () => void;
-    log: (event: string, fields: Record<string, unknown>) => void;
+    log: (level: ParentWatchLogLevel, event: string, fields: Record<string, unknown>) => void;
 }
 /** 装配并**立刻**起监视(装配即 `parent_watch_armed`)。返回停机链用的 `stop()`。 */
 export declare function createParentWatch(deps: ParentWatchDeps): {

package/dist/parent-watch.js

@@ -1,13 +1,25 @@
-export const PARENT_WATCH_INTERVAL_MS = 15_000;
+export const PARENT_WATCH_INTERVAL_MS = 2_000;
 export function createParentWatch(deps) {
     const probe = deps.probe ?? ((pid) => void process.kill(pid, 0));
-    let firstMissAtMs;
+    const readPpid = deps.readPpid ?? (() => process.ppid);
+    const ppidAtArm = readPpid();
+    const directParent = ppidAtArm === deps.pid;
     let stopped = false;
     let probeErrorReported = false;
-    deps.log("parent_watch_armed", {
+    deps.log(directParent ? "info" : "warn", "parent_watch_armed", {
         pid: deps.pid,
+        ppidAtArm,
+        directParent,
         intervalMs: PARENT_WATCH_INTERVAL_MS,
-        note: "engine watches this pid; TWO consecutive ESRCH probes trigger the same graceful drain as SIGTERM (EPERM = alive). Unset SEMA_PARENT_PID to disable.",
+        note: directParent
+            ? "engine watches this pid; it enters the same graceful drain as SIGTERM as soon as EITHER the engine is " +
+                "reparented away from it OR process.kill(pid,0) reports ESRCH (EPERM = alive). " +
+                "Unset SEMA_PARENT_PID to disable."
+            : "SEMA_PARENT_PID is NOT this engine's direct parent (ppid differs at arm time) — a wrapper process sits " +
+                "in between. The reparent arm is therefore NOT armed (it would stop a healthy engine when the wrapper " +
+                "exits while the watched process is still alive); only the process.kill(pid,0)/ESRCH arm is active, so a " +
+                "watched parent that exits WITHOUT being reaped (zombie) will not be detected. Spawn the engine directly " +
+                "from the process whose pid you pass.",
     });
     const timer = setInterval(() => {
         if (stopped)
@@ -16,41 +28,44 @@ export function createParentWatch(deps) {
             stop();
             return;
         }
-        let alive = true;
+        const ppid = readPpid();
+        if (directParent && ppid !== ppidAtArm) {
+            fire("reparented", { ppidAtArm, ppid });
+            return;
+        }
         try {
             probe(deps.pid);
         }
         catch (err) {
             const code = err?.code;
-            alive = code !== "ESRCH";
-            if (code !== "ESRCH" && code !== "EPERM" && !probeErrorReported) {
+            if (code === "ESRCH") {
+                fire("esrch", { ppid });
+                return;
+            }
+            if (code !== "EPERM" && !probeErrorReported) {
                 probeErrorReported = true;
-                deps.log("parent_watch_probe_error", {
+                deps.log("warn", "parent_watch_probe_error", {
                     pid: deps.pid,
                     code: code ?? "unknown",
                     err: String(err),
-                    note: "liveness probe failed with an errno that is neither ESRCH nor EPERM — treated as ALIVE (conservative), so this watch will NOT self-terminate while this persists",
+                    note: "liveness probe failed with an errno that is neither ESRCH nor EPERM — treated as ALIVE " +
+                        "(conservative), so the pid arm of this watch will NOT self-terminate while this persists " +
+                        "(the reparent arm is unaffected)",
                 });
             }
         }
-        if (alive) {
-            firstMissAtMs = undefined;
-            return;
-        }
-        if (firstMissAtMs === undefined) {
-            firstMissAtMs = Date.now();
-            return;
-        }
+    }, PARENT_WATCH_INTERVAL_MS);
+    timer.unref?.();
+    function fire(reason, fields) {
         stop();
-        deps.log("parent_watch_exit", {
+        deps.log("warn", "parent_watch_exit", {
             pid: deps.pid,
-            firstMissAtMs,
-            secondMissAtMs: Date.now(),
-            note: "parent pid gone on two consecutive probes — entering the SIGTERM graceful drain path",
+            reason,
+            ...fields,
+            note: "the parent that spawned this engine is gone — entering the SIGTERM graceful drain path",
         });
         deps.drain();
-    }, PARENT_WATCH_INTERVAL_MS);
-    timer.unref?.();
+    }
     function stop() {
         if (stopped)
             return;

package/dist/plugins/approval-nonce-store.d.ts

@@ -0,0 +1,94 @@
+import type { Pool as MysqlPool } from "mysql2/promise";
+import type { Pool as PgPool } from "pg";
+import { type SqlDriver } from "./sql-driver.js";
+/** 表名(单数形;`test/schema-naming-invariants.test.ts` 的闭集词表钉着)。 */
+export declare const APPROVAL_NONCE_TABLE = "approval_nonce";
+/**
+ * nonce 的**字符上限**。与 `reason` 的上限同姿势:**拒而不截**(截过的字节签名器复现不了 ⇒ MAC 恒不匹配,
+ * 把一个可诊断的 400 变成费解的 401)。190 = 本仓键列的标准宽度(`VARCHAR(190)`);以 JS 的 UTF-16 长度
+ * 设限是**保守**方向(星平面字符在 JS 里算 2、在两个引擎的 VARCHAR 里算 1),永远不会撞到列宽。
+ */
+export declare const MAX_APPROVAL_NONCE_CHARS = 190;
+export interface ApprovalNonceStore {
+    /**
+     * **这只店为它的记录计时的那口钟**(epoch ms)—— 见头注「到期 —— 一口钟」。
+     *
+     * 它是消费记录这条命上**唯一**的参照:受理窗的判定、落地后的复核、到期清扫三处全读它,于是
+     * 「还受理 ⇒ 记录还在」是结构性的,不靠「两台副本的钟差不多」这条没人声明过的假设。
+     *
+     * ⚠️ **要求:单调不减**。同源只挡「两只钟各走各的」,挡不住「这一只往回走」—— 钟回拨会让一条已被
+     * 清扫的记录所对应的证明重新过验签(头注「由构造」那段的残余,🚧 见 `approval-nonce-store.test.ts`)。
+     * 现役三实现都**不**自己强制这一条(Memory/File = `Date.now()`,SQL = 库钟),登记在案。
+     * 🔴 读不出来 ⇒ **响亮抛**([ref] fail-closed):调用方必须把它当不确定失败,**绝不**掉回本地墙钟。
+     */
+    nowMs(): Promise<number>;
+    /**
+     * 消费 `(sessionId, nonce)` —— **恰好一次**。
+     * @param expiresAtMs 这份证明还能被受理的最后一刻(epoch ms,**按 {@link nowMs} 这口钟**)。
+     * @returns `true` = 本次调用消费掉了它(首次);`false` = 它**已经**被消费过(= 重放)。
+     */
+    consume(sessionId: string, nonce: string, expiresAtMs: number): Promise<boolean>;
+    /**
+     * GC:删掉 `expires_at_ms <= ` **{@link nowMs}** 的记录,返回删除行数(维护 tick 调)。
+     *
+     * 🔴 **一个时钟入参都没有**,而且这不是省事:形参会让删除线由**跑清理的那台副本**说了算,而它跟
+     * 验签那台不是同一口钟 —— 那正是本店要消灭的那条依赖(与票据店 [ref] 删掉 `now: () => number`
+     * 同一条律:留着那只形参会让人以为「注一只假钟就能改记录的判决」)。测试要制造过期,把
+     * `consume` 的 `expiresAtMs` 相对 {@link nowMs} 往前挪即可 —— 那也是生产上唯一能让记录过期的方式。
+     */
+    reapExpired(): Promise<number>;
+}
+export declare class SqlApprovalNonceStore implements ApprovalNonceStore {
+    private readonly db;
+    constructor(db: SqlDriver);
+    private q;
+    /** 库钟({@link sqlDbNowMs})—— 一组无状态副本唯一共享的那口钟。读不出 ⇒ 响亮抛。 */
+    nowMs(): Promise<number>;
+    consume(sessionId: string, nonce: string, expiresAtMs: number): Promise<boolean>;
+    reapExpired(): Promise<number>;
+}
+/** MySQL 协议腿的构造绑定(与兄弟店同形:类名/构造元数不变,消费方不必动)。 */
+export declare class TiDBApprovalNonceStore extends SqlApprovalNonceStore {
+    constructor(pool: MysqlPool);
+}
+/** PostgreSQL 腿的构造绑定。 */
+export declare class PgApprovalNonceStore extends SqlApprovalNonceStore {
+    constructor(pool: PgPool);
+}
+export declare class MemoryApprovalNonceStore implements ApprovalNonceStore {
+    private readonly rows;
+    /** 单进程腿:店 = 这个进程,所以店钟就是本进程的墙钟(验签、复核、清扫本来就同一只钟,无第二口)。 */
+    nowMs(): Promise<number>;
+    consume(sessionId: string, nonce: string, expiresAtMs: number): Promise<boolean>;
+    reapExpired(): Promise<number>;
+}
+/**
+ * local 车道的持久腿:**单个**追加日志 + 内存索引 + 到期时的原子压实。
+ *
+ * 为什么不是「按会话一个文件」(兄弟 `FileApprovalExemptionStore` 的形):那只店的行**随会话长存**,
+ * 按会话分片才能按会话删;本店的行**至多活 ~150 秒**、且从不按会话查询 —— 分片只会在数据根里长出
+ * 一堆几行就作废的小文件。单文件 + 压实与行的生命周期同构。
+ *
+ * 崩溃语义:`append` 走 fsync。丢一条记录 = 那个 nonce 在它剩下的 TTL 里可被重放一次(与「整台副本重启」
+ * 的既有暴露同级,且 SQL 车道不受此影响);**绝不**能出现的是反向 —— 记录还在却被读成不在,那要靠
+ * `readJsonlRecords` 的断尾安全(半行丢弃)兜住。
+ */
+export declare class FileApprovalNonceStore implements ApprovalNonceStore {
+    private readonly path;
+    private readonly tmpDir;
+    /** key → 盘上那条记录**本身**(不是它的到期时刻):压实要把幸存者原样写回去,而把 `(sessionId, nonce)`
+     *  从复合键里**解析**出来是一条没必要的反向铸形 —— 记录留着就不必解析。 */
+    private readonly rows;
+    private log;
+    constructor(root: string);
+    private logFor;
+    /** local 车道:店 = 这台机器上的这个数据根,所以店钟就是本进程的墙钟(理由同 Memory 腿)。 */
+    nowMs(): Promise<number>;
+    consume(sessionId: string, nonce: string, expiresAtMs: number): Promise<boolean>;
+    reapExpired(): Promise<number>;
+    /** 释放追加 fd(`LocalBackend.close` → 优雅重启重开)。
+     *  刻意**不包 try/catch**:core 的 `AppendLog.close()` 自己就是全函数(`releaseFd` 内部吞掉 `closeSync`
+     *  的错),再包一层空 catch 只是一段永不执行的静默降级码 —— 兄弟 File 店那一层是历史包袱,不复制。 */
+    dispose(): void;
+}
+//# sourceMappingURL=approval-nonce-store.d.ts.map