@sema-agent/server 7.133.0 → 7.135.0

package/deploy/sema-up/README.md

@@ -154,6 +154,22 @@ data-center:2c/2G/20G)以下 BLOCK——确实无法稳定部署,提前警告不
 - **MinIO**:钉死的 tag(`minio/minio:RELEASE.…`,chart / cluster 静态清单 / compose 三份同值;k8s `imagePullPolicy: IfNotPresent`,不再 `:latest` + `Always`)。换源 = 换整条引用:
   compose 与 kube-up 读环境变量 `MINIO_IMAGE`(kube-up 给了才递给 chart),chart 直接 `--set minio.image=<源>/minio/minio:<tag>`(预灌镜像的节点 `--set minio.pullPolicy=Never`)。
 
+## 停驻钥匙的持久卷(helm 图表的 `sealedKey` 块)
+
+server 的 `<数据根>/sealed-key/` 存着停驻任务续跑上下文里请求凭据的封签钥匙(子目录 `checkpoint-ctx-keys/`)和模型钥匙 —— 私钥只在这个目录里、不进库。
+图表(`kube-up.sh` 的 `--kube=existing|k3s`、`cluster-up.sh` 的 `STACK_ENGINE=helm`)缺省把整个目录挂成一只 PVC(`sealedKey.persistence.enabled: true`),
+容器内路径 `/root/.ai-agent/sealed-key`,主 worker 与启用的 `serverV4pro` 共用:重启与换副本都不丢钥匙,停驻的任务照常续跑。
+
+- **访问模式缺省随共享这只卷的 pod 数**:`server.replicas`(加上启用的 `serverV4pro.replicas`)为 1 ⇒ `ReadWriteOnce`,多于 1 ⇒ `ReadWriteMany`,**要集群的存储类支持 RWX**
+  (Longhorn 走 NFS 共享管理器、每个节点要装 NFS 客户端;`local-path` 与多数云盘类不支持 ⇒ PVC 一直 Pending、server Pod 起不来)。点名存储类:`--set sealedKey.persistence.storageClass=<支持 RWX 的类>`。
+  单节点多副本(pod 都在同一个节点)用 `--set sealedKey.persistence.accessMode=ReadWriteOnce` 显式盖(随包的 `values-full-single.yaml` 就这么写)。
+  有效访问模式是 `ReadWriteOnce` 时 Deployment 用 `Recreate`(RWO 卷同时只能被一个节点挂,滚动更新的新 Pod 落在别的节点就永远等不到卷;代价是升级窗口内短暂没有副本)。
+- **没有 RWX 的集群**:`--set server.replicas=1`,或单节点多副本盖 RWO(上一条),或关持久 `--set sealedKey.persistence.enabled=false` —— 关掉时图表**显式**给每只 worker 设 `DURABLE_APPROVAL=false`
+  (耐久审批整条关,不产生续不了的停驻行;`helm install` 打印的安装说明里也有这一句),且同时配 `server.durableApproval=true` 渲染即拒。
+- **首装是空卷**:多个 pod 并发首启会各自生成一把钥匙、各持自己那一把;装好后 `kubectl -n <ns> rollout restart deploy/sema-server`(启用 `serverV4pro` 时再加 `deploy/sema-server-v4pro`)一次,之后每个 pod 读到全部钥匙。
+- PVC 的 `accessModes` 建好后不可改:副本数跨过 1 的边界时 `helm upgrade` 会撞「spec is immutable」;卷里是私钥,换卷前先结掉停驻行或备份钥匙文件。
+  PVC 带 `helm.sh/resource-policy: keep`:`helm uninstall` 与把 `enabled` 改成 `false` 的 upgrade 都不删它(确认不要了再 `kubectl -n <ns> delete pvc sema-server-sealed-key`)。
+
 ## 凭据纪律
 
 全部凭据生成一次、落 `~/.sema-up/<project>/.env`(0600),重跑**绝不轮换**;

package/deploy/sema-up/chart/Chart.yaml

@@ -7,5 +7,5 @@ description: >-
   SC、kata-deploy(runtimeclass)、CNPG operator、runner-token 跨 ns 复制、MinIO 建桶、
   imagePullSecret(sema-regcred)。
 type: application
-version: 0.3.0
+version: 0.4.0
 appVersion: "1.156.1"

package/deploy/sema-up/chart/templates/NOTES.txt

@@ -0,0 +1,15 @@
+{{- $persist := eq (include "sema.sealedKey.enabled" .) "true" }}
+{{- if $persist }}
+停驻封签钥匙:server 的 <数据根>/sealed-key/ 在持久卷 {{ include "sema.sealedKey.claimName" . }}(挂在容器内 {{ include "sema.sealedKey.mountPath" . }},{{ include "sema.sealedKey.accessMode" . }}),重启与换副本都不丢钥匙,停驻的任务照常续跑。PVC 带 helm.sh/resource-policy: keep(helm uninstall 与把 sealedKey.persistence.enabled 改成 false 的 upgrade 都不删它)。
+{{- if eq (include "sema.sealedKey.accessMode" .) "ReadWriteOnce" }}
+有效访问模式是 ReadWriteOnce,server / serverV4pro 的 Deployment 用 Recreate 更新策略(RWO 卷同时只能被一个节点挂,滚动更新的新 Pod 落在别的节点会一直等不到卷;代价是升级窗口内短暂没有副本)。
+{{- end }}
+{{- if eq (include "sema.sealedKey.accessMode" .) "ReadWriteMany" }}
+多个 pod 共用这只卷,存储类必须支持 ReadWriteMany(PVC 一直 Pending 就是它不支持:出路 server.replicas=1,或 sealedKey.persistence.enabled=false 并接受耐久审批随之关)。
+{{- end }}
+{{- if gt (int (include "sema.sealedKey.podCount" .)) 1 }}
+首装是空卷:多个副本并发首启会各自生成一把钥匙、各持自己那一把 —— 装好后执行一次 kubectl -n {{ .Release.Namespace }} rollout restart deploy/sema-server{{ if .Values.serverV4pro.enabled }} deploy/sema-server-v4pro{{ end }},此后每个副本读到目录里的全部钥匙。
+{{- end }}
+{{- else }}
+停驻封签钥匙:sealedKey.persistence.enabled=false —— 不建卷,图表已给每只 worker 显式设上 DURABLE_APPROVAL=false(耐久审批整条关,不产生续不了的停驻行;代价见 values.yaml 的 sealedKey 块;要重新打开,把它改回 true)。关持久 + 提交体没声明 settings.approvalFrameFamilies 的客户端 ⇒ 受门工具当场拒(没有耐久店,无处停驻;7.134.0 起审批卡只发给声明认得这一族的客户端)。
+{{- end }}

package/deploy/sema-up/chart/templates/_helpers.tpl

