@sema-agent/settings-schema 11.3.0 → 12.0.0

package/CHANGELOG.md

@@ -6,6 +6,60 @@
 > `@sema-agent/registry-core`(更早还曾是 `@sema-ai/registry-core`)。本档 `0.19.0` 以下各节里的
 > 包名是**历史记录**,如实保留不追改。
 
+## 12.0.0 — 2026-10-12 — 角色词随引擎收缩(`ModelRole` 8 → 6,一次性迁移 SS-M8)· 写失败按 errno 落点分句 · `config.d` 每份文档同一只文本判 · 扣名条目的可比记号 `identity.token`(major)
+
+> 本节一处硬破坏(角色词表收缩,持久面走一次性迁移 SS-M8)外加三件:命令行写失败按落点分句、`config.d` 每份文档同一只文本判(`remote-exec.json` 非对象不再被 `migrate`
+> 当成无事可做)、扣名条目带可比记号(新导出 `withheldNameToken`,additive)。车道表的租户依据列 `tenantSeparationBasis` 11.0.0 起已是数据,本版无改动。
+> 消费方:server 与引擎 core 7.49.0 同批提货(读点见各条);web-admin 的角色编辑面读 `ModelRole.options`,随表收缩、零改动。版号日期与节标题由发版方写。
+
+### BREAKING:`ModelRole` 收成 6 词 —— 删 `team` / `synthesize`(随引擎 core 7.49.0)
+
+- **删什么**:`ModelRole` = `default` / `summarize` / `subagent` / `verifier` / `classifier` / `consolidate`;`team` / `synthesize` 直接删,零别名、零双读。
+  `ROSTER_PRIMARY_ROLES` = `["default"]`:roster 的 `primaryModel` 标记只派生 `roles.default`(`ROSTER_CHEAP_ROLES` 不变)。`advisor` 本包从未收。
+- **谁会红**:把 `"team"` / `"synthesize"` 当 `ModelRole` 写的代码 tsc 红;存着 `roles.team` / `roles.synthesize`(`models.roles` 或任一 `rosters[].roles`)的文档
+  在迁移之前到达判官 —— 写侧拒;读侧丢那一条角色(models 里只剩它时整域降级到缺省;rosters 是闸域,整个 scope 读不出)—— 拒句点名一次性迁移 SS-M8。
+- **怎么办**:起服 / 提货前跑 SS-M8(函数 `migrateStoredDocuments`,或 `npx @sema-agent/settings-schema migrate <config.d directory>`),把读 `team` / `synthesize`
+  角色的地方改成读 `default` 或删掉。
+
+| 迁移 | 改写什么 | 收据 | 删码之后谁接住 |
+|---|---|---|---|
+| SS-M8 | `models.roles` 与每个 `rosters[].roles` 上的 `team` / `synthesize` 键删掉(值不论);别的角色与别的键原样 | 逐坐标一张 `dropped-inert`(`roles.team` / `rosters.<i>.roles.synthesize` …);再跑零收据 | 退役角色词墓碑(永久):残留的键读写两面拒 |
+
+窗与删法照例只登记在 `ONE_TIME_MIGRATIONS`。收据的迁移 id 闭集多一个 `SS-M8`(`ONE_TIME_MIGRATION_IDS`)。
+- **谁要改**:server 按 `ROSTER_PRIMARY_ROLES` 给每个词写角色的那一处随表只剩 `default`;读 `team` / `synthesize` 角色的消费点(团队 / 合议 / 协作类能力)改读 `default`
+  或随引擎退役;起服对本地 `config.d` 的迁移与提货前对存量文档跑一次 SS-M8。
+
+### 行为修复:命令行写失败按 errno 落点分句
+
+`migrate` 写回阶段写盘失败以前一句话包打天下:「cannot write <文件>: <Node 的错误句> … fix the cause and re-run」—— 目录不可写时点名的却是文件(Node 句子里是临时文件的路径),
+而可写目录里的只读文件照常迁;「fix the cause」也没说是哪个。现在原子写器按失败的那一步出句子,句尾是对应出路:
+- 临时文件建不出(目录不可写:`EACCES` / `EPERM` / `EROFS` / `ENOENT`)⇒ `cannot write into directory <dir> (<errno>): make the directory writable`;
+- `rename` 被拒(`EACCES` / `EPERM`:不可变标志、粘滞目录里别人的文件)⇒ `cannot replace <file> (<errno>): make the file replaceable — …`;
+- 别的 errno(磁盘满、I/O 错 …)⇒ 同两种开头,句尾是 Node 自己的句子。
+命令行 stderr 一行 = `settings-schema: <那一句> — files written before it keep their migrated form; re-run once that is fixed`,rc 2 不变。
+库写口(`writeDomainFile` / `writeRemoteExec` / 调度店写口)抛的是同一句的错误:`code` 照抄底层 errno、原错误在 `cause`(按 `code` 分支的调用方不受影响)。
+
+### 行为修复:`config.d` 每份文档同一只文本判 —— `remote-exec.json` 非对象不再被 `migrate` 当成「无事可做」
+
+同一条 `migrate`,`models.json` 写成 `[]` ⇒ rc 2,`remote-exec.json` 写成 `[]` / `null` / `5` / `"x"` / `true` ⇒ noop rc 0、文件不动(它走的是另一只只拒空与坏 JSON 的文本判)。
+现在 `config.d` 里每份文档(域文档、退役域文档、`remote-exec.json`)过同一只文本判,三种坏形每种一句、点名 `config.d/<名>.json` 与形,句尾出路按文档类:
+- 空 / 纯空白 ⇒ `config.d/<名>.json is empty/whitespace — <出路>`;坏 JSON ⇒ `invalid JSON in config.d/<名>.json — <出路>`;不是对象 ⇒ `config.d/<名>.json must be a JSON object (got <形>) — <出路>`;
+- 出路:域 ⇒ `delete it for the domain default, or write a valid object`;`remote-exec` ⇒ `delete it for the host default, or write a valid remoteExec spec`。
+`FileConfigStore` / `readBundle` / `loadRemoteExec` / 命令行读同一只。措辞随之归一的两处:域文档的坏 JSON 句补上出路;非对象句「delete the file」改成「delete it」(与空文件句同)。
+`loadRemoteExec` 的三句改点名 `config.d/remote-exec.json`(不再是绝对路径),非对象改为上面那句(以前是联合判的 zod 句)—— 抛不抛都不变。
+- **订正 11.3.0 节**:那一节「行为变(命令行)」第二句说「`remote-exec.json` 是空 / 坏 JSON 时 … ⇒ 读不进 rc 2」—— 在 11.3.0 上只对空与坏 JSON 成立,
+  非对象(数组 / `null` / 数 / 串 / 布尔)仍是 noop rc 0。从本版起五种形一律 rc 2,那句话才完整为真。
+
+### 新导出:`withheldNameToken` —— 扣名条目带可比记号 `identity.token`(additive)
+
+被丢条目的名不能原样出门(秘密形 / 超长 / 字符集外)时,身份以前只带 `nameWithheld: true`:两条扣名行在消费方眼里一模一样,「请求点名的那个模型是不是这条坏行」也无从比对。
+现在扣名的同时带 `token` = `withheld:` + SHA-256(域分隔前缀 + 原名的 JSON 串形 —— 逐个 UTF-16 码元保留,孤立代理项不会与 U+FFFD 撞成同一输入)的前 12 个十六进制位 ——
+稳定(同名恒同记号)、不可逆、原名一个字节都不出门;
+`DroppedEntryIdentity` 加可选键 `token`(与 `nameWithheld` 同在同缺)。唯一铸法 `withheldNameToken(name)`(主桶与 `./config-fns` 各 +1)。
+身份只回答「丢的是谁」:在场与否是消费方按原文判的事(注释里「没有名的行不是在场条目」一句删去,与消费方更严的读法一致)。
+一致性语料里带扣名身份的 6 条 case,金样随之多 `token` 一键。
+- **谁要改**:server 读被丢条目身份的那一处,对请求里显式点名的模型调 `withheldNameToken` 与扣名行的 `token` 比对 —— 命中即「点名的是一条坏行」(而不是「未知模型」);不另写摘要。
+
 ## 11.3.0 — 2026-10-11 — 六件 additive:运行期成员表三张(AUTONOMY_MODES / COMMAND_DECISIONS / PROMPT_SLOTS)· 项目登记扩形(goal / contextItems / archivedAt / icon / color,displayName 上界 200)+ PATCH 形 · 命令行环境错一臂(I/O 错 rc 2 一句点名路径)· 一次性迁移 SS-M7 走到 remote-exec.json · 每条自铸 custom issue 带结构化句子(QuotedIssueParams)· hookMatcherForm(minor:新导出主桶 19 / hooks 2 / remote-exec 1 / node 1 型,零删零改名)
 
 > 本节六件,全部 additive(零删导出、零改名;minor):运行期成员表三张 · 项目登记扩形 + PATCH 形 · 命令行环境错一臂 · 一次性迁移 SS-M7 走到 `remote-exec.json` ·

package/conformance/VERSION

@@ -1 +1 @@
-11.3.0
+12.0.0

package/conformance/cases/c40-s712-identity-only-what-reads-out/expected.json