@@ -0,0 +1,129 @@
+{{- /*
+  sealedKey 持久块的助手 —— 卷名 / 挂载路径 / 共享 pod 数 / 访问模式 / 耐久审批的渲值,各一处定义,主 worker(server.yaml)与
+  v4pro 变体(server-v4pro.yaml)同调,不各抄一份。
+
+  这是什么:server 的数据根下 `sealed-key/` 目录存两样东西 —— 模型钥匙(web-admin 贴的 `sealedApiKey` 的解封私钥)与停驻任务续跑上下文里
+  请求凭据的封签钥匙(子目录 `checkpoint-ctx-keys/`)。私钥只在这个目录里(不进库),所以它要**跨重启持久**、**每个副本是同一份**:
+  不持久 ⇒ 每次重启换钥匙,重启前停驻、带请求凭据的任务续跑恒 409 conflict.checkpoint_ctx_unsealable(reason key_not_held);
+  多副本各一份 ⇒ A 副本停驻的任务在 B 副本上同一个结局。
+
+  路径:镜像以 root 跑、本图表不设 LOCAL_DATA_ROOT / CONFIG_LOCAL_DIR / AGENT_DATA_DIR ⇒ 数据根是缺省 ~/.ai-agent = /root/.ai-agent。
+  给部署另设了数据根变量的人:挂载路径要跟着移(本图表不替部署设这几个变量)。
+*/ -}}
+
+{{- /* 卷 / PVC 的名字。 */ -}}
+{{- define "sema.sealedKey.claimName" -}}sema-server-sealed-key{{- end -}}
+
+{{- /* 容器内挂载点 = <数据根>/sealed-key(整个目录:模型钥匙 + checkpoint-ctx-keys/ 同一卷)。 */ -}}
+{{- define "sema.sealedKey.mountPath" -}}/root/.ai-agent/sealed-key{{- end -}}
+
+{{- /*
+  持久开关,且**只收布尔**:`--set-string ...enabled=false` / values 里带引号的 "false" 是字符串,模板里字符串恒为真 ⇒ 会静默保持持久开,
+  与写的人的意思相反,所以非布尔渲染即拒。输出 "true" / "false"。
+*/ -}}
+{{- define "sema.sealedKey.enabled" -}}
+{{- $v := .Values.sealedKey.persistence.enabled -}}
+{{- if not (kindIs "bool" $v) -}}
+{{- fail (printf "sealedKey.persistence.enabled must be a boolean (true or false), got %s %q — a string such as \"false\" is truthy in a template and would silently keep the volume on" (kindOf $v) (toString $v)) -}}
+{{- end -}}
+{{- $v -}}
+{{- end -}}
+
+{{- /* 一只 Deployment 的副本数:缺省(null,k8s 按 1 只起)不当 0 只数;其余按整数。 */ -}}
+{{- define "sema.sealedKey.replicasOf" -}}
+{{- if kindIs "invalid" . -}}1{{- else -}}{{- int . -}}{{- end -}}
+{{- end -}}
+
+{{- /* 共享这只卷的 pod 数:主 worker 的副本数 + 启用的 v4pro 变体的副本数(两者读同一个库里的停驻行,所以挂同一只卷)。 */ -}}
+{{- define "sema.sealedKey.podCount" -}}
+{{- $n := int (include "sema.sealedKey.replicasOf" .Values.server.replicas) -}}
+{{- if .Values.serverV4pro.enabled -}}
+{{- $n = add $n (int (include "sema.sealedKey.replicasOf" .Values.serverV4pro.replicas)) -}}
+{{- end -}}
+{{- $n -}}
+{{- end -}}
+
+{{- /*
+  访问模式:`sealedKey.persistence.accessMode` 留空 = 随共享 pod 数派生(一只 ReadWriteOnce,多只 ReadWriteMany —— 要集群的存储类支持 RWX,见 values.yaml sealedKey 块);
+  写了 ReadWriteOnce / ReadWriteMany = 显式盖。显式盖的用处:单节点、多副本 —— 所有 pod 在同一个节点上,RWO 就够,不必为它给节点装 NFS 客户端;
+  盖成 RWO 而 pod 其实会落在不同节点是写的人的前提(新 Pod 会卡在「卷被别的节点挂着」)。其它词渲染即拒。
+*/ -}}
+{{- define "sema.sealedKey.accessMode" -}}
+{{- $raw := .Values.sealedKey.persistence.accessMode -}}
+{{- $m := "" -}}
+{{- if not (kindIs "invalid" $raw) -}}
+{{- $m = toString $raw -}}
+{{- end -}}
+{{- if not (has $m (list "" "ReadWriteOnce" "ReadWriteMany")) -}}
+{{- fail (printf "sealedKey.persistence.accessMode must be empty (derive from the number of pods sharing the volume), \"ReadWriteOnce\" or \"ReadWriteMany\", got %q" $m) -}}
+{{- end -}}
+{{- if ne $m "" -}}
+{{- $m -}}
+{{- else if gt (int (include "sema.sealedKey.podCount" .)) 1 -}}
+ReadWriteMany
+{{- else -}}
+ReadWriteOnce
+{{- end -}}
+{{- end -}}
+
+{{- /*
+  Deployment 的更新策略:有效访问模式是 ReadWriteOnce ⇒ `Recreate`(`nindent 2` 接在 `replicas:` 之后)。RWO 卷同时只能被一个节点挂,默认的滚动更新先起新 Pod、
+  旧 Pod 要等新 Pod 就绪才放卷 —— 新 Pod 落在别的节点就永远等不到卷。代价:升级窗口内这一只 Deployment 短暂没有副本(只有一只 pod 的形本来就没有别的副本可接)。
+  RWX 与持久关闭不碰策略。
+*/ -}}
+{{- define "sema.sealedKey.strategy" -}}
+{{- /* 访问模式先取(取值即校验):持久关闭时写了非闭集词也拒,「其它词渲染即拒」不看开关。 */ -}}
+{{- $mode := include "sema.sealedKey.accessMode" . -}}
+{{- if and (eq (include "sema.sealedKey.enabled" .) "true") (eq $mode "ReadWriteOnce") -}}
+strategy: { type: Recreate }
+{{- end -}}
+{{- end -}}
+
+{{- /*
+  `server.durableApproval`(耐久审批,env DURABLE_APPROVAL)渲给 worker 的值:"" = 不渲(开关归引擎按姿态定),"true" / "false" = 显式。
+  布尔与字符串写法同义;其它词渲染即拒。持久被关(sealedKey.persistence.enabled=false)⇒ 固定 "false" —— 钥匙跨不过重启,耐久审批铸出来的停驻行
+  就是续不了的行,所以图表替部署**显式**关掉它(不是靠引擎的缺省碰巧关);同一份 values 又把它点名成 true ⇒ 渲染即拒,两个键各说各的就是矛盾。
+  `kindIs "invalid"` 判 nil(`--set server.durableApproval=null` 删键):不能用 `default ""` —— 布尔 false 在 `default` 里算空,会把显式 false 吞成「没表态」。
+*/ -}}
+{{- define "sema.durableApproval" -}}
+{{- $raw := .Values.server.durableApproval -}}
+{{- $want := "" -}}
+{{- if not (kindIs "invalid" $raw) -}}
+{{- $want = lower (trim (toString $raw)) -}}
+{{- end -}}
+{{- if not (has $want (list "" "true" "false")) -}}
+{{- fail (printf "server.durableApproval must be \"true\", \"false\" or empty (empty = the engine decides by posture), got %q" $want) -}}
+{{- end -}}
+{{- if eq (include "sema.sealedKey.enabled" .) "true" -}}
+{{- $want -}}
+{{- else -}}
+{{- if eq $want "true" -}}
+{{- fail "server.durableApproval=true cannot be combined with sealedKey.persistence.enabled=false: durable approvals park tasks whose request credentials are sealed under keys kept in the sealed-key volume, and without that volume every restart replaces the keys so no parked task could resume. Keep sealedKey.persistence.enabled=true (the default), or drop server.durableApproval (with persistence off the chart sets DURABLE_APPROVAL=false itself)" -}}
+{{- end -}}
+false
+{{- end -}}
+{{- end -}}
+
+{{- /* worker 容器 env 里的耐久审批一条(`nindent 12` 之后接在 env 列表里);值为空 ⇒ 什么都不出。 */ -}}
+{{- define "sema.sealedKey.env" -}}
+{{- with (include "sema.durableApproval" .) -}}
+- { name: DURABLE_APPROVAL, value: {{ . | quote }} }
+{{- end -}}
+{{- end -}}
+
+{{- /* worker 容器的 volumeMounts 块(`nindent 10`);持久关 ⇒ 什么都不出。 */ -}}
+{{- define "sema.sealedKey.volumeMounts" -}}
+{{- if eq (include "sema.sealedKey.enabled" .) "true" -}}
+volumeMounts:
+  - { name: sealed-key, mountPath: {{ include "sema.sealedKey.mountPath" . | quote }} }
+{{- end -}}
+{{- end -}}
+
+{{- /* Pod 的 volumes 块(`nindent 6`);持久关 ⇒ 什么都不出。 */ -}}
+{{- define "sema.sealedKey.volumes" -}}
+{{- if eq (include "sema.sealedKey.enabled" .) "true" -}}
+volumes:
+  - name: sealed-key
+    persistentVolumeClaim: { claimName: {{ include "sema.sealedKey.claimName" . }} }
+{{- end -}}
+{{- end -}}