@@ -80,7 +80,8 @@
         "domain": "models",
         "identity": {
           "id": "withheld-id",
-          "nameWithheld": true
+          "nameWithheld": true,
+          "token": "withheld:5c1dac79e895"
         },
         "kind": "entry-dropped",
         "path": [
@@ -107,7 +108,8 @@
         "domain": "models",
         "identity": {
           "id": "short-bearer-id",
-          "nameWithheld": true
+          "nameWithheld": true,
+          "token": "withheld:8d196a0cf81a"
         },
         "kind": "entry-dropped",
         "path": [
@@ -120,7 +122,8 @@
         "domain": "models",
         "identity": {
           "id": "pem-id",
-          "nameWithheld": true
+          "nameWithheld": true,
+          "token": "withheld:ffe22d022741"
         },
         "kind": "entry-dropped",
         "path": [

package/conformance/cases/c41-s792-encoded-pem-identity/expected.json

@@ -93,7 +93,8 @@
         "domain": "models",
         "identity": {
           "id": "in-charset-secret-name-id",
-          "nameWithheld": true
+          "nameWithheld": true,
+          "token": "withheld:e4c2e8ebcfc8"
         },
         "kind": "entry-dropped",
         "path": [
@@ -106,7 +107,8 @@
         "domain": "models",
         "identity": {
           "id": "one-dot-jwt-name-id",
-          "nameWithheld": true
+          "nameWithheld": true,
+          "token": "withheld:c30e4531b782"
         },
         "kind": "entry-dropped",
         "path": [

package/conformance/cases/c45-s792-identity-bounds-and-decode-depth/expected.json

@@ -112,7 +112,8 @@
         "domain": "models",
         "identity": {
           "id": "cap-257-id",
-          "nameWithheld": true
+          "nameWithheld": true,
+          "token": "withheld:389e8c0da200"
         },
         "kind": "entry-dropped",
         "path": [
@@ -174,7 +175,8 @@
       {
         "domain": "hosts",
         "identity": {
-          "nameWithheld": true
+          "nameWithheld": true,
+          "token": "withheld:56d720b6a52f"
         },
         "kind": "entry-dropped",
         "path": [

package/conformance/cases/c46-s811-host-name-url-userinfo-withheld/expected.json

@@ -70,7 +70,8 @@
       {
         "domain": "hosts",
         "identity": {
-          "nameWithheld": true
+          "nameWithheld": true,
+          "token": "withheld:e2bdf1a6eb87"
         },
         "kind": "entry-dropped",
         "path": [

package/conformance/cases/cli01-model-name-nfc-vs-nfd/expected.json

@@ -76,7 +76,8 @@
         "domain": "models",
         "identity": {
           "idWithheld": true,
-          "nameWithheld": true
+          "nameWithheld": true,
+          "token": "withheld:b2fca8da7930"
         },
         "kind": "entry-dropped",
         "path": [
@@ -89,7 +90,8 @@
         "domain": "models",
         "identity": {
           "idWithheld": true,
-          "nameWithheld": true
+          "nameWithheld": true,
+          "token": "withheld:946256d8ea6b"
         },
         "kind": "entry-dropped",
         "path": [

package/conformance/cases/cli02-control-and-zero-width-chars/expected.json

@@ -89,7 +89,8 @@
         "domain": "models",
         "identity": {
           "idWithheld": true,
-          "nameWithheld": true
+          "nameWithheld": true,
+          "token": "withheld:f3b4942da5cd"
         },
         "kind": "entry-dropped",
         "path": [
@@ -102,7 +103,8 @@
         "domain": "models",
         "identity": {
           "idWithheld": true,
-          "nameWithheld": true
+          "nameWithheld": true,
+          "token": "withheld:2469fd783cfd"
         },
         "kind": "entry-dropped",
         "path": [

package/dist/atomic-write.js

@@ -19,10 +19,16 @@
  * (不在链接位置建普通文件,也不替链接建它指向的文件);成环的链接由 `realpath` 抛 `ELOOP`。目标不存在 ⇒ 新建(没有链接可言;经符号链接的目录写新文件时,文件落在真目录里)。
  * 「链接 ⇒ 真文件、悬空 ⇒ 响亮抛」这一只判法是 {@link resolveSymlinkTarget}:目录迁移的读口(`./config-dir-io`)读目录 / 读文件前也问它,
  * 悬空链接在读阶段与写阶段是**同一句**({@link danglingSymlinkSentence})。
+ *
+ * ## 写失败(12.0.0)
+ * 两步各一句({@link AtomicWriteFailure},句子在 `./write-failure`):临时文件建不出 ⇒ 「cannot write into directory <dir> (<errno>): …」(点名目录 —— 目录不可写时
+ * 文件本身没错);`rename` 失败 ⇒ 「cannot replace <file> (<errno>): …」(点名真文件)。认得的 errno 给对应出路,别的给 Node 自己的句子;`code` / `cause` 留着。
+ * 可写目录里的只读文件照常写得进(`rename` 换的是目录项)。
  */
 import { randomBytes } from "node:crypto";
 import { chmodSync, lstatSync, readlinkSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import path from "node:path";
+import { AtomicWriteFailure } from "./write-failure.js";
 /** 按文档类的模式表(闭集)。 */
 export const ATOMIC_FILE_CLASSES = {
     "config-document": { newMode: 0o644, existing: "keep" },
@@ -79,11 +85,14 @@ export function writeFileAtomic(target, text, kind) {
             throw new Error(`writeFileAtomic: unhandled existing-file rule ${String(unhandled)}`);
         }
     }
-    const tmp = path.join(path.dirname(real), `.${path.basename(real)}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`);
+    const dir = path.dirname(real);
+    const tmp = path.join(dir, `.${path.basename(real)}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`);
+    let step = "create";
     try {
         writeFileSync(tmp, text, { encoding: "utf8", mode: kept ?? spec.newMode });
         if (kept !== undefined)
             chmodSync(tmp, kept); // a kept mode is restored exactly (the creation mode above went through the umask)
+        step = "replace";
         renameSync(tmp, real);
     }
     catch (e) {
@@ -93,6 +102,6 @@ export function writeFileAtomic(target, text, kind) {
         catch {
             /* 临时文件没建成:没什么可清 */
         }
-        throw e;
+        throw new AtomicWriteFailure(step, dir, real, e); // 12.0.0: the sentence names the step that failed and its way out (`./write-failure`)
     }
 }

package/dist/cli.d.ts

@@ -15,8 +15,9 @@
  * 零收据 = noop 退出 0 —— 新部署的空 `config.d` 是合法态,「没有东西可迁」不是「指错目录」(搬空之后再跑同一目录也因此幂等)。
  *
  * 退出码:0 = 已写回 / 无事可做(目录里有域文档只是没有要改的,或目录真空);1 = 有迁不了的坐标(收据 `refused`)**或**要写回的域文档整域读不进(整域终判,见 `migrateConfigDirectory`),**一字不写**;
- * 2 = 用法错,或**环境错**(读目录 / 读文件 / 写盘 / 删文件的 I/O 错:权限、磁盘、悬空符号链接 …;stdout 空、stderr 一行点名路径与错误(errno 码在 Node 的错误句里),不打栈 ——
- * rc 1 是「拒迁」的约定码,不许被一个权限错冒充),或某个域文件是坏文件(空 / 纯空白 / 坏 JSON / 不是 JSON 对象 —— 与 `FileConfigStore` 同一只判、同一句),**或目录里有条目却没有一个是域文档**
+ * 2 = 用法错,或**环境错**(读目录 / 读文件 / 写盘 / 删文件的 I/O 错:权限、磁盘、悬空符号链接 …;stdout 空、stderr 一行点名路径与 errno,不打栈;写盘失败按落点分句 ——
+ * 目录建不出文件 ⇒ 点名目录、目标换不掉 ⇒ 点名文件,句尾是对应出路(原子写器的句子,`./write-failure`)——
+ * rc 1 是「拒迁」的约定码,不许被一个权限错冒充),或覆盖面内某份文档(域文档或 `remote-exec.json`)是坏文件(空 / 纯空白 / 坏 JSON / 不是 JSON 对象 —— 与 `FileConfigStore` / `loadRemoteExec` 同一只判、同一句),**或目录里有条目却没有一个是域文档**
  * (多半是填错了目录:要的是 `config.d` 目录本身;`<目录>/config.d` 在场时句子直接点它)(此时 stdout 为空);3 = `--check` 且会有改动、整域判得过(不写)。`--check` 与真跑过同一只判定,只在
  * 「有改动、且整域判得过」那一支上分开(pending vs applied)—— 整域会被拒的目录 `--check` 也报 refused / rc 1。
  *

package/dist/cli.js

@@ -15,8 +15,9 @@
  * 零收据 = noop 退出 0 —— 新部署的空 `config.d` 是合法态,「没有东西可迁」不是「指错目录」(搬空之后再跑同一目录也因此幂等)。
  *
  * 退出码:0 = 已写回 / 无事可做(目录里有域文档只是没有要改的,或目录真空);1 = 有迁不了的坐标(收据 `refused`)**或**要写回的域文档整域读不进(整域终判,见 `migrateConfigDirectory`),**一字不写**;
- * 2 = 用法错,或**环境错**(读目录 / 读文件 / 写盘 / 删文件的 I/O 错:权限、磁盘、悬空符号链接 …;stdout 空、stderr 一行点名路径与错误(errno 码在 Node 的错误句里),不打栈 ——
- * rc 1 是「拒迁」的约定码,不许被一个权限错冒充),或某个域文件是坏文件(空 / 纯空白 / 坏 JSON / 不是 JSON 对象 —— 与 `FileConfigStore` 同一只判、同一句),**或目录里有条目却没有一个是域文档**
+ * 2 = 用法错,或**环境错**(读目录 / 读文件 / 写盘 / 删文件的 I/O 错:权限、磁盘、悬空符号链接 …;stdout 空、stderr 一行点名路径与 errno,不打栈;写盘失败按落点分句 ——
+ * 目录建不出文件 ⇒ 点名目录、目标换不掉 ⇒ 点名文件,句尾是对应出路(原子写器的句子,`./write-failure`)——
+ * rc 1 是「拒迁」的约定码,不许被一个权限错冒充),或覆盖面内某份文档(域文档或 `remote-exec.json`)是坏文件(空 / 纯空白 / 坏 JSON / 不是 JSON 对象 —— 与 `FileConfigStore` / `loadRemoteExec` 同一只判、同一句),**或目录里有条目却没有一个是域文档**
  * (多半是填错了目录:要的是 `config.d` 目录本身;`<目录>/config.d` 在场时句子直接点它)(此时 stdout 为空);3 = `--check` 且会有改动、整域判得过(不写)。`--check` 与真跑过同一只判定,只在
  * 「有改动、且整域判得过」那一支上分开(pending vs applied)—— 整域会被拒的目录 `--check` 也报 refused / rc 1。
  *
@@ -30,6 +31,7 @@
 import { reportReceipt, joinDirPath, migrateConfigDirectory } from "./config-dir-migration.js";
 import { MIGRATE_COMMAND_TEMPLATE, migrateCommandFor } from "./retired-form.js";
 import { REMOTE_EXEC_DOCUMENT } from "./remote-exec.js";
+import { AtomicWriteFailure } from "./write-failure.js";
 import { DOMAINS, RETIRED_DOMAINS } from "./types.js";
 /** 命令行的覆盖面:全部配置域、retired 域(便携与否不论 —— 离线的 `workers.json` 一样迁)与 `remote-exec.json`。 */
 export const COVERED_DOCUMENTS = [...DOMAINS, ...Object.keys(RETIRED_DOMAINS), REMOTE_EXEC_DOCUMENT];
@@ -77,7 +79,8 @@ class EnvironmentFailure extends Error {
 }
 const oneLine = (text) => text.replace(/\s*\n\s*/g, " ");
 const messageOf = (err) => oneLine(err instanceof Error ? err.message : String(err));
-/** 把注入的写口包一层:写盘 / 删文件抛 ⇒ {@link EnvironmentFailure},句子点名**要写的那份文件**(原子写器的错误句里是临时文件的路径)与原错误句。
+/** 把注入的写口包一层:写盘 / 删文件抛 ⇒ {@link EnvironmentFailure}。本包的原子写器抛的是按失败那一步分好的句子({@link AtomicWriteFailure}:目录建不出文件 ⇒
+ *  点名目录,目标换不掉 ⇒ 点名文件,句尾是对应出路)—— 原样用;别的写口(注入的替身)抛的错 ⇒ 点名**要写的那份文件**与原错误句。
  *  读口不包:读目录 / 读文件错由 `migrateConfigDirectory` 自己收成 `unreadable`(同为 rc 2)。 */
 function withEnvironmentArm(io) {
     return {
@@ -88,7 +91,7 @@ function withEnvironmentArm(io) {
                 await io.writeFileAtomic(path, text);
             }
             catch (err) {
-                throw new EnvironmentFailure(`cannot write ${path}: ${messageOf(err)}`, { cause: err });
+                throw new EnvironmentFailure(err instanceof AtomicWriteFailure ? err.message : `cannot write ${path}: ${messageOf(err)}`, { cause: err });
             }
         },
         removeFile: async (path) => {
@@ -125,7 +128,7 @@ export async function runSettingsSchemaCli(argv, io) {
         if (!(err instanceof EnvironmentFailure))
             throw err;
         // 写回阶段断在这里:之前写完的文档已在新形上,再跑一次幂等收尾(迁移只认形)。stdout 不出结论行 —— 没有 `outcome=applied`。
-        io.stderr(`settings-schema: ${err.message} — files written before it keep their migrated form; fix the cause and re-run\n`);
+        io.stderr(`settings-schema: ${err.message} — files written before it keep their migrated form; re-run once that is fixed\n`);
         return 2;
     }
     switch (m.kind) {

package/dist/config-d-file.d.ts

@@ -1,20 +1,19 @@
-import { RemoteExecSpec } from "./remote-exec.js";
+import { REMOTE_EXEC_DOCUMENT, RemoteExecSpec } from "./remote-exec.js";
 import { type DomainName, type RetiredDomainName } from "./types.js";
 /** 一份 `config.d` 文档写盘的**文本形** —— 两格缩进的 JSON 加一个换行。写域文件(`writeDomainFile`)、写 `remote-exec.json`(`writeRemoteExec`)与目录迁移写回
  *  都用这一只(此前三处各写一遍同一行),于是迁移写回的文件与编辑器写出的同一份文件逐字节同形。 */
 export declare function configDDocumentText(value: unknown): string;
-/** `config.d/remote-exec.json` 在场时的**文本** → 它的 JSON 值(纯判,零 I/O)—— `loadRemoteExec` 与目录迁移读同一只、同一句(从 `loadRemoteExec` 里搬出)。
- *  空 / 纯空白(半写、截断 —— 不是「用默认」:默认车道要的是文件**缺席**)、坏 JSON ⇒ 抛,句子点名 `filePath`、不回显原文。值的形由
- *  {@link parseRemoteExecDocument} 判(不是对象也归它拒)。 */
-export declare function judgeRemoteExecText(filePath: string, text: string): unknown;
 /** 判一份 remote-exec 文档的值(`RemoteExecSpec`),错误**脱敏**(zod 会回显出错的值 —— 粘错位置的密钥不许随抛出的错走);反射访问抛(恶意 getter /
  *  Proxy)⇒ 定句。`loadRemoteExec` / `writeRemoteExec` 与目录迁移的整文档终判调同一只。 */
 export declare function parseRemoteExecDocument(raw: unknown): RemoteExecSpec;
 /** `<root>/config.d/<名>.json` 的路径 —— 名字的判也在这里(**一处**):不是配置域也不是 retired 域 ⇒ 拒(不拿用户给的名拼路径,防 `../` 穿越)。 */
 export declare function configDPath(root: string, name: string): string;
+/** `config.d` 里能放的文档名:配置域、retired 域、`remote-exec`(`config.d/remote-exec.json`,不是配置域)。 */
+export type ConfigDDocumentName = DomainName | RetiredDomainName | typeof REMOTE_EXEC_DOCUMENT;
 /** 一个 `config.d/<名>.json` 在场时的**文本** → 它的值(纯判,零 I/O;见文件头的律):一个 JSON 对象 ⇒ 它;空 / 纯空白、坏 JSON、
- *  不是对象 ⇒ 抛。读盘的入口(`readConfigDFile`)与自己读文本的命令行(`migrate`)都过它,四种坏形一句话。 */
-export declare function judgeConfigDText(name: DomainName | RetiredDomainName, text: string): Record<string, unknown>;
+ *  不是对象 ⇒ 抛,每种一句(点名文件与形,句尾 {@link documentWayOut})。读盘的入口(`readConfigDFile`、`loadRemoteExec`)与自己读文本的命令行(`migrate`)
+ *  都过它 —— 一种坏形一句话,不论是哪份文档。 */
+export declare function judgeConfigDText(name: ConfigDDocumentName, text: string): Record<string, unknown>;
 /** 读一个 `config.d/<名>.json`:不存在(ENOENT)⇒ `undefined`;在场 ⇒ {@link judgeConfigDText}。 */
 export declare function readConfigDFile(root: string, name: DomainName | RetiredDomainName): Promise<Record<string, unknown> | undefined>;
 /**

package/dist/config-d-file.js

@@ -1,36 +1,23 @@
 /**
- * 包内私有(不进主桶、不进 exports 表):**一只** `config.d/<名>.json` 文件读法 —— `FileConfigStore`、`readBundle` 与命令行 `migrate` 读同一个目录,
- * 同一种文件形同一个答案、同一句话。分两只:纯判 `judgeConfigDText`(文本 → 值 | 抛,零 I/O;命令行自己读文本,只调它)与读盘的
- * `readConfigDFile`(调它);路径与名字的判只在 `configDPath`。
+ * 包内私有(不进主桶、不进 exports 表):**一只** `config.d/<名>.json` 文件读法 —— `FileConfigStore`、`readBundle`、`loadRemoteExec` 与命令行 `migrate` 读同一个目录,
+ * 同一种文件形同一个答案、同一句话(12.0.0 起 `remote-exec.json` 也是这一只;此前它有自己的一只文本判,只拒空与坏 JSON,非对象在命令行上被当成「无事可做」)。
+ * 分两只:纯判 `judgeConfigDText`(文本 → 值 | 抛,零 I/O;命令行与 `loadRemoteExec` 自己读文本,只调它)与读盘的 `readConfigDFile`(调它);路径与名字的判只在 `configDPath`。
  *
  * 律:**只有不存在(ENOENT)= 缺席**(`undefined`);在场的文件必须是一个 JSON 对象。空 / 纯空白(半写、截断)、坏 JSON、解析出来不是对象
  * (`null` / 数组 / 数 / 串 / 布尔)一律是**坏文件** ⇒ 抛(fail-closed:把一个被截断的文件读成缺席,就是静默丢掉那一个域 —— 例:截断的
- * governance.json 丢掉它的护栏)。拒句只点名文件与形,从不回显文件原文。
+ * governance.json 丢掉它的护栏;截断的 remote-exec.json 把隔离车道降成宿主车道)。三种坏形每种一句,点名文件与形、句尾出路按文档类
+ * ({@link documentWayOut}),从不回显文件原文。
  */
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { refuseRetiredDomain, sanitizeZodError } from "./config-fns.js";
-import { RemoteExecSpec } from "./remote-exec.js";
+import { REMOTE_EXEC_DOCUMENT, RemoteExecSpec } from "./remote-exec.js";
 import { RETIRED_DOMAINS, isDomainName, isRetiredDomainName } from "./types.js";
 /** 一份 `config.d` 文档写盘的**文本形** —— 两格缩进的 JSON 加一个换行。写域文件(`writeDomainFile`)、写 `remote-exec.json`(`writeRemoteExec`)与目录迁移写回
  *  都用这一只(此前三处各写一遍同一行),于是迁移写回的文件与编辑器写出的同一份文件逐字节同形。 */
 export function configDDocumentText(value) {
     return `${JSON.stringify(value, null, 2)}\n`;
 }
-/** `config.d/remote-exec.json` 在场时的**文本** → 它的 JSON 值(纯判,零 I/O)—— `loadRemoteExec` 与目录迁移读同一只、同一句(从 `loadRemoteExec` 里搬出)。
- *  空 / 纯空白(半写、截断 —— 不是「用默认」:默认车道要的是文件**缺席**)、坏 JSON ⇒ 抛,句子点名 `filePath`、不回显原文。值的形由
- *  {@link parseRemoteExecDocument} 判(不是对象也归它拒)。 */
-export function judgeRemoteExecText(filePath, text) {
-    const trimmed = text.trim();
-    if (!trimmed)
-        throw new Error(`${filePath} is empty/corrupt — delete it for the host default, or write a valid remoteExec spec`);
-    try {
-        return JSON.parse(trimmed); // sanitized: don't let a SyntaxError echo the raw (possibly secret-bearing) file text
-    }
-    catch {
-        throw new Error(`${filePath} — invalid JSON (delete it for the host default, or write a valid remoteExec spec)`);
-    }
-}
 /** 判一份 remote-exec 文档的值(`RemoteExecSpec`),错误**脱敏**(zod 会回显出错的值 —— 粘错位置的密钥不许随抛出的错走);反射访问抛(恶意 getter /
  *  Proxy)⇒ 定句。`loadRemoteExec` / `writeRemoteExec` 与目录迁移的整文档终判调同一只。 */
 export function parseRemoteExecDocument(raw) {
@@ -51,22 +38,28 @@ export function configDPath(root, name) {
         throw new Error(`"${name}" is not a config domain — refusing to build a config.d path from it (no traversal)`);
     return path.join(root, "config.d", `${name}.json`);
 }
+/** 坏文件句的出路(按文档类):删掉它 = 回到缺席时的缺省(域 ⇒ 域缺省;`remote-exec` ⇒ 宿主车道缺省),或写成那一类的合法文档。 */
+function documentWayOut(name) {
+    return name === REMOTE_EXEC_DOCUMENT ? "delete it for the host default, or write a valid remoteExec spec" : "delete it for the domain default, or write a valid object";
+}
 /** 一个 `config.d/<名>.json` 在场时的**文本** → 它的值(纯判,零 I/O;见文件头的律):一个 JSON 对象 ⇒ 它;空 / 纯空白、坏 JSON、
- *  不是对象 ⇒ 抛。读盘的入口(`readConfigDFile`)与自己读文本的命令行(`migrate`)都过它,四种坏形一句话。 */
+ *  不是对象 ⇒ 抛,每种一句(点名文件与形,句尾 {@link documentWayOut})。读盘的入口(`readConfigDFile`、`loadRemoteExec`)与自己读文本的命令行(`migrate`)
+ *  都过它 —— 一种坏形一句话,不论是哪份文档。 */
 export function judgeConfigDText(name, text) {
+    const file = `config.d/${name}.json`;
     const trimmed = text.trim();
     if (!trimmed)
-        throw new Error(`config.d/${name}.json is empty/whitespace — delete it for the domain default, or write a valid object`);
+        throw new Error(`${file} is empty/whitespace — ${documentWayOut(name)}`);
     let parsed;
     try {
         parsed = JSON.parse(trimmed);
     }
     catch {
-        throw new Error(`invalid JSON in config.d/${name}.json`); // sanitized: never echo the raw file text into the error
+        throw new Error(`invalid JSON in ${file} — ${documentWayOut(name)}`); // sanitized: never echo the raw file text into the error
     }
     if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
         const kind = parsed === null ? "null" : Array.isArray(parsed) ? "array" : typeof parsed;
-        throw new Error(`config.d/${name}.json must be a JSON object (got ${kind}) — delete the file for the domain default, or write a valid object`);
+        throw new Error(`${file} must be a JSON object (got ${kind}) — ${documentWayOut(name)}`);
     }
     return parsed;
 }

package/dist/config-dir-migration.d.ts

@@ -1,6 +1,5 @@
+import { type ConfigDDocumentName } from "./config-d-file.js";
 import { type MigrationReceipt } from "./one-time-migrations.js";
-import { REMOTE_EXEC_DOCUMENT } from "./remote-exec.js";
-import { type DomainName, type RetiredDomainName } from "./types.js";
 /** 注入的 I/O(本模块不碰 `node:fs`)。`writeFileAtomic` 必须原子(写临时文件再改名):半写的域文档比旧文档更糟。 */
 export interface ConfigDirectoryIo {
     readDir(path: string): Promise<string[]>;
@@ -50,8 +49,8 @@ export interface MigrateConfigDirectoryOptions {
     /** 只判、不写:有改动且整域判得过 ⇒ `pending`。默认 `false`。 */
     readonly check?: boolean;
 }
-/** 目录迁移能读写的文档名:配置域、retired 域、`remote-exec`(`config.d/remote-exec.json`)。 */
-export type ConfigDirectoryDocument = DomainName | RetiredDomainName | typeof REMOTE_EXEC_DOCUMENT;
+/** 目录迁移能读写的文档名:配置域、retired 域、`remote-exec`(`config.d/remote-exec.json`)—— 就是 `config.d` 里能放的文档名。 */
+export type ConfigDirectoryDocument = ConfigDDocumentName;
 /** 目录加文件名(目录尾部的分隔符折掉)。包内私有(不进 `./node`)。 */
 export declare const joinDirPath: (dir: string, name: string) => string;
 type RefusedReceipt = Extract<MigrationReceipt, {

package/dist/config-dir-migration.js

@@ -23,16 +23,12 @@
  */
 import { z } from "zod";
 import { formatConfigPath, parseDomain } from "./config-fns.js";
-import { configDDocumentText, judgeConfigDText, judgeRemoteExecText, parseRemoteExecDocument } from "./config-d-file.js";
+import { configDDocumentText, judgeConfigDText, parseRemoteExecDocument } from "./config-d-file.js";
 import { migrateStoredDocuments } from "./one-time-migrations.js";
 import { REMOTE_EXEC_DOCUMENT } from "./remote-exec.js";
 import { RUNTIME_LIFT_TARGETS } from "./runtime-lift-targets.js";
 import { isDomainName, isRetiredDomainName } from "./types.js";
 const isConfigDirectoryDocument = (name) => isDomainName(name) || isRetiredDomainName(name) || name === REMOTE_EXEC_DOCUMENT;
-/** 一份文档在场时的文本 → 值:域 / retired 域过 `judgeConfigDText`(与 `FileConfigStore` 同一只),`remote-exec` 过 `judgeRemoteExecText`(与 `loadRemoteExec` 同一只)。 */
-function judgeDocumentText(dir, name, text) {
-    return name === REMOTE_EXEC_DOCUMENT ? judgeRemoteExecText(joinDirPath(dir, `${name}.json`), text) : judgeConfigDText(name, text);
-}
 /** 改过的文档的整文档终判:域过读侧那一只 `parseDomain`,`remote-exec` 过 `loadRemoteExec` 那一只 `parseRemoteExecDocument`;retired 域不终判(它只会被删)。 */
 function judgeWholeDocument(name, doc) {
     if (isDomainName(name))
@@ -130,7 +126,7 @@ export async function migrateConfigDirectory(dir, opts) {
             return { kind: "unreadable", reason: `cannot read ${name}: ${messageOf(err)}` };
         }
         try {
-            docs[base] = judgeDocumentText(dir, base, text); // the one judge per document kind: a domain file's is FileConfigStore's, remote-exec.json's is loadRemoteExec's
+            docs[base] = judgeConfigDText(base, text); // the one config.d text judge (FileConfigStore / loadRemoteExec read with it): empty / bad JSON / not an object ⇒ unreadable
         }
         catch (err) {
             return { kind: "unreadable", reason: messageOf(err) };

package/dist/config-fns.d.ts

@@ -182,8 +182,10 @@ export declare function outgoingPath(p: ConfigPath): ConfigPath;
  *  所以是**不带**而不是打码)。三键都读不出 ⇒ 整个身份缺席(不铸空对象)。
  *
  *  **扣名 ≠ 读不出**(11.0.0,N-4 / S-759):`name` / `id` 是字符串但不能原样出门 ⇒ 身份带 `nameWithheld: true` / `idWithheld: true`;
- *  不是字符串 ⇒ 什么都不带。两种处置对消费方不同:「这一行在场、有名、名被扣下」的启用行仍是一条在场的条目(server 据此铸无名占位,
- *  不走「零启用」捷径),「没有名」的行不是。标记只说「有一个名、没给出」,不说为什么(秘密形 / 超长 / 字符集外是同一个记号)。
+ *  不是字符串 ⇒ 什么都不带。标记只说「有一个名、没给出」,不说为什么(秘密形 / 超长 / 字符集外是同一个记号)。扣下的**名**另带一个可比记号
+ *  `token`(12.0.0,{@link withheldNameToken}):两条扣名行据此可分、消费方拿请求里的名字调同一只就能比对,原名一个字节都不出门。
+ *  身份只回答「丢的是谁」,不回答「这条坏行算不算在场」:一条读不出名字的被丢行照样是文档里的一行,在场与否是消费方按原文判的事
+ *  (例:server 把没写 `enabled: false` 的被丢行一律算在场)。
  *
  *  为什么要带:条目被丢之后它的名字从目录里消失,只给坐标的话,消费方要知道「丢的是谁」只能拿坐标回读
  *  原文档 —— 而它手里那份原文档未必是这一次读到的那份。铸告警的这一层判的就是那条原文,在这里取一次、
@@ -194,6 +196,9 @@ export interface DroppedEntryIdentity {
     enabled?: boolean;
     /** `name` was a string that {@link isDisclosableIdentity} would not let out (11.0.0). Absent with a `name` present or with no string name. */
     nameWithheld?: true;
+    /** The withheld name's comparable token ({@link withheldNameToken}; 12.0.0) — present exactly when `nameWithheld` is. Stable (the same name
+     *  always gives the same token), irreversible, never the name or any part of it. */
+    token?: string;
     /** `id` was a string that {@link isDisclosableIdentity} would not let out (11.0.0). */
     idWithheld?: true;
 }
@@ -251,6 +256,13 @@ export declare function isDisclosableIdentity(v: string): boolean;
  *   ② {@link isDisclosableIdentity}(不是白名单闭形里的标识符,或是秘密形 ⇒ 不出门)。
  *  非字符串 ⇒ false。住在本文件而不是 `./fleet`:`fleet.ts` 被 `types.ts` 引,它再引本文件会成环。 */
 export declare function isReportableRefusalName(name: string): boolean;
+/** 扣下的名的**可比记号**(12.0.0)—— `withheld:` + SHA-256(域分隔前缀 + 原名的 JSON 串形)的前 12 个十六进制位。**唯一**铸法:被丢条目的身份
+ *  ({@link DroppedEntryIdentity}`.token`)由它铸,消费方要问「请求点名的这个名是不是那条扣名行」就对请求里的名调它、比 token —— 不另写一份摘要。
+ *  稳定(同名恒同记号)、不可逆(48 位摘要,秘密形名字本身是高熵串);域分隔前缀让它与别处对同一串算的 SHA-256 指纹对不上。它只区分名字,
+ *  不是 MAC、不防字典猜测:低熵的名(`Basic Chat`)能被猜回来 —— 那类名被扣下是因为字符集外,本就不是秘密。
+ *  摘要输入取 `JSON.stringify(name)`:UTF-8 编码会把孤立代理项换成 U+FFFD(`"\ud800"` / `"\ud801"` / `"\ufffd"` 三个不同的名同一串字节),
+ *  JSON 串形逐个 UTF-16 码元保留(孤立代理项写成转义)—— 不同的名恒是不同的输入。 */
+export declare function withheldNameToken(name: string): string;
 /** 抢救造成的**下标位移表**:数组字段名 → 该字段压缩后每个位置的**原**下标(`kept[j]` = 压缩后第 j 条
  *  在原文档里的下标)。纯数据,无行为。
  *

package/dist/config-fns.js

@@ -18,6 +18,7 @@
 import { z } from "zod";
 import { MODEL_ENTRY_REFUSAL_CODES, ModelRefusalsWire } from "./fleet.js";
 import { carriesUserinfo, secretScanForms } from "./secret-scan.js"; // package-private normalization (both scanners read it) + the userinfo judgement (not in the barrel)
+import { sha256Hex } from "./sha256.js";
 import { unwrapSchema } from "./zod-unwrap.js"; // package-private: the ONE reading of zod's wrapper layers (salvage + the one-time migrations share it)
 import { DOMAIN_SCHEMAS, InfraCostRates, LimitsConfig, PRIVATE_KEY_PEM_HEADER, RETIRED_DOMAINS, SkillsManifestSchema, containsSecretToken, isDomainName, isRetiredDomainName, renderQuotedSentence, retiredDomainSentence } from "./types.js";
 /** Redact secret-shaped tokens from a validation MESSAGE — a zod error echoes the offending value (e.g.
@@ -327,6 +328,17 @@ export function isReportableRefusalName(name) {
     const probe = ModelRefusalsWire.safeParse({ entries: { [name]: MODEL_ENTRY_REFUSAL_CODES[0] } });
     return probe.success && Object.hasOwn(probe.data.entries, name);
 }
+/** {@link withheldNameToken} 的域分隔前缀(摘要输入 = 前缀 + 原名的 JSON 串形)。 */
+const WITHHELD_NAME_TOKEN_DOMAIN = "sema-settings-schema/withheld-name\u0000";
+/** 扣下的名的**可比记号**(12.0.0)—— `withheld:` + SHA-256(域分隔前缀 + 原名的 JSON 串形)的前 12 个十六进制位。**唯一**铸法:被丢条目的身份
+ *  ({@link DroppedEntryIdentity}`.token`)由它铸,消费方要问「请求点名的这个名是不是那条扣名行」就对请求里的名调它、比 token —— 不另写一份摘要。
+ *  稳定(同名恒同记号)、不可逆(48 位摘要,秘密形名字本身是高熵串);域分隔前缀让它与别处对同一串算的 SHA-256 指纹对不上。它只区分名字,
+ *  不是 MAC、不防字典猜测:低熵的名(`Basic Chat`)能被猜回来 —— 那类名被扣下是因为字符集外,本就不是秘密。
+ *  摘要输入取 `JSON.stringify(name)`:UTF-8 编码会把孤立代理项换成 U+FFFD(`"\ud800"` / `"\ud801"` / `"\ufffd"` 三个不同的名同一串字节),
+ *  JSON 串形逐个 UTF-16 码元保留(孤立代理项写成转义)—— 不同的名恒是不同的输入。 */
+export function withheldNameToken(name) {
+    return `withheld:${sha256Hex(`${WITHHELD_NAME_TOKEN_DOMAIN}${JSON.stringify(name)}`).slice(0, 12)}`;
+}
 /** 一条被丢条目原文的身份({@link DroppedEntryIdentity} 的**唯一**读法)。只看纯 JSON 对象的**自有数据
  *  属性**;任何反射/陷阱抛错 ⇒ 当作读不出(身份是诊断面的附件,绝不许把抢救拖下水)。 */
 function readEntryIdentity(entry) {
@@ -341,7 +353,7 @@ function readEntryIdentity(entry) {
         const id = own("id");
         const enabled = own("enabled");
         const identity = {
-            ...(typeof name === "string" ? (isDisclosableIdentity(name) ? { name } : { nameWithheld: true }) : {}),
+            ...(typeof name === "string" ? (isDisclosableIdentity(name) ? { name } : { nameWithheld: true, token: withheldNameToken(name) }) : {}),
             ...(typeof id === "string" ? (isDisclosableIdentity(id) ? { id } : { idWithheld: true }) : {}),
             ...(typeof enabled === "boolean" ? { enabled } : {}),
         };

package/dist/local-load.js

@@ -14,7 +14,7 @@ import { writeFileAtomic } from "./atomic-write.js";
 import { FileConfigStore } from "./file-store.js";
 import { listRequiredEnvNames } from "./file-edit.js";
 import {} from "./config-fns.js";
-import { configDDocumentText, judgeRemoteExecText, parseRemoteExecDocument } from "./config-d-file.js";
+import { configDDocumentText, judgeConfigDText, parseRemoteExecDocument } from "./config-d-file.js";
 import { REMOTE_EXEC_DOCUMENT } from "./remote-exec.js";
 /** The remoteExec file path under a config root (under config.d/, beside the per-domain files). */
 export function remoteExecPath(root) {
@@ -34,9 +34,9 @@ export async function loadRemoteExec(root) {
     }
     // A present-but-empty file is a corruption/half-write, NOT "use the default" — FAIL CLOSED (an empty file
     // silently falling back to the host lane would be an isolation DOWNGRADE if the user meant local-docker).
-    // To get the host default, the file must be ABSENT, not empty. The text judge and the sanitized value judge are the ones the
-    // directory migration reads this file with (`./config-d-file`).
-    return parseRemoteExecDocument(judgeRemoteExecText(remoteExecPath(root), text));
+    // To get the host default, the file must be ABSENT, not empty. The text judge is THE config.d one (empty / bad JSON / not an object, one sentence
+    // each — the same judge FileConfigStore and the directory migration read with); the sanitized value judge is the migration's too (`./config-d-file`).
+    return parseRemoteExecDocument(judgeConfigDText(REMOTE_EXEC_DOCUMENT, text));
 }
 /** Validate + ATOMICALLY write `<root>/config.d/remote-exec.json` (the package's one atomic writer, `./atomic-write`; never a half file). The
  *  client's `config` editor writes the exec backend through this; the engine reads it via loadRemoteExec. */

package/dist/migration-receipt.d.ts

@@ -6,7 +6,7 @@ import type { REMOTE_EXEC_DOCUMENT } from "./remote-exec.js";
 import type { DomainName, RetiredDomainName } from "./types.js";
 /** 本版登记的一次性**数据**迁移 id(闭集;每个 id 在 `ONE_TIME_MIGRATIONS` 登记表里恰一行)。收据只许这些 id —— 同表登记的 wire 删码位
  *  (`WIRE_RETIREMENT_IDS`,`./one-time-migrations`)不改任何存储形,铸不出收据,不在本集。 */
-export declare const ONE_TIME_MIGRATION_IDS: readonly ["SS-M1", "SS-M2", "SS-M3", "SS-M4", "SS-M5", "SS-M6", "SS-M7", "SS-M9"];
+export declare const ONE_TIME_MIGRATION_IDS: readonly ["SS-M1", "SS-M2", "SS-M3", "SS-M4", "SS-M5", "SS-M6", "SS-M7", "SS-M8", "SS-M9"];
 export type OneTimeMigrationId = (typeof ONE_TIME_MIGRATION_IDS)[number];
 /**
  * 一条收据说迁移**对一个坐标做了什么**(闭集,每词一义):

package/dist/migration-receipt.js

@@ -1,6 +1,6 @@
 /** 本版登记的一次性**数据**迁移 id(闭集;每个 id 在 `ONE_TIME_MIGRATIONS` 登记表里恰一行)。收据只许这些 id —— 同表登记的 wire 删码位
  *  (`WIRE_RETIREMENT_IDS`,`./one-time-migrations`)不改任何存储形,铸不出收据,不在本集。 */
-export const ONE_TIME_MIGRATION_IDS = ["SS-M1", "SS-M2", "SS-M3", "SS-M4", "SS-M5", "SS-M6", "SS-M7", "SS-M9"];
+export const ONE_TIME_MIGRATION_IDS = ["SS-M1", "SS-M2", "SS-M3", "SS-M4", "SS-M5", "SS-M6", "SS-M7", "SS-M8", "SS-M9"];
 /**
  * 一条收据说迁移**对一个坐标做了什么**(闭集,每词一义):
  *  - `moved`            — 值搬到新位(`to`),义不变;

package/dist/one-time-migrations.d.ts

@@ -39,7 +39,7 @@ export type StoredDocuments = Readonly<Partial<Record<DomainName | RetiredDomain
 export interface StoredDocumentsMigration {
     /** 迁移后的文档集:没改的文档是**同一引用**;被移除的(retired 域)不在;新建的(例:迁出的 `governance` / `limits`)在。 */
     readonly docs: Readonly<Record<string, unknown>>;
-    /** 逐条收据(步序 SS-M1 → SS-M2 → SS-M5 → SS-M6 → SS-M9 → SS-M7 → SS-M4:纯改写步在前,用新 schema 终判的 SS-M4 最后;步内按坐标)。
+    /** 逐条收据(步序 SS-M1 → SS-M2 → SS-M5 → SS-M6 → SS-M8 → SS-M9 → SS-M7 → SS-M4:纯改写步在前,用新 schema 终判的 SS-M4 最后;步内按坐标)。
      *  只有 `refused` 的收据 = 什么都没改。 */
     readonly receipts: readonly MigrationReceipt[];
 }

package/dist/one-time-migrations.js

@@ -34,6 +34,7 @@ import { LANE_ENV_OWNER, STORE_ENV_KEYS, isLaneEnvKey } from "./execution-lane-i
 import { EXECUTION_LANE_WORDS, MEMORY_ENGINE_BACKENDS, STORE_BACKENDS } from "./execution-lanes.js";
 import { INTEGER } from "./integer.js";
 import { RUNTIME_LIFT_TARGETS } from "./runtime-lift-targets.js";
+import { RETIRED_ROLE_WORDS } from "./retired-role-words.js";
 import { REMOTE_EXEC_DOCUMENT, RemoteExecSpec } from "./remote-exec.js";
 import { DOMAIN_SCHEMAS, HOSTS_ARRAY_MAX, HOST_NAME_MAX, NON_SECRET_URL, isDomainName, isRetiredDomainName } from "./types.js";
 import { workerRowVerdict } from "./worker-row-verdict.js";
@@ -134,6 +135,19 @@ export const ONE_TIME_MIGRATIONS = [
         removal: "the next major after the window: delete the SS-M7 step and its schema walk; the NON_SECRET_URL fragment rule loses its SS-M7 clause",
         afterRemoval: "the NON_SECRET_URL shape judge, which refuses a fragment (`#` included) on read and write",
     },
+    {
+        id: "SS-M8",
+        oldForm: "refused",
+        introducedIn: "12.0.0",
+        releasedOn: "2026-10-12",
+        removableAfter: "2026-11-11",
+        rewrites: "models / rosters: role words removed by core 7.49.0: team, synthesize — the keys roles.team / roles.synthesize (models.roles and every " +
+            "rosters[].roles) are removed whatever their value (12.0.0 drops both words from ModelRole: no role reads them, and the engine refuses " +
+            "them); every other role and key stays as stored",
+        removal: "the next major after the window: delete the SS-M8 step; the retired role-word tombstone stays — its SS-M8 clause goes",
+        afterRemoval: "the retired role-word tombstone (permanent): a residual roles.team / roles.synthesize is refused on read and write (read: the entry is dropped " +
+            "when other roles survive, else models degrades to its default; rosters: the scope fails to read)",
+    },
     {
         id: "SS-M9",
         oldForm: "refused",
@@ -189,6 +203,7 @@ export function migrateStoredDocuments(docs, opts) {
     stepHostsBounds(out, receipts);
     stepModelKeyOneOf(out, receipts);
     stepAtMention(out, receipts);
+    stepRetiredRoleWords(out, receipts);
     stepModelsDefault(out, receipts);
     stepUrlFragments(out, receipts);
     stepWorkers6x(out, receipts);
@@ -675,6 +690,45 @@ function stepAtMention(out, receipts) {
             out.rosters = { ...rosters, rosters: next };
     }
 }
+// ── SS-M8:退役的角色词 ────────────────────────────────────────────────────────────────────────────────
+/** 一个 `roles` 图上的退役角色词键删掉(值不论 —— 没有角色读它);逐键一张 `dropped-inert` 收据。返回改后的图或 `undefined`(没改 / 不是对象:判形是读者的事)。 */
+function withoutRetiredRoles(roles, document, at, receipts) {
+    if (!isPlainObject(roles))
+        return undefined;
+    const present = RETIRED_ROLE_WORDS.filter((w) => Object.prototype.hasOwnProperty.call(roles, w));
+    if (present.length === 0)
+        return undefined;
+    let next = roles;
+    for (const w of present) {
+        next = without(next, w);
+        receipts.push(receipt("SS-M8", document, [...at, "roles", w], "dropped-inert"));
+    }
+    return next;
+}
+function stepRetiredRoleWords(out, receipts) {
+    const models = out.models;
+    if (isPlainObject(models)) {
+        const roles = withoutRetiredRoles(models.roles, "models", [], receipts);
+        if (roles !== undefined)
+            out.models = { ...models, roles };
+    }
+    const rosters = out.rosters;
+    if (isPlainObject(rosters) && Array.isArray(rosters.rosters)) {
+        const rows = rosters.rosters;
+        let next;
+        rows.forEach((row, index) => {
+            if (!isPlainObject(row))
+                return;
+            const roles = withoutRetiredRoles(row.roles, "rosters", ["rosters", index], receipts);
+            if (roles === undefined)
+                return;
+            next ??= [...rows];
+            next[index] = { ...row, roles };
+        });
+        if (next !== undefined)
+            out.rosters = { ...rosters, rosters: next };
+    }
+}
 // ── SS-M9:models.default → roles.default ──────────────────────────────────────────────────────────────
 /** 迁移前「缺省模型是谁」的生效读法 = server 的缺省解析以结构键 `default` 为第一级,主任务真跑它(N-7 两答复现:`default` = A、`roles.default`
  *  = B 时主任务跑 A,core 的 `default` 角色解到 B)。所以并过去的是 `default` 的值:`roles.default` 缺席 ⇒ 搬入;同名 ⇒ 搬入(重复的那一份

package/dist/resolve-roster.d.ts

@@ -13,7 +13,7 @@
 import type { AtMention, EffectiveConfig, EffectiveWire, ModelRole, RoleTarget, RosterEntry } from "./types.js";
 import { type RefIssue } from "./cross-domain.js";
 /** primaryModel 标记喂的角色族(§3)。 */
-export declare const ROSTER_PRIMARY_ROLES: readonly ["default", "team", "synthesize"];
+export declare const ROSTER_PRIMARY_ROLES: readonly ["default"];
 /** cheapModel 标记喂的角色族(§3)。 */
 export declare const ROSTER_CHEAP_ROLES: readonly ["subagent", "summarize"];
 /** 把 roster 的主/cheap 角色标记派生成 roles 片段(PURE)。显式 roster.roles 逐角色盖过它;它盖过全局

package/dist/resolve-roster.js

@@ -2,12 +2,12 @@ import { stableHash } from "./hash.js";
 import { danglingRefs } from "./cross-domain.js";
 import { toSkillsManifest } from "./skills-manifest.js";
 // ── 主/cheap 角色标记语义(0.6.3, E3)────────────────────────────────
-// service 现有 ModelRoles 口径:default/team/synthesize→主、subagent/summarize→cheap。1.8.0 起 `classifier`/`consolidate`
+// service 现有 ModelRoles 口径:default→主(12.0.0 起唯一;`team` / `synthesize` 随 core 7.49.0 删)、subagent/summarize→cheap。1.8.0 起 `classifier`/`consolidate`
 // 同 `verifier` 一样**不派生**(归 cheap 会盖掉 models.tiers 档位与 core 兜底链)。`verifier` 刻意
 // 不派生(unset→core 的 default 兜底链,与 service 语义一致)。常量导出=单一语义源,service 收敛小单与
 // web-admin 表单同源引用,别第二份。
 /** primaryModel 标记喂的角色族(§3)。 */
-export const ROSTER_PRIMARY_ROLES = ["default", "team", "synthesize"];
+export const ROSTER_PRIMARY_ROLES = ["default"];
 /** cheapModel 标记喂的角色族(§3)。 */
 export const ROSTER_CHEAP_ROLES = ["subagent", "summarize"];
 /** 把 roster 的主/cheap 角色标记派生成 roles 片段(PURE)。显式 roster.roles 逐角色盖过它;它盖过全局
@@ -86,7 +86,7 @@ export function resolveEffectiveForWorker(eff, worker) {
     // `{select}`-form (capability-based) roles name no model → kept.
     // Per-role merge (roster overrides global PER ROLE) — NOT a whole-map replace. The types promise "unset
     // roster roles fall back to global models.roles per role"; a whole-map `??` silently dropped the global
-    // `subagent`/`team`/… when a roster set only `default`. Round-3 fix. Then drop any dangling {model}.
+    // `subagent`/`summarize`/… when a roster set only `default`. Round-3 fix. Then drop any dangling {model}.
     // 0.6.3: marker-derived roles (primaryModel/cheapModel semantics) sit BETWEEN global and explicit
     // roster.roles — global < markers < explicit per-role. Markers are subset-validated at PUT; a stale marker
     // after a catalog change still falls through the dangling-{model} drop below (defence-in-depth).

package/dist/retired-role-words.d.ts

@@ -0,0 +1,5 @@
+/** 退役的角色词(闭集;逐字)。 */
+export declare const RETIRED_ROLE_WORDS: readonly ["team", "synthesize"];
+/** 一组被判官拒下的角色键 / 角色词里若有退役词 ⇒ 那一句(点名退役词与 SS-M8;同组里别的不认识的词也点名,一个不漏);没有 ⇒ `undefined`
+ *  (交回 zod 自己的句子)。`ModelRole` 的判句(一个词)与 `roles` 图的未知键判句(一组键)都调这一只。 */
+export declare function retiredRoleWordsRefusal(words: readonly unknown[]): string | undefined;

package/dist/retired-role-words.js

@@ -0,0 +1,25 @@
+/**
+ * 包内私有(不进主桶、不进 exports 表):12.0.0 退役的**角色词**墓碑 —— 引擎 core 7.49.0 把 `team` / `synthesize` 从角色表里删了(对未知角色词响亮拒),
+ * 本包的 `ModelRole` 随之收成 6 词。墓碑是**拒**,不是第二种读法:判官遇到这两个词不把它们读成任何角色,只说「这是一份没迁的旧形」以及去哪儿迁
+ * (一次性迁移 SS-M8,`./one-time-migrations`)。一处写词、一处写句:`ModelRole` 的判句、`roles` 图的未知键判句与 SS-M8 的改写步都读这里。
+ * 迁移族按登记表的窗整族删,墓碑留下 —— 到那时句子里的迁移指路由删码那一车去掉(登记表 SS-M8 行的 `removal`)。
+ */
+import { retiredFormSentence } from "./retired-form.js";
+/** 退役的角色词(闭集;逐字)。 */
+export const RETIRED_ROLE_WORDS = ["team", "synthesize"];
+const ROLE_WORDS_RETIRED = {
+    retiredIn: "12.0.0",
+    now: "no role reads it (core 7.49.0 removed the role and refuses the word)",
+    migration: "SS-M8",
+};
+const isRetiredRoleWord = (w) => RETIRED_ROLE_WORDS.some((r) => r === w);
+/** 一组被判官拒下的角色键 / 角色词里若有退役词 ⇒ 那一句(点名退役词与 SS-M8;同组里别的不认识的词也点名,一个不漏);没有 ⇒ `undefined`
+ *  (交回 zod 自己的句子)。`ModelRole` 的判句(一个词)与 `roles` 图的未知键判句(一组键)都调这一只。 */
+export function retiredRoleWordsRefusal(words) {
+    const retired = RETIRED_ROLE_WORDS.filter((r) => words.includes(r));
+    if (retired.length === 0)
+        return undefined;
+    const others = words.filter((w) => !isRetiredRoleWord(w)).map((w) => JSON.stringify(String(w)));
+    const head = others.length === 0 ? "" : `unrecognized role ${others.length === 1 ? "word" : "words"} ${others.join(", ")}; `;
+    return head + retiredFormSentence(`role word ${retired.join(" / ")}`, ROLE_WORDS_RETIRED);
+}

package/dist/safety-merge-spec.d.ts

@@ -53,8 +53,8 @@
 import { z } from "zod";
 /** How values from different layers/principals combine for a category. */
 export declare const MergeShape: z.ZodEnum<{
-    concat: "concat";
     replace: "replace";
+    concat: "concat";
     denyFirst: "denyFirst";
     runAll: "runAll";
     overrideByName: "overrideByName";
@@ -185,8 +185,8 @@ export declare const TightenRule: z.ZodDiscriminatedUnion<[z.ZodObject<{
 export type TightenRule = z.infer<typeof TightenRule>;
 export declare const MergeCategorySpec: z.ZodObject<{
     mergeShape: z.ZodEnum<{
-        concat: "concat";
         replace: "replace";
+        concat: "concat";
         denyFirst: "denyFirst";
         runAll: "runAll";
         overrideByName: "overrideByName";

package/dist/types.d.ts

@@ -204,8 +204,6 @@ export declare const ModelRole: z.ZodEnum<{
     default: "default";
     summarize: "summarize";
     subagent: "subagent";
-    team: "team";
-    synthesize: "synthesize";
     verifier: "verifier";
     classifier: "classifier";
     consolidate: "consolidate";
@@ -318,8 +316,6 @@ export declare const ModelsConfig: z.ZodObject<{
         default: "default";
         summarize: "summarize";
         subagent: "subagent";
-        team: "team";
-        synthesize: "synthesize";
         verifier: "verifier";
         classifier: "classifier";
         consolidate: "consolidate";
@@ -375,8 +371,6 @@ export declare const RosterEntry: z.ZodObject<{
         default: "default";
         summarize: "summarize";
         subagent: "subagent";
-        team: "team";
-        synthesize: "synthesize";
         verifier: "verifier";
         classifier: "classifier";
         consolidate: "consolidate";
@@ -421,8 +415,6 @@ export declare const RostersConfig: z.ZodObject<{
             default: "default";
             summarize: "summarize";
             subagent: "subagent";
-            team: "team";
-            synthesize: "synthesize";
             verifier: "verifier";
             classifier: "classifier";
             consolidate: "consolidate";
@@ -2334,8 +2326,6 @@ export declare const DOMAIN_SCHEMAS: {
             default: "default";
             summarize: "summarize";
             subagent: "subagent";
-            team: "team";
-            synthesize: "synthesize";
             verifier: "verifier";
             classifier: "classifier";
             consolidate: "consolidate";
@@ -2391,8 +2381,6 @@ export declare const DOMAIN_SCHEMAS: {
                 default: "default";
                 summarize: "summarize";
                 subagent: "subagent";
-                team: "team";
-                synthesize: "synthesize";
                 verifier: "verifier";
                 classifier: "classifier";
                 consolidate: "consolidate";

package/dist/types.js

@@ -30,6 +30,7 @@ import { Sha256Digest } from "./sha256.js"; // the one `sha256:<hex>` digest for
 import { EXECUTION_LANES, EXECUTION_LANE_WORDS, MEMORY_ENGINE_BACKENDS, SESSION_BACKENDS, STORE_BACKENDS, retiredLaneWordRefusal } from "./execution-lanes.js"; // 7.0.0 M-R2: the lane / store vocabulary (one exported table)
 import { LANE_ENV_OWNER, isMigratableEnvKey, laneEnvSeat, laneRowOf } from "./execution-lane-index.js"; // package-private indexes derived from that table (not in the barrel)
 import { migrationSignpost, retiredFormSentence, retiredKey } from "./retired-form.js"; // 11.0.0: the ONE retired-form sentence + key tombstone (package-private)
+import { retiredRoleWordsRefusal } from "./retired-role-words.js"; // 12.0.0: the retired role-word tombstone (package-private; SS-M8)
 import { buildQuotedIssue, fixed } from "./quoted-issue.js"; // THE minting point of custom issues (package-private)
 import { AbsoluteHostPath } from "./host-path.js"; // the one host-path shape judge (a task's cwd and a project's folder / file entries)
 import { RFC3339_DATE_TIME } from "./rfc3339.js"; // the package's one RFC 3339 date-time judge (package-private)
@@ -550,20 +551,31 @@ export const ModelEntry = z.object({
 // `verifier` (2026-06-11, SERVICE-RESPONSE-…-PHASE2): real consumer = core's verification gate
 // (runWithVerification/resumeWithVerification resolve the verifier sub-task model via this role). Fallback
 // semantics per core: a roster that doesn't set `verifier` uses `default`.
-// 1.8.0(消费方壳侧真案):对齐 core `ModelRole`(9 词)里**有真消费方**的两个缺席角色 ——
-//   `classifier`  = auto 模式权限分类器(core FALLBACK classifier→summarize→default;tier 缺省 flash);此前 settings
-//                   写 `roles.classifier` 被本闭集拒,用户想单独钉分类器模型只能连带 summarize。
+// 1.8.0(消费方壳侧真案):对齐 core 角色表里**有真消费方**的两个角色 ——
+//   `classifier`  = auto 模式权限分类器(core FALLBACK classifier→summarize→default;tier 缺省 flash);
 //   `consolidate` = 记忆整理(core FALLBACK consolidate→summarize)。
 // 两个词都**不进** roster 标记族(resolve-roster.ts):显式归 cheap 会让 server 把它钉死到 cheapRef,盖掉用户
 // `models.tiers.flash` 的档位与 core 兜底链 —— 新角色「不派生、走 core 兜底、只由 settings 显式钉」。
-// `advisor`(teacher mode)仍 deliberately NOT added: no consumer, no key —— 谁消费谁来加。
-// 子集关系由消费方服务端的型面对账钉(编译期 `satisfies`)钉住(本仓不依赖 core)。
-export const ModelRole = z.enum(["default", "summarize", "subagent", "team", "synthesize", "verifier", "classifier", "consolidate"]);
+// 12.0.0(硬破坏):`team` / `synthesize` 随 core 7.49.0 删掉(引擎对未知角色词响亮拒)—— 零别名、零双读;存着的这两个键由一次性迁移 SS-M8 删,
+// 迁移前到达判官的旧词拒句点名它(墓碑在 `./retired-role-words`)。`advisor`(teacher mode)本包从未收(没有消费方)。
+// 子集关系(本表 ⊆ 引擎角色表)由消费方服务端的型面对账钉住(本仓不依赖 core;dev 期的漂移门 ② 对拍 devDependency 那一版引擎)。
+export const ModelRole = z.enum(["default", "summarize", "subagent", "verifier", "classifier", "consolidate"], {
+    error: (iss) => (iss.code === "invalid_value" ? retiredRoleWordsRefusal([iss.input]) : undefined),
+});
 /** A role resolves either to a model NAME, or by capability/price (core 1.25 `{ select }`). */
 export const RoleTarget = z.union([
     z.object({ model: z.string().min(1) }),
     z.object({ select: z.object({ tier: ModelTier.optional(), needs: z.array(z.enum(["vision", "reasoning"])).optional(), prefer: z.enum(["cheapest", "premium"]).optional() }) }),
 ]);
+/** 角色 → 目标的图(`models.roles` 与 `rosters[].roles` 同一只)。键不认识 ⇒ zod 的「未知键」句;键里有 12.0.0 退役的角色词 ⇒ 那一句点名
+ *  一次性迁移 SS-M8(同组别的未知键一并点名)。 */
+const RoleMap = z.partialRecord(ModelRole, RoleTarget, {
+    // 枚举键的 record 在运行期以 `unrecognized_keys`(带 `keys`)报未知键,zod 的型面只列了 invalid_type / invalid_key —— 按运行期形读(钉:role-words-12.0.0)。
+    error: (iss) => {
+        const raw = iss;
+        return raw.code === "unrecognized_keys" && Array.isArray(raw.keys) ? retiredRoleWordsRefusal(raw.keys) : undefined;
+    },
+});
 /** {@link AtMention} 的模式闭集:`all` = 每个启用的模型都可 `@`;`none` = 一个都不许;`only` = 只许 `models` 里点名的那几个。 */
 export const AT_MENTION_MODES = ["all", "none", "only"];
 /** 「`@` 能点名哪些模型」(11.0.0,取代 `atModelAllowlist`)。义由 `mode` 说,不由数组空不空说:旧形一个数组靠「缺席 / 空 / 非空」
@@ -609,7 +621,7 @@ export const ModelsConfig = z
      *  the main task ran the first and the core `default` role resolved the second). Which catalog entry is the default is
      *  `resolveCatalogDefaultModel` (`./default-model`; a `{select}` default is handed back as-is for the engine to resolve). A stored
      *  `default` key is moved here by the one-time migration SS-M9. */
-    roles: z.partialRecord(ModelRole, RoleTarget).prefault({}),
+    roles: RoleMap.prefault({}),
     /** Which model names an end user may `@`-mention({@link AtMention});缺省 `{mode:"all"}`。 */
     atMention: AtMention.prefault({ mode: "all" }),
     /** retired 键墓碑(11.0.0):在场即拒,拒句点名一次性迁移 SS-M6。 */
@@ -675,7 +687,7 @@ export const RosterEntry = z.object({
     models: z.array(z.string().min(1)).prefault([]),
     /**
      * 主模型角色标记(0.6.3, E3)——catalog model NAME。worker.model 废除后 service 从 roster
-     * 解析 boot 主模型的归宿位:解析语义(resolve-roster)= primary 喂 `default`/`team`/`synthesize` 三角色、
+     * 解析 boot 主模型的归宿位:解析语义(resolve-roster)= primary 喂 `default`(12.0.0 起唯一;`team` / `synthesize` 随 core 7.49.0 删)、
      * cheap 喂 `subagent`/`summarize`(service 现有 ModelRoles 口径;`verifier`/`classifier`/`consolidate` 不派生——unset 走 core 兜底链)。
      * 显式 `roles` **逐角色**优先于标记派生;标记优先于全局 models.roles。additive:不设=行为与 0.6.2 全等。
      */
@@ -683,7 +695,7 @@ export const RosterEntry = z.object({
     /** cheap 模型角色标记(同上;worker.model.cheapId 的迁移归宿,§3②)。 */
     cheapModel: z.string().min(1).optional(),
     /** Role map override; unset roles fall back to marker-derived roles, then the global models.roles. */
-    roles: z.partialRecord(ModelRole, RoleTarget).optional(),
+    roles: RoleMap.optional(),
     /** `@` 点名覆盖({@link AtMention});缺席 = 继承全局 `models.atMention`。 */
     atMention: AtMention.optional(),
     /** retired 键墓碑(11.0.0):在场即拒,拒句点名一次性迁移 SS-M6。 */

package/dist/write-failure.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 包内私有(不进主桶、不进 exports 表;零 `node:` 依赖):原子写器(`./atomic-write`)写失败的**唯一一句** —— 按失败落在哪一步、errno 是什么分句,
+ * 句尾给那一步对应的出路。写器有两步:在目标所在目录里建临时文件(`create`,连同恢复沿用的模式)、`rename` 盖过目标(`replace`)。
+ * 改前一句话包打天下(「cannot write <文件>: <Node 的错误句> … fix the cause」):目录不可写时点名的却是文件(Node 句子里是临时文件的路径),
+ * 而可写目录里的只读文件照常写得进 —— 句子把人指向了错的那一个。命令行(`./cli`)认这只错误类型、原样印它的句子。
+ */
+/** 原子写的两步(闭集)。 */
+export type AtomicWriteStep = "create" | "replace";
+/** 一次写失败的句子(纯函数)。认得的 errno 给对应出路;别的 errno(磁盘满、I/O 错 …)给 Node 自己的句子 —— 照样响亮,只是不替它猜出路。 */
+export declare function atomicWriteFailureSentence(step: AtomicWriteStep, dir: string, file: string, cause: unknown): string;
+/** 原子写器抛的错:句子见 {@link atomicWriteFailureSentence};`code` 照抄底层 errno(按 `code` 分支的调用方不受影响),原错误在 `cause`。 */
+export declare class AtomicWriteFailure extends Error {
+    readonly step: AtomicWriteStep;
+    readonly code: string | undefined;
+    constructor(step: AtomicWriteStep, dir: string, file: string, cause: unknown);
+}

package/dist/write-failure.js

@@ -0,0 +1,43 @@
+/**
+ * 包内私有(不进主桶、不进 exports 表;零 `node:` 依赖):原子写器(`./atomic-write`)写失败的**唯一一句** —— 按失败落在哪一步、errno 是什么分句,
+ * 句尾给那一步对应的出路。写器有两步:在目标所在目录里建临时文件(`create`,连同恢复沿用的模式)、`rename` 盖过目标(`replace`)。
+ * 改前一句话包打天下(「cannot write <文件>: <Node 的错误句> … fix the cause」):目录不可写时点名的却是文件(Node 句子里是临时文件的路径),
+ * 而可写目录里的只读文件照常写得进 —— 句子把人指向了错的那一个。命令行(`./cli`)认这只错误类型、原样印它的句子。
+ */
+/** `create` 步里「目录本身不让建文件」的 errno:权限不够、只读文件系统、目录不在。出路 = 让目录可写。 */
+const DIRECTORY_NOT_WRITABLE = new Set(["EACCES", "EPERM", "EROFS", "ENOENT"]);
+/** `replace` 步里「目录收新文件、却换不掉这一份」的 errno:不可变标志、粘滞目录里别人的文件。出路 = 让文件可被替换。 */
+const FILE_NOT_REPLACEABLE = new Set(["EACCES", "EPERM"]);
+const errnoOf = (e) => {
+    const code = e?.code;
+    return typeof code === "string" ? code : undefined;
+};
+const messageOf = (e) => (e instanceof Error ? e.message : String(e)).replace(/\s*\n\s*/g, " ");
+/** 一次写失败的句子(纯函数)。认得的 errno 给对应出路;别的 errno(磁盘满、I/O 错 …)给 Node 自己的句子 —— 照样响亮,只是不替它猜出路。 */
+export function atomicWriteFailureSentence(step, dir, file, cause) {
+    const code = errnoOf(cause);
+    const tag = code === undefined ? "" : ` (${code})`;
+    switch (step) {
+        case "create":
+            return code !== undefined && DIRECTORY_NOT_WRITABLE.has(code) ? `cannot write into directory ${dir}${tag}: make the directory writable` : `cannot write into directory ${dir}${tag}: ${messageOf(cause)}`;
+        case "replace":
+            return code !== undefined && FILE_NOT_REPLACEABLE.has(code)
+                ? `cannot replace ${file}${tag}: make the file replaceable — clear an immutable flag; in a sticky directory only the file's owner may replace it`
+                : `cannot replace ${file}${tag}: ${messageOf(cause)}`;
+        default: {
+            const unhandled = step;
+            throw new Error(`atomicWriteFailureSentence: unhandled step ${String(unhandled)}`);
+        }
+    }
+}
+/** 原子写器抛的错:句子见 {@link atomicWriteFailureSentence};`code` 照抄底层 errno(按 `code` 分支的调用方不受影响),原错误在 `cause`。 */
+export class AtomicWriteFailure extends Error {
+    step;
+    code;
+    constructor(step, dir, file, cause) {
+        super(atomicWriteFailureSentence(step, dir, file, cause), { cause });
+        this.name = "AtomicWriteFailure";
+        this.step = step;
+        this.code = errnoOf(cause);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/settings-schema",
-  "version": "11.3.0",
+  "version": "12.0.0",
   "description": "Sema settings schema — pure config contract (zod domains + effective-config + roster resolution + ref-integrity + remoteExec) shared by sema-web-admin, sema-server, and the TOC desktop/CLI. One source of truth. (Renamed at 1.0.0 from @sema-agent/registry-core — name and docs only, no behavior change; note the range moves 0.19.0 -> 1.0.0, so a dependency must become ^1.0.0. The old names @sema-agent/registry-core <=0.19.0 and @sema-ai/registry-core remain published, frozen, for migration.)",
   "type": "module",
   "license": "BUSL-1.1",