package/deploy/sema-up/chart/templates/sealed-key.yaml

@@ -0,0 +1,24 @@
+# ── 停驻封签钥匙的持久卷(sealedKey.persistence.enabled,缺省开)──────────────────────────
+#    server 的 <数据根>/sealed-key/ 整个目录(模型钥匙 + 子目录 checkpoint-ctx-keys/ 的停驻行封签钥匙)挂这一只 PVC,
+#    主 worker 与启用的 v4pro 变体共用。私钥只在这里(不进库):卷丢了,封在停驻行里的请求凭据就开不开。
+#    访问模式随共享这只卷的 pod 数(助手 sema.sealedKey.accessMode):一只 ReadWriteOnce,多只 ReadWriteMany(要集群的存储类支持 RWX)。
+#    ⚠ PVC 的 accessModes 建好后不可改:副本数跨过 1 的边界(1 ⇄ 多)会让升级撞「spec is immutable」—— 响亮,不静默;见 values.yaml sealedKey 块。
+#    有效访问模式是 ReadWriteOnce 时 server / v4pro 两只 Deployment 用 Recreate(助手 sema.sealedKey.strategy)。
+{{- if eq (include "sema.sealedKey.enabled" .) "true" }}
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: {{ include "sema.sealedKey.claimName" . }}
+  namespace: {{ .Release.Namespace }}
+  annotations:
+    # 卷里是私钥:丢了,库里停驻行的请求凭据就开不开。`helm uninstall` 与「关持久」的 upgrade 都不顺手删它(确认不要了再 kubectl delete pvc)。
+    helm.sh/resource-policy: keep
+spec:
+  accessModes: [{{ include "sema.sealedKey.accessMode" . }}]
+{{- if .Values.sealedKey.persistence.storageClass }}
+  storageClassName: {{ .Values.sealedKey.persistence.storageClass | quote }}
+{{- end }}
+  resources:
+    requests:
+      storage: {{ .Values.sealedKey.persistence.size | quote }}
+{{- end }}

package/deploy/sema-up/chart/templates/server-v4pro.yaml

@@ -11,6 +11,9 @@ metadata:
   labels: { app: sema-server-v4pro }
 spec:
   replicas: {{ .Values.serverV4pro.replicas }}
+{{- with (include "sema.sealedKey.strategy" .) }}
+{{ . | indent 2 }}
+{{- end }}
   selector:
     matchLabels: { app: sema-server-v4pro }
   template:
@@ -75,10 +78,21 @@ spec:
             - { name: K8S_SANDBOX_IMAGE, value: {{ .Values.sandbox.image | quote }} }
             - { name: K8S_SANDBOX_IPV6, value: {{ .Values.sandbox.ipv6 | quote }} }
             - { name: K8S_TOKEN, valueFrom: { secretKeyRef: { name: sema-runner-token-copy, key: token } } }
+{{- /* 耐久审批的显式表态与停驻封签钥匙卷同源(助手 sema.durableApproval / sema.sealedKey.*,见 _helpers.tpl):关持久 ⇒ 显式 false;留空 ⇒ 不渲。 */}}
+{{- with (include "sema.sealedKey.env" .) }}
+{{ . | indent 12 }}
+{{- end }}
           readinessProbe:  # the only probe path is /readyz (/health is diagnostic, always 200)
             httpGet: { path: /readyz, port: 8090 }
             initialDelaySeconds: 5
             periodSeconds: 5
+{{- /* <数据根>/sealed-key 的持久卷(整个目录:模型钥匙 + 停驻封签钥匙);关持久时两块都不出。 */}}
+{{- with (include "sema.sealedKey.volumeMounts" .) }}
+{{ . | indent 10 }}
+{{- end }}
+{{- with (include "sema.sealedKey.volumes" .) }}
+{{ . | indent 6 }}
+{{- end }}
 ---
 apiVersion: v1
 kind: Service

package/deploy/sema-up/chart/templates/server.yaml

@@ -16,6 +16,9 @@ metadata:
   namespace: {{ .Release.Namespace }}
 spec:
   replicas: {{ .Values.server.replicas }}
+{{- with (include "sema.sealedKey.strategy" .) }}
+{{ . | indent 2 }}
+{{- end }}
   selector:
     matchLabels: { app: sema-server }
   template:
@@ -88,10 +91,21 @@ spec:
             - { name: K8S_SANDBOX_IMAGE, value: {{ .Values.sandbox.image | quote }} }
             - { name: K8S_SANDBOX_IPV6, value: {{ .Values.sandbox.ipv6 | quote }} }
             - { name: K8S_TOKEN, valueFrom: { secretKeyRef: { name: sema-runner-token-copy, key: token } } }
+{{- /* 耐久审批的显式表态与停驻封签钥匙卷同源(助手 sema.durableApproval / sema.sealedKey.*,见 _helpers.tpl):关持久 ⇒ 显式 false;留空 ⇒ 不渲。 */}}
+{{- with (include "sema.sealedKey.env" .) }}
+{{ . | indent 12 }}
+{{- end }}
           readinessProbe:  # the only probe path is /readyz (/health is diagnostic, always 200)
             httpGet: { path: /readyz, port: 8090 }
             initialDelaySeconds: 5
             periodSeconds: 5
+{{- /* <数据根>/sealed-key 的持久卷(整个目录:模型钥匙 + 停驻封签钥匙);关持久时两块都不出。 */}}
+{{- with (include "sema.sealedKey.volumeMounts" .) }}
+{{ . | indent 10 }}
+{{- end }}
+{{- with (include "sema.sealedKey.volumes" .) }}
+{{ . | indent 6 }}
+{{- end }}
 ---
 apiVersion: v1
 kind: Service

package/deploy/sema-up/chart/values-full-single.yaml

@@ -1,5 +1,5 @@
 # full-single(单节点 k3s dev/测试)覆盖:1 实例 PG、preferred 反亲和(required 在单机=永久
-# Pending——真踩)、2 副本 server。用法:
+# Pending——真踩)、2 副本 server(钥匙卷 RWO,见文末)。用法:
 #   helm upgrade --install sema-stack ./chart -n sema --create-namespace \
 #     -f chart/values-full-single.yaml --set server.image=… --set …(凭据)
 pg:
@@ -7,3 +7,7 @@ pg:
   antiAffinity: preferred
 server:
   replicas: 2
+# 钥匙卷:单节点上的 2 个副本在同一个节点,ReadWriteOnce 的卷同节点可共用 —— 不必为它给节点装 NFS 客户端(缺省的 ReadWriteMany 要 RWX 存储类)。
+sealedKey:
+  persistence:
+    accessMode: ReadWriteOnce

package/deploy/sema-up/chart/values.yaml

@@ -49,6 +49,10 @@ server:
   modelApiKey: ""          # REQUIRED
   modelVision: "false"
   requirePrincipal: "false"   # users=multi 时 true(身份隔离;compose 路径同名 env)
+  # 耐久审批(env DURABLE_APPROVAL;停驻 / 续跑 / /v1/approvals 整条路由)。留空 = 图表不渲这个 env,开关归引擎按姿态定
+  # (单用户 + 有耐久店 ⇒ 开;requirePrincipal=true 的多用户形 ⇒ 关);"true" / "false" = 显式表态,原样渲给每只 worker。
+  # sealedKey.persistence.enabled=false 时图表固定渲 "false"(钥匙跨不过重启,停驻行就续不了);此处再写 "true" ⇒ 渲染即拒。
+  durableApproval: ""
   # region=global 时置 "global"(B5 env-first);cn 留空 = 域内默认
   sandboxPkgSource: ""
   # k8s exec lane 的 TLS 姿势:true=渲染 K8S_INSECURE_TLS=true(chart 0.1.0 as-built);
@@ -66,6 +70,36 @@ server:
   s3PublicBucket: ""
   sendUserFileSandboxPutEndpoint: ""
 
+# 停驻封签钥匙的持久卷:server 的 <数据根>/sealed-key/ 整个目录挂一只 PVC(缺省开)。
+#   为什么:耐久审批(单用户 + 有耐久店时引擎缺省就开)停驻的任务,续跑上下文里请求自带的凭据只以封签落盘,封签的私钥只在这个目录里
+#   (子目录 checkpoint-ctx-keys/;同目录还有模型钥匙)——钥匙不进库。目录不持久 ⇒ 每次重启换一把钥匙;多副本各一份 ⇒ 换副本就换了钥匙。
+#   两种结局相同:重启 / 换副本之前停驻、带请求凭据的任务续跑恒答 409 conflict.checkpoint_ctx_unsealable(reason key_not_held),只能作为新任务重提。
+#   挂在哪:容器内 /root/.ai-agent/sealed-key(镜像以 root 跑、本图表不设数据根变量 ⇒ 数据根是缺省 /root/.ai-agent)。
+#   主 worker 与启用的 serverV4pro 变体共用同一只 PVC(它们读同一个库里的停驻行)。
+#   访问模式缺省随共享这只卷的 pod 数(server.replicas + 启用的 serverV4pro.replicas):1 只 ⇒ ReadWriteOnce;多只 ⇒ ReadWriteMany;`accessMode` 可显式盖(见下)。
+#   有效访问模式是 ReadWriteOnce 时,server / serverV4pro 两只 Deployment 用 Recreate 更新策略(RWO 卷同时只能被一个节点挂,滚动更新的新 Pod 落在别的节点就永远等不到卷;
+#   代价:升级窗口内这一只 Deployment 短暂没有副本)。
+#   ⚠ ReadWriteMany 要集群的存储类支持 RWX(Longhorn 的 RWX 走 NFS 共享管理器,每个节点要装 NFS 客户端 —— cluster-up.sh 不替你装;NFS / CephFS 类存储本就支持;
+#   local-path 与多数云盘类不支持,PVC 会一直 Pending、server Pod 起不来)。没有 RWX 的集群出路有三:server.replicas=1(RWO 即可);
+#   单节点多副本(所有 pod 在同一个节点)显式 accessMode: ReadWriteOnce(随包的 values-full-single.yaml 就是这么写的);或关掉持久(下面 enabled: false,耐久审批随之关 —— 代价见下)。
+#   ⚠ PVC 的 accessModes 建好后不可改:副本数跨过 1 的边界(1 ⇄ 多;启用 v4pro 也算一只)时 helm upgrade 会撞 PVC「spec is immutable」—— 响亮失败,不静默;
+#   这只卷里是私钥,不要为了过这个错直接删 PVC:先把停驻行结掉(随包排空检查脚本数一数)或备份钥匙文件,再换卷。
+#   PVC 带 helm.sh/resource-policy: keep:`helm uninstall` 与把 enabled 改成 false 的 upgrade 都不删它(钥匙留着;确认不要了再 `kubectl -n <ns> delete pvc sema-server-sealed-key`);
+#   同名 release 重装会接管这只留下的 PVC。
+#   ⚠ 空卷上多副本并发首启:每个副本看到空目录各自生成一把钥匙,各副本只持有自己那一把,直到下次重启 —— 首装后 `kubectl -n <ns> rollout restart deploy/sema-server`
+#   一次(启用 serverV4pro 时再加 deploy/sema-server-v4pro;NOTES 也说这句),重启之后每个副本读到目录里的全部钥匙,从此一致。
+sealedKey:
+  persistence:
+    # true(缺省)= 建 PVC 并挂到上面的路径。
+    # false = 不建卷、不挂载,图表**显式**给每只 worker 设 DURABLE_APPROVAL=false(不产生续不了的停驻行;NOTES 也打印这一句);
+    #   此时 server.durableApproval 再写 "true" ⇒ 渲染即拒。代价:耐久审批整条关(审批卡停驻 / 续跑、/v1/approvals 路由、/v1/capabilities 的 approvals 位);
+    #   web-admin 贴的模型钥匙 sealedApiKey 的私钥也跨不过重启(重启后那些条目答 stale_ciphertext,要对着新公钥重封)。
+    #   只收布尔:字符串 "false" 在模板里恒为真,会静默保持开着,所以渲染即拒。
+    enabled: true
+    size: 64Mi         # 只放几个几百字节的钥匙文件;留余量给文件系统开销
+    storageClass: ""   # 空 = 集群默认 SC;访问模式是 ReadWriteMany 时要点名一个支持它的类
+    accessMode: ""     # 空 = 随共享 pod 数派生(1 只 RWO,多只 RWX);"ReadWriteOnce" / "ReadWriteMany" = 显式盖,其它词渲染即拒
+
 # v4-pro 变体 worker(2026-07-11 手工 kubectl 资源收编进 chart;同镜像/同 env 面,仅 MODEL_ID 不同;
 # 公网入口=Gcore LB listener 8091 → nodePort,LB 面不归 chart 管)
 serverV4pro:

package/dist/adoption/plan.d.ts

@@ -161,7 +161,7 @@ export declare function checkAdoptionPrincipalShape(fromPrincipal: string, toPri
  */
 export declare function checkAdoptionWidths(fromPrincipal: string, toPrincipal: string): string | undefined;
 /** 两段键的 tenant / 属主段前缀(值对由 DISTINCT 扫描按前缀解出;扫描 SQL 的前缀臂由本表生成,一处):`proj:` / `userproj:`(core 文法)
- *  与单用户项目层 `userrepo:`(S-640,文法 `project-layer-key.ts`:属主段 = principal 的段编码)。 */
+ *  与单用户项目层 `userrepo:`([ref],文法 `project-layer-key.ts`:属主段 = principal 的段编码)。 */
 export declare const MEMORY_PROJECT_SCOPE_PREFIXES: readonly string[];
 /**
  * 一根身份轴上,「旧值 → 新值」的**值对**。`verbatim` 轴恒只有一对;`memory-scope` 轴的对数 =

package/dist/approval-ask-audit-store.d.ts

@@ -3,11 +3,11 @@
  * `server/designs/2026-08-31-s38-local-stream-approval-v1.md`,v1 三臂 + v1.1 §6 两件增益)——
  * local 车道(`DB_BACKEND=local`)的 **File ask 审计店**。SINGLE-FILE 店([ref] A12 单文件店纪律,
  * 形照 `plugins/memory-optout-grant-store-sql.ts`:一个实现文件、数据形/偏离/坏值姿态全部成文在头注;
- * 崩溃安全机制 = append-only JSONL、fsync 逐行、重放容忍撕尾行 —— 追加与重放都走本仓 JSONL 店族的**共用口**(S-967,见下「追加 / 重放口」段))。
+ * 崩溃安全机制 = append-only JSONL、fsync 逐行、重放容忍撕尾行 —— 追加与重放都走本仓 JSONL 店族的**共用口**([ref],见下「追加 / 重放口」段))。
  *
- * ## 它治的病([ref] / [ref]① 车定界钉;⚠️ **病因描述是 [ref] 当时的事实,S-384 起已变**)
+ * ## 它治的病([ref] / [ref]① 车定界钉;⚠️ **病因描述是 [ref] 当时的事实,[ref] 起已变**)
  * 当时:local 车道 ask 账进程内易失(`InMemoryApprovalAskStore`),活卡窗内崩溃 = **零痕迹**:重启后
- * `/v1/approvals` 两数组空,那次审批连一条审计行都没有。**S-384 起 local 的 ask 账已是持久的**
+ * `/v1/approvals` 两数组空,那次审批连一条审计行都没有。**[ref] 起 local 的 ask 账已是持久的**
  * (`FileApprovalAskStore`),所以「零痕迹」那句不再成立;本店今天还在的理由收窄成它**独有**的那一格:
  * `crashConverged` 这个 local-only 的 additive 读面(孤儿行的 `orphanState` / `resumeSafe` 两位)—— **腿证据只在这里**
  * (`legTracked` / `leg_closed` / 关停记号),ask 账没有。🔴 **「这一问还能不能决」不归本店答**:答案源是 ask 账的行状态
@@ -20,10 +20,10 @@
  * 操作员追溯。
  *
  * ## 它**不**做的事(裁 (c) 的边界,与稿 §1 (a) 臂的语义论证同源)
- *  - **不翻 `streamApproval` 能力位**([ref] 当时的裁 (c);⚠️ **这一位已由 S-384 翻真,不是被本店翻的**):
+ *  - **不翻 `streamApproval` 能力位**([ref] 当时的裁 (c);⚠️ **这一位已由 [ref] 翻真,不是被本店翻的**):
  *    当年不翻的理由是「该位在 SQL 车道隐含 durable park 兜底,local 给不了」+「local 的 ask 账是进程内
  *    易失形」。后半条已由 `FileApprovalAskStore` 消掉(持久账落地);前半条的答案一直在谓词里 ——
- *    `resolveStreamApprovalGate` 的 `parkFacility` 合取项要求 `backend.checkpoint` 在场 ∧ `DURABLE_APPROVAL`,
+ *    `resolveStreamApprovalGate` 的 park 设施(`checkpointStore`)合取项要求 `backend.checkpoint` 在场 ∧ `DURABLE_APPROVAL`,
  *    所以位报 true 的 local 部署**必然**配齐了 File 形 checkpoint 店(`durable-approval-local-e2e` 第一格
  *    实证:park 行跨双 kill 存活、重启后 decide 驱动 resume 真跑完)。本店与那一位自此无关:它治的是
  *    **活卡窗内崩溃**(park 还没落盘)那一格的零痕迹病,而那一格无论位真位假都不复活 run。
@@ -40,11 +40,11 @@
  *                     收敛器**不**把它当孤儿)+ 宿主自报(在场才带)+ **`cause`(成因闭集 {@link SettleCause},`approval-deny-reasons.ts`)**:
  *                     `outcome:"expired"`(非人结局)恒带、人答(`allowed` / `denied`)恒缺席 —— 写口的联合型逼每个非人调用点点名一个;
  *                     词表外 ⇒ 计坏行、结清照认;本版之前落盘的 `expired` 行没有 `cause`(存量审计行不回填,读面缺席即缺席)。
- *                     `cause:"shutdown_before_park"`(S-929)= 这次等待是被**有序关停**结束的 —— `drainForShutdown` 按断连同路收场的活卡;park 路由的那几行**等观察到 core 已处置这次调用才落**(F1:停车行提交 / 承载它的腿退场,后者恒在 `leg_closed` 之前),两者皆无就退出 ⇒ 无此行。
+ *                     `cause:"shutdown_before_park"`([ref])= 这次等待是被**有序关停**结束的 —— `drainForShutdown` 按断连同路收场的活卡;park 路由的那几行**等观察到 core 已处置这次调用才落**(F1:停车行提交 / 承载它的腿退场,后者恒在 `leg_closed` 之前),两者皆无就退出 ⇒ 无此行。
  *   `leg_closed`      腿闭点(`runWithContext` finally;只为铸过审计行的 taskId 落,防账本膨胀):
  *                     「决议之后腿有没有闭」是 decided 臂唯一的机械证据面 —— 没有它,「批完跑完」与
  *                     「批了、执行窗内崩」在账本字节上同形,收敛器只能二选一地撒谎。
- *   `interrupted_by_shutdown` **有序关停记号**(S-929;`drainForShutdown` 在关停宽限窗满时落,只为铸过审计行、腿仍未闭的 taskId):
+ *   `interrupted_by_shutdown` **有序关停记号**([ref];`drainForShutdown` 在关停宽限窗满时落,只为铸过审计行、腿仍未闭的 taskId):
  *                     「这条腿是被**有序关停**截断的,不是进程崩了」。它**不是** `leg_closed`(腿没闭:工具可能正执行到一半),所以
  *                     不改变收敛判据,只改变收敛行的 `cause`(`"shutdown_before_park"` 而不是 `"crashed_before_park"`)—— `resumeSafe:false`
  *                     那句「确认上次操作再续跑」的提醒不许因为关停是有序的就丢掉。
@@ -94,13 +94,13 @@
  *     **decided 臂**:批了、执行窗内崩,工具可能有半截副作用 ⇒ `resumeSafe:false`(留人工确认)。
  *     判据方向刻意**保守**:腿闭是「本进程对该腿的守护结束」,晚于工具真完成 —— 误差方向是「把可能
  *     干净的批注成待人工确认」,绝不反向。
- *   - **腿证据只对被追踪行作数**(S-945,[ref]):`leg_closed` 与 `interrupted_by_shutdown` 都只按 taskId 落,只对 `ask.legTracked` 的行作证据 ——
+ *   - **腿证据只对被追踪行作数**([ref],[ref]):`leg_closed` 与 `interrupted_by_shutdown` 都只按 taskId 落,只对 `ask.legTracked` 的行作证据 ——
  *     委派 / 后台子代 ask 行的 taskId 是宿主 run,宿主腿的记录不证明子代那次调用的任何事(下面三条判据都经这一口读)。
  *   - **腿闭反证门**(codex R1-F1 部分采):有 `ask`(被追踪)、无 `settle`、却有本 taskId 的后继 `leg_closed` ⇒
  *     这不是崩溃孤儿(settle 恒先于 ask() 返回、腿闭恒在其后),只能是「settle 行写丢在一条跑完了的
  *     腿上」的审计断档组 —— **不收敛**(标 pending = 把可能已执行的批注成 resumeSafe:true,方向反;
  *     标 decided = 凭空断言人批了),`inconsistent` 计数进 boot 日志。
- *   - **收敛行的 `cause`**(S-929,两臂同一条):该组最后一个事件行(settle 行,缺席则 ask 行)之后、它的收敛行(重投影时)
+ *   - **收敛行的 `cause`**([ref],两臂同一条):该组最后一个事件行(settle 行,缺席则 ask 行)之后、它的收敛行(重投影时)
  *     之前,有本 taskId 的 `interrupted_by_shutdown` 记号(被追踪行才认)⇒ `"shutdown_before_park"`(腿被有序关停截断);否则 `"crashed_before_park"`。
  *     记号**只改成因注,不改收敛判据**:有序关停下已批而腿未闭,工具照样可能半截副作用(decided 臂 `resumeSafe:false` 照留)。
  *     有序关停下的**未决**活卡由 `drainForShutdown` 先落 settle(`cause:"shutdown_before_park"`)⇒ 不再是 pending 孤儿(本就不收敛);
@@ -108,7 +108,7 @@
  *     与崩溃同路,证据不丢;腿被打过记号 ⇒ `shutdown_before_park`,零活流 / 子代腿无记号 ⇒ `crashed_before_park`)。
  *   - 其余(denied / expired / park 路由 / 已收敛)⇒ 不收敛。三条成文残留(fail-safe 方向,宁漏不误):
  *     ① `legTracked:false` 的 decided 行拿不到腿闭信号 ⇒ decided 臂对它不收(pending 臂不受此限 —— 但也因此没有腿闭反证门护着:
- *        子代卡照列 pending 孤儿但 `resumeSafe:false` —— 没有腿证据就不作「零执行」正断言(S-945 ⑧,车 SO codex r2 [high];修前 true = 方向反))。
+ *        子代卡照列 pending 孤儿但 `resumeSafe:false` —— 没有腿证据就不作「零执行」正断言([ref] ⑧,车 SO codex r2 [high];修前 true = 方向反))。
  *        两形同标 false:bg 腿(出处腿不在本协调器 runWithContext 视野)与**委派/bg 子代**(codex
  *        R1-F2:继承链闭包携宿主身份,origin.taskId = 宿主 run,宿主腿退场的 leg_closed 会把「批了、
  *        子代执行中崩」误反证成「跑完了」—— 铸造点 `!child` 合取如实标 false);
@@ -142,20 +142,20 @@
  * **终态成因注**(收敛器 fail-closed 地把孤儿收成 DENIED 同码并在读面显形),它的存在恰恰是响亮化
  * 本身,不是静默降级。本店的静默降级臂有两条:① 运行期 append 失败(审批可用性不押在审计盘上),已按
  * [ref] 律走 `recordFailOpen("server.approval-ask-audit.append-failed")`(census 第 53 行);② boot 重放跳过中间坏行
- * (S-967 起由重放属主逐条披露 + `server.approval-ask-audit.corrupt-record-skipped`,census 第 106 行;此前只计 `corruptLines`)。
+ * ([ref] 起由重放属主逐条披露 + `server.approval-ask-audit.corrupt-record-skipped`,census 第 106 行;此前只计 `corruptLines`)。
  * boot 期(mkdir/重放的读错)失败则**拒启**(与 File 店族同律:`FileStorageBackend` ctor 同 root 同姿态)——
  * 一台「审计写不进却继续批」的机器 = [ref] 换个皮回来。
  *
- * ## 追加 / 重放口(S-967:一只追加日志实现,不留两份)
+ * ## 追加 / 重放口([ref]:一只追加日志实现,不留两份)
  * 追加 = core `AppendLog`(惰性打开,首次 append 才铸文件;一行 = 单次 `writeSync` 的 `JSON.stringify(rec) + "\n"`、`fsync=true` 逐行;文件 0o600、目录 0o700;
  * 末段无换行的字节在打开与每次追加前由它按 core 的同一只判词修 —— 解析成对象 = 丢了换行的整条记录,**补换行、字节保留**;不解析 = 崩溃半写(撕尾),
- * **截断**回最后一个换行;解析成非对象 = 截断并披露(core 7.38.2 #1278))。重放 = `replayJsonlSkipping`(登记名 `approval-ask-audit`,fail-open + F 类 tag
+ * **截断**回最后一个换行;解析成非对象 = 截断并披露(core 7.38.2 [ref]))。重放 = `replayJsonlSkipping`(登记名 `approval-ask-audit`,fail-open + F 类 tag
  * `server.approval-ask-audit.corrupt-record-skipped`:中间坏行逐条披露 + 计数;撕尾不计,无换行的完整末行照常进重放)。本店只剩两样自己的东西:**形判据**({@link LEDGER_SHAPE},逐 `kind` 的最小必填键
  * + 词表外成因行「计坏行、结清照认」)与**失败方向**(运行期 append 失败 ⇒ `recordFailOpen("server.approval-ask-audit.append-failed")`,审批照常)。
- * **一行「在账」的判据 = 它的字节解析成一只对象**(与共用口同一条,core 7.38.2 #1278:读面、打开修尾、追加门修尾三站问同一只判词;换行只是边界的拼法,
+ * **一行「在账」的判据 = 它的字节解析成一只对象**(与共用口同一条,core 7.38.2 [ref]:读面、打开修尾、追加门修尾三站问同一只判词;换行只是边界的拼法,
  * 不是记录存在的条件 —— 没有一只 JSON 对象的真前缀能被解析,所以解析得出的末行就是整条记录;失败的 append 由 core 截回它开写处,不留自己的字节)。
  * 修前本店手写了第二份追加 / 修尾(私有的脏尾标 + 写字节注入席),撕尾用**孤立换行隔离**保留残字节而不是截断;与共用口的形差(撕尾隔离 ⇄ 截断、撕尾计数、
- * 字节全落却报错后多落的孤立换行、空白行计数、坏行披露)逐条记在 CHANGELOG 7.111.0 S-967 段,读数钉 = `test/approval-ask-audit.test.ts` 的「S-967」两组;
+ * 字节全落却报错后多落的孤立换行、空白行计数、坏行披露)逐条记在 CHANGELOG 7.111.0 [ref] 段,读数钉 = `test/approval-ask-audit.test.ts` 的「[ref]」两组;
  * 「完整 JSON 却缺换行的末行」一条(R2)在 core 7.38.2 下与修前同形(认下 + 补换行,C2 正向钉),不再是形差。
  *
  * ## 装配(为什么不在 `plugins/store-backend.ts`)
@@ -221,7 +221,7 @@ export type AuditSettleInput = (AuditSettleBase & {
     outcome: typeof SETTLE_OUTCOME.EXPIRED;
     cause: SettleCause;
 });
-/** 收敛行 `cause` 的闭集(`GET /v1/approvals` `crashConverged[].cause`):崩溃孤儿 / 有序关停截断的腿(S-929 +1;与 `crashed_before_park` 同形)。
+/** 收敛行 `cause` 的闭集(`GET /v1/approvals` `crashConverged[].cause`):崩溃孤儿 / 有序关停截断的腿([ref] +1;与 `crashed_before_park` 同形)。
  *  🔴 **词表属主 = `approval-deny-reasons.ts` 的 {@link HolderGoneCause}**(本表两词的子集):启动收敛把同一问的问账行收成 VOID 时 `denied_reason` 写的就是这两个词 ——
  *  同一问在 `crashConverged` 与决断口 410 体上只有一个成因词。wire 值闭集登记在 `trace/self-minted-wire.ts` 的 `crashConvergedCause`
  *  (`satisfies Record<HolderGoneCause, …>` 双向绑定 ⇒ 加词不登记 = tsc 红,wire 变更清单从那张表 diff —— F3)。 */
@@ -246,7 +246,7 @@ export interface AuditLateSettleInput {
      * 的成因,[ref] 件6③ 同律)。`"person"` = 运维经审批通道做的决定;`"sla_timeout"` = 宿主自己的 SLA 扫
      * 在行的 deadline 上判的。今天两条 HTTP decide 腿恒 `"person"`,但真值以调用方为准。
      *
-     * 🔴 S-136(core 7.6.0 [ref] S6-A):这一格此前记的是 core 的**结算词**(`ApprovalSettledBy`,
+     * 🔴 [ref](core 7.6.0 [ref] S6-A):这一格此前记的是 core 的**结算词**(`ApprovalSettledBy`,
      * 已删)。改记**事实**而不是词,理由是 core 的 `@contract settlement.single_mint` 逐字写着「宿主永不
      * 铸词」—— 账本要是记一个自己拼出来的 `human_refused`,server 就成了同一套词表的**第二个铸点**,
      * 而两个铸点的分歧一定是静默的。词的属主留在 core,取证要词就去读行的 `resolvedOutcome.gateOutcome`
@@ -265,7 +265,7 @@ export interface ApprovalAskAuditSink {
     recordSettle(input: AuditSettleInput): void;
     /** 腿闭点(`runWithContext` finally)。只为铸过审计行的 taskId 真落行(店内去重)。 */
     noteLegClosed(taskId: string): void;
-    /** S-929 有序关停记号点(`drainForShutdown` 宽限窗满时调一次):铸过审计行、腿仍未闭的每个 taskId 各落一条
+    /** [ref] 有序关停记号点(`drainForShutdown` 宽限窗满时调一次):铸过审计行、腿仍未闭的每个 taskId 各落一条
      *  `interrupted_by_shutdown`。 */
     noteLegsInterruptedByShutdown(): void;
     /** [ref] 迟到人工结算点(HTTP decide 两腿)。**纯观察**:自吞一切失败,不返回受否,绝不改变结算面。 */
@@ -301,7 +301,7 @@ export interface CrashConvergedRow {
      * 不是语义(改这个值会让把它当闭集判别式读的消费端整行丢弃,须与消费端同窗改)。
      */
     decision: "denied";
-    /** 成因注(闭集 {@link HolderGoneCause}):`crashed_before_park` = 进程崩了;`shutdown_before_park`(S-929)= 腿被**有序关停**截断
+    /** 成因注(闭集 {@link HolderGoneCause}):`crashed_before_park` = 进程崩了;`shutdown_before_park`([ref])= 腿被**有序关停**截断
      *  (判据见头注「收敛行的 `cause`」)。两者的 `orphanState` / `resumeSafe` 判据相同。 */
     cause: HolderGoneCause;
     orphanState: CrashOrphanState;
@@ -339,13 +339,13 @@ export declare class FileApprovalAskAuditStore implements ApprovalAskAuditSink,
     private readonly replayed;
     /** 前世账本里的腿闭事件(taskId + 行序;decided 臂按「决议行之后」判)。 */
     private readonly replayedLegClosed;
-    /** S-929:前世账本里的有序关停记号(taskId + 行序;收敛行 `cause` 的判据,见头注)。 */
+    /** [ref]:前世账本里的有序关停记号(taskId + 行序;收敛行 `cause` 的判据,见头注)。 */
     private readonly replayedShutdownMarks;
     /** 已收敛行(读面数据源;含前世已收敛 + 本次 boot 新收敛)。owner 只做 scope 门,不上 wire。 */
     private readonly convergedRows;
     /** 本进程铸过审计行、且腿闭信号可达的 taskId(腿闭去重 + 防无关腿刷账本)。 */
     private readonly openLegTasks;
-    /** S-929:本进程已落过有序关停记号的 taskId(记号去重;与腿追踪集分开 —— 记号之后的真实腿闭照落)。 */
+    /** [ref]:本进程已落过有序关停记号的 taskId(记号去重;与腿追踪集分开 —— 记号之后的真实腿闭照落)。 */
     private readonly shutdownMarkedLegs;
     private convergedOnce;
     /**
@@ -367,12 +367,12 @@ export declare class FileApprovalAskAuditStore implements ApprovalAskAuditSink,
      * boot 期 fail-stop:建目录 / 重放的**读错**(非 ENOENT)⇒ 抛 ⇒ **拒启**(File 店族同律)。root = local 数据根
      * (`config.localDataRoot`;与 `LocalBackend` 同源,见头注装配段)。
      * 0o700 目录 + 0o600 账本:行携租户身份(owner/sessionId),不得组/他人可读(目录由 core `ensureDir`、账本由 `AppendLog` 铸)。
-     * 追加口惰性打开(S-967,与 `FileUserInputLedgerStore` 同形):末段的修(撕尾截断 / 完整末行补换行)随首次 append 的打开发生 —— 重放读数不依赖它
+     * 追加口惰性打开([ref],与 `FileUserInputLedgerStore` 同形):末段的修(撕尾截断 / 完整末行补换行)随首次 append 的打开发生 —— 重放读数不依赖它
      * (撕尾不进重放、完整末行进重放,修前修后读数同);
      * 目录已在而盘后来满 / 变只读 ⇒ boot 照常,append 走 `recordFailOpen`。
      * @param internals.appendLog 测试注入席(见 {@link AuditAppendPort})。
      *
-     * 坏行披露 = F 类座纪律(S-1000:无 warn 出口)—— 每条跳过的行 `recordFailOpen` 计数 + 探针行,warn 每进程每 tag 一次。
+     * 坏行披露 = F 类座纪律([ref]:无 warn 出口)—— 每条跳过的行 `recordFailOpen` 计数 + 探针行,warn 每进程每 tag 一次。
      */
     constructor(root: string, internals?: {
         appendLog?: (path: string) => AuditAppendPort;
@@ -405,7 +405,7 @@ export declare class FileApprovalAskAuditStore implements ApprovalAskAuditSink,
     recordAsk(input: AuditAskInput): void;
     recordSettle(input: AuditSettleInput): void;
     noteLegClosed(taskId: string): void;
-    /** S-929:有序关停宽限窗满时仍未闭的腿各落一条记号。只为铸过审计行、腿仍开着的 taskId 落;记号有**自己的**去重集 ——
+    /** [ref]:有序关停宽限窗满时仍未闭的腿各落一条记号。只为铸过审计行、腿仍开着的 taskId 落;记号有**自己的**去重集 ——
      *  腿追踪集 `openLegTasks` **不动**:进程在记号之后仍可能活几秒(server / backend 收尾),期间真跑完的腿照常落 `leg_closed`
      *  (codex r1 F1 [high]:清空追踪集会吞掉这份真实证据,而「settle 写丢 + 腿跑完」时正是它让腿闭反证门判 inconsistent,
      *  吞掉就把一次已执行的批投影成 pending / `resumeSafe:true`)。迟到的腿闭落在记号之后 ⇒ 收敛判据照常认它(腿跑完了,不是孤儿)。 */
@@ -449,7 +449,7 @@ export declare class FileApprovalAskAuditStore implements ApprovalAskAuditSink,
      * 没有有序关停的证据,就不说它是有序关停。判据读的是构造时冻结的前世账本 ⇒ 同一份账本跨几次启动恒得同一个词。
      */
     causeFor(approvalId: string): HolderGoneCause;
-    /** S-929 收敛行的成因注(判据见头注「收敛行的 `cause`」):组的最后一个事件行之后、收敛行(若已收敛)之前,有本 taskId 的
+    /** [ref] 收敛行的成因注(判据见头注「收敛行的 `cause`」):组的最后一个事件行之后、收敛行(若已收敛)之前,有本 taskId 的
      *  有序关停记号 ⇒ `shutdown_before_park`;否则 `crashed_before_park`。 */
     private causeOf;
     private projectRow;

package/dist/approval-ask-machine.d.ts

@@ -40,13 +40,13 @@ export type AskIdentityRequest = Pick<AskRequest, "toolCallId" | "classes"> & {
 };
 /** ask_id = sha256('ask' ⊕ sourceTaskId ⊕ runId ⊕ toolCallId ⊕ legKey ⊕ parentToolCallId ⊕ 类集规范形).slice(0,64)。
  *  确定性:同参数元组(含重试/failover/闭包再入)永远派生同一个 id——这是 ensureAsk 幂等 upsert 成立的前提;
- *  同调用不同类集 ⇒ 不同 id(S-944)。 */
+ *  同调用不同类集 ⇒ 不同 id([ref])。 */
 export declare function deriveAskId(sourceTaskId: string, runId: string, legKey: string, request: AskIdentityRequest): string;
 /** batch_id = sha256('batch' ⊕ sourceTaskId ⊕ runId ⊕ legKey).slice(0,64)。同一 (sourceTaskId, runId,
  *  legKey) 恒派生同一批——批 = 同一决策点的兄弟 ask 集合,故不掺 toolCallId。 */
 export declare function deriveBatchId(sourceTaskId: string, runId: string, legKey: string): string;
 /**
- * 🔴 S-689 codex R1-F1:**单 ask 批** —— batch_id = sha256('ask-batch' ⊕ askId).slice(0,64)。
+ * 🔴 [ref] codex R1-F1:**单 ask 批** —— batch_id = sha256('ask-batch' ⊕ askId).slice(0,64)。
  *
  * 批是 **park 路由的单位**:窗到期赢家把整批转投递面(OPEN → ROUTING_UNBOUND)、兄弟连坐 VOID,core 随后 park,
  * 这条腿就此结束 —— 所以「整腿一批」成立。不走 park 路由的部署(`UNATTENDED_APPROVAL_POLICY=deny`)上这个前提