@sema-agent/settings-schema 11.2.0 → 12.0.0

package/conformance/cases/c75-projects-patch-remote-uniqueness/input.json

@@ -0,0 +1,35 @@
+{
+  "meta": {
+    "version": 17,
+    "updatedAt": "2026-10-12T00:00:00.000Z"
+  },
+  "domains": {
+    "projects": {
+      "projects": {
+        "01890a5d-ac96-774b-bcce-b302099a8057": {
+          "gitRemotes": [
+            "example.com/acme/shared"
+          ],
+          "defaultScopes": [
+            "proj"
+          ],
+          "registeredBy": "alice",
+          "registeredAt": "2026-10-01T00:00:00.000Z",
+          "displayName": "holder"
+        },
+        "9b2ee1f0-3f9a-4c1d-8b7e-2a54ff00c9d3": {
+          "gitRemotes": [
+            "example.com/acme/own",
+            "example.com/acme/shared"
+          ],
+          "defaultScopes": [
+            "proj"
+          ],
+          "registeredBy": "alice",
+          "registeredAt": "2026-10-01T00:00:00.000Z",
+          "displayName": "patched"
+        }
+      }
+    }
+  }
+}

package/conformance/cases/c75-projects-patch-remote-uniqueness/meta.json

@@ -0,0 +1,5 @@
+{
+  "contributor": "contract",
+  "claim": "PATCH 合并出来的形:后一个项目(被 PATCH 的那个,排在文档末尾)带上了前一个项目已登记的 remote。remote 全局唯一由同一只 superRefine 判,整域拒、坐标落在后来者的那一条 remote 上。打的是「PATCH 只判请求体、不对整份登记簿再判一次 remote 唯一」的写入面(两个项目同领一条 remote = 找回阶梯二义)。",
+  "firstRedOn": []
+}

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/api/feedback.js

@@ -13,6 +13,7 @@
  */
 import { z } from "zod";
 import { INTEGER } from "../integer.js";
+import { buildQuotedIssue, fixed } from "../quoted-issue.js";
 /** 报告的端点,相对 web-admin 根。 */
 export const FEEDBACK_V1_PATH = "/api/v1/feedback";
 /** `description`(去首尾空白后)的上限 —— 报告常带粘贴的报错与栈,所以宽,但有界。 */
@@ -36,9 +37,7 @@ export const FeedbackSubmitRequest = z.object({
     /** 客户端自报的时刻(参考,不信任 —— 回体的 `createdAt` 由服务端盖)。 */
     datetime: z.string(),
     latestAssistantMessageId: z.string().nullable().optional(),
-    transcript: z.array(z.unknown()).refine((t) => JSON.stringify(t).length <= FEEDBACK_TRANSCRIPT_MAX_JSON_CHARS, {
-        message: `transcript must serialize to at most ${FEEDBACK_TRANSCRIPT_MAX_JSON_CHARS} characters`,
-    }),
+    transcript: z.array(z.unknown()).refine((t) => JSON.stringify(t).length <= FEEDBACK_TRANSCRIPT_MAX_JSON_CHARS, buildQuotedIssue `transcript must serialize to at most ${fixed(String(FEEDBACK_TRANSCRIPT_MAX_JSON_CHARS))} characters`),
     errors: z.array(FeedbackError).optional(),
     lastApiRequest: z.unknown().optional(),
     subagentTranscripts: z.record(z.string(), z.unknown()).optional(),

package/dist/api/scopes.js

@@ -45,6 +45,7 @@
  */
 import { z } from "zod";
 import { INTEGER } from "../integer.js";
+import { buildQuotedIssue, fixed } from "../quoted-issue.js";
 import { USER_ROLES } from "../config-fns.js";
 import { ACCESS_TOKEN_TTL_SECONDS } from "./auth.js";
 // ── constants ────────────────────────────────────────────────────────────────────────────────────────────
@@ -137,7 +138,7 @@ export const SCOPE_SWITCH_TOKEN_TTL_SECONDS = ACCESS_TOKEN_TTL_SECONDS;
 /** Reserved ids ("global") are rejected AT THE SCHEMA — the default scope pre-exists and is not creatable. */
 export const ScopeCreateRequest = z
     .object({
-    id: ScopeId.refine((id) => !isReservedScopeId(id), { message: `"${GLOBAL_SCOPE}" is reserved` }),
+    id: ScopeId.refine((id) => !isReservedScopeId(id), buildQuotedIssue `"${fixed(GLOBAL_SCOPE)}" is reserved`),
     name: z.string().min(1).max(200),
 })
     .passthrough();

package/dist/atomic-write.d.ts

@@ -10,5 +10,11 @@ export declare const ATOMIC_FILE_CLASSES: {
     };
 };
 export type AtomicFileClass = keyof typeof ATOMIC_FILE_CLASSES;
+/** 悬空符号链接的**唯一一句**(写器与目录迁移的读口抛同一句;不带 errno 码 —— 带了 `ENOENT` 的错会被「ENOENT = 缺席」的读者读成文件不在,
+ *  悬空链接恰恰不是缺席)。 */
+export declare function danglingSymlinkSentence(link: string, pointsAt: string): string;
+/** 读写的真目标 —— **一只判法**(写器与目录迁移的读口共用):`target` 是符号链接 ⇒ 解析到它指向的真文件(悬空 ⇒ 抛 {@link danglingSymlinkSentence});
+ *  不是链接或不存在 ⇒ 原样(不存在的由调用方的读 / 写照常报)。 */
+export declare function resolveSymlinkTarget(target: string): string;
 /** 原子写 `text`(UTF-8)到 `target`(符号链接则写到它指向的真文件,见文件头);模式按 `kind` 在 {@link ATOMIC_FILE_CLASSES} 里的行。父目录须已存在。 */
 export declare function writeFileAtomic(target: string, text: string, kind: AtomicFileClass): void;

package/dist/atomic-write.js

@@ -17,17 +17,31 @@
  * 临时文件建在真文件所在目录、rename 到真文件**:链接(及链上每一环)原样保留,真文件的内容更新,模式规则作用在真文件上。临时文件与目标同目录 ⇒ rename 不会跨文件系统;
  * 真文件所在目录写不进、或 rename 因别的原因失败 ⇒ 响亮抛,**绝不**回退成「在链接位置写一个普通文件」(那是静默换形)。路径本身是悬空链接 ⇒ 响亮抛
  * (不在链接位置建普通文件,也不替链接建它指向的文件);成环的链接由 `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" },
     "scheduler-store": { newMode: 0o600, existing: "reset" },
 };
-/** 写盘的真目标:`target` 是符号链接 ⇒ 解析到它指向的真文件(悬空 ⇒ 抛);不是链接或不存在 ⇒ 原样。 */
-function resolveWriteTarget(target) {
+/** 悬空符号链接的**唯一一句**(写器与目录迁移的读口抛同一句;不带 errno 码 —— 带了 `ENOENT` 的错会被「ENOENT = 缺席」的读者读成文件不在,
+ *  悬空链接恰恰不是缺席)。 */
+export function danglingSymlinkSentence(link, pointsAt) {
+    return `${link} is a dangling symbolic link (it points at ${pointsAt}, which does not exist) — nothing is read or written through it; repair or remove the link`;
+}
+/** 读写的真目标 —— **一只判法**(写器与目录迁移的读口共用):`target` 是符号链接 ⇒ 解析到它指向的真文件(悬空 ⇒ 抛 {@link danglingSymlinkSentence});
+ *  不是链接或不存在 ⇒ 原样(不存在的由调用方的读 / 写照常报)。 */
+export function resolveSymlinkTarget(target) {
     let link;
     try {
         link = lstatSync(target).isSymbolicLink();
@@ -44,14 +58,14 @@ function resolveWriteTarget(target) {
     }
     catch (e) {
         if (e.code === "ENOENT") {
-            throw new Error(`writeFileAtomic: ${target} is a dangling symbolic link (it points at ${readlinkSync(target)}) — refusing to replace the link or to create what it points at; repair or remove the link`, { cause: e });
+            throw new Error(danglingSymlinkSentence(target, readlinkSync(target)), { cause: e });
         }
         throw e;
     }
 }
 /** 原子写 `text`(UTF-8)到 `target`(符号链接则写到它指向的真文件,见文件头);模式按 `kind` 在 {@link ATOMIC_FILE_CLASSES} 里的行。父目录须已存在。 */
 export function writeFileAtomic(target, text, kind) {
-    const real = resolveWriteTarget(target);
+    const real = resolveSymlinkTarget(target);
     const spec = ATOMIC_FILE_CLASSES[kind];
     let kept; // the existing file's mode, when this class keeps it
     switch (spec.existing) {
@@ -71,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) {
@@ -85,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

@@ -2,20 +2,22 @@
  * `settings-schema` 命令行的核心(11.0.0)—— 子命令只有一个:`migrate <config.d 目录> [--check]`,即一次性迁移
  * `migrateStoredDocuments`(`./one-time-migrations`)的目录形(本地 config.d / 离线文件用;web-admin 在它起服时直接调同一只函数)。
  * 目录形的语义(读目录 → 迁 → 整域终判 → 原子写 → 删 retired 域文件)只有一处实现:`migrateConfigDirectory`(`./config-dir-migration`,`./node` 导出,引擎起服调同一只);
- * 本模块是它的**渲染器**:把它的结果闭集渲染成退出码、报告行与 stderr 句子。命令行的覆盖面是全部配置域加 retired 域。
+ * 本模块是它的**渲染器**:把它的结果闭集渲染成退出码、报告行与 stderr 句子。命令行的覆盖面是全部配置域、retired 域与 `remote-exec.json`。
  * 目录被当作**一个 scope 的全集**(`coverage: "scope"`):目录里没有的域文件就是从未设过。
  *
  * 本模块不碰 `node:fs`:读写文件由入口 `bin/settings-schema.mjs` 注入(真绑定是 `./config-dir-io` 的 `nodeConfigDirectoryIo`,写盘用的是 `./atomic-write` 那一只原子写器 —— 写法与文件模式在那里一处定),所以测试可以直接驱动它。
  * 不进主桶 —— 它是 bin 的实现,不是契约面。
  *
- * 读哪些文件:目录里 `<名>.json`,名是配置域或 retired 域(`runtime`)—— 便携与否不论(离线的 `workers.json` 一样迁);别的文件
- * (`remote-exec.json`、隐藏文件、不认识的名)不读不动。
+ * 读哪些文件:目录里 `<名>.json`,名是配置域或 retired 域(`runtime`)—— 便携与否不论(离线的 `workers.json` 一样迁)—— 以及 `remote-exec.json`
+ * (一次性迁移 SS-M7 的座位走查也走它的两个端点);别的文件(隐藏文件、不认识的名、非 `.json`)不读不动。
  *
  * 零域文档分两形:**有条目却没有域文档**(任何非 `.` 开头的条目 —— 子目录、说明文件、不认识的名)⇒ 退出 2;**目录真空**(零条目,或只有以 `.` 开头的条目)⇒ 照常走判定,
  * 零收据 = noop 退出 0 —— 新部署的空 `config.d` 是合法态,「没有东西可迁」不是「指错目录」(搬空之后再跑同一目录也因此幂等)。
  *
  * 退出码:0 = 已写回 / 无事可做(目录里有域文档只是没有要改的,或目录真空);1 = 有迁不了的坐标(收据 `refused`)**或**要写回的域文档整域读不进(整域终判,见 `migrateConfigDirectory`),**一字不写**;
- * 2 = 用法 / 读目录 / 读文件错,或某个域文件是坏文件(空 / 纯空白 / 坏 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。
  *
@@ -32,4 +34,6 @@ export interface SettingsSchemaCliIo extends ConfigDirectoryIo {
     stdout(text: string): void;
     stderr(text: string): void;
 }
+/** 命令行的覆盖面:全部配置域、retired 域(便携与否不论 —— 离线的 `workers.json` 一样迁)与 `remote-exec.json`。 */
+export declare const COVERED_DOCUMENTS: ("models" | "rosters" | "scenarios" | "skills" | "execution" | "plugins" | "systems" | "limits" | "runtime" | "workers" | "hosts" | "projects" | "mcp" | "collab" | "governance" | "entitlement" | "prompts" | "remote-exec")[];
 export declare function runSettingsSchemaCli(argv: readonly string[], io: SettingsSchemaCliIo): Promise<number>;

package/dist/cli.js

@@ -2,20 +2,22 @@
  * `settings-schema` 命令行的核心(11.0.0)—— 子命令只有一个:`migrate <config.d 目录> [--check]`,即一次性迁移
  * `migrateStoredDocuments`(`./one-time-migrations`)的目录形(本地 config.d / 离线文件用;web-admin 在它起服时直接调同一只函数)。
  * 目录形的语义(读目录 → 迁 → 整域终判 → 原子写 → 删 retired 域文件)只有一处实现:`migrateConfigDirectory`(`./config-dir-migration`,`./node` 导出,引擎起服调同一只);
- * 本模块是它的**渲染器**:把它的结果闭集渲染成退出码、报告行与 stderr 句子。命令行的覆盖面是全部配置域加 retired 域。
+ * 本模块是它的**渲染器**:把它的结果闭集渲染成退出码、报告行与 stderr 句子。命令行的覆盖面是全部配置域、retired 域与 `remote-exec.json`。
  * 目录被当作**一个 scope 的全集**(`coverage: "scope"`):目录里没有的域文件就是从未设过。
  *
  * 本模块不碰 `node:fs`:读写文件由入口 `bin/settings-schema.mjs` 注入(真绑定是 `./config-dir-io` 的 `nodeConfigDirectoryIo`,写盘用的是 `./atomic-write` 那一只原子写器 —— 写法与文件模式在那里一处定),所以测试可以直接驱动它。
  * 不进主桶 —— 它是 bin 的实现,不是契约面。
  *
- * 读哪些文件:目录里 `<名>.json`,名是配置域或 retired 域(`runtime`)—— 便携与否不论(离线的 `workers.json` 一样迁);别的文件
- * (`remote-exec.json`、隐藏文件、不认识的名)不读不动。
+ * 读哪些文件:目录里 `<名>.json`,名是配置域或 retired 域(`runtime`)—— 便携与否不论(离线的 `workers.json` 一样迁)—— 以及 `remote-exec.json`
+ * (一次性迁移 SS-M7 的座位走查也走它的两个端点);别的文件(隐藏文件、不认识的名、非 `.json`)不读不动。
  *
  * 零域文档分两形:**有条目却没有域文档**(任何非 `.` 开头的条目 —— 子目录、说明文件、不认识的名)⇒ 退出 2;**目录真空**(零条目,或只有以 `.` 开头的条目)⇒ 照常走判定,
  * 零收据 = noop 退出 0 —— 新部署的空 `config.d` 是合法态,「没有东西可迁」不是「指错目录」(搬空之后再跑同一目录也因此幂等)。
  *
  * 退出码:0 = 已写回 / 无事可做(目录里有域文档只是没有要改的,或目录真空);1 = 有迁不了的坐标(收据 `refused`)**或**要写回的域文档整域读不进(整域终判,见 `migrateConfigDirectory`),**一字不写**;
- * 2 = 用法 / 读目录 / 读文件错,或某个域文件是坏文件(空 / 纯空白 / 坏 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。
  *
@@ -28,16 +30,19 @@
  */
 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` 一样迁)。 */
-const COVERED_DOCUMENTS = [...DOMAINS, ...Object.keys(RETIRED_DOMAINS)];
+/** 命令行的覆盖面:全部配置域、retired 域(便携与否不论 —— 离线的 `workers.json` 一样迁)与 `remote-exec.json`。 */
+export const COVERED_DOCUMENTS = [...DOMAINS, ...Object.keys(RETIRED_DOMAINS), REMOTE_EXEC_DOCUMENT];
 const USAGE = [
     `usage: ${MIGRATE_COMMAND_TEMPLATE} [--check]`,
-    "  Runs the one-time migrations (@sema-agent/settings-schema/one-time-migrations) over every <domain>.json in the directory, read as one",
+    "  Runs the one-time migrations (@sema-agent/settings-schema/one-time-migrations) over every <domain>.json (and remote-exec.json) in the directory, read as one",
     "  scope (a missing domain file = never set): writes the rewritten files in place and removes retired-domain files (runtime.json) only when",
     "  nothing is refused and every document it would write reads as a whole domain; --check runs the same verdict and only reports (exit 3",
     "  if something would change). The argument is the config.d directory itself; a directory that has entries but no <domain>.json among them is",
-    "  refused (exit 2); an empty directory has nothing to migrate (exit 0).",
+    "  refused (exit 2); an empty directory has nothing to migrate (exit 0). An I/O failure (reading, writing or removing a file) exits 2 with",
+    "  one line on stderr naming the path and the error.",
     "  stdout (exit 0 / 1 / 3): line 1 = outcome=<refused|applied|noop|pending> written=<true|false>, line 2 = the JSON report",
     "  (applied only when written=true; otherwise wouldApply).",
 ].join("\n");
@@ -69,6 +74,36 @@ function reportOf(outcome, dir, applied, refused) {
     });
     return `outcome=${outcome} written=${written}\n${json}\n`;
 }
+/** 写回阶段(写盘 / 删文件)的一次 I/O 失败 —— 环境错一臂(rc 2)。只由 {@link withEnvironmentArm} 包的两个写口铸;别的抛错(包内守卫、误用)不是它,照旧抛。 */
+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 AtomicWriteFailure}:目录建不出文件 ⇒
+ *  点名目录,目标换不掉 ⇒ 点名文件,句尾是对应出路)—— 原样用;别的写口(注入的替身)抛的错 ⇒ 点名**要写的那份文件**与原错误句。
+ *  读口不包:读目录 / 读文件错由 `migrateConfigDirectory` 自己收成 `unreadable`(同为 rc 2)。 */
+function withEnvironmentArm(io) {
+    return {
+        readDir: (path) => io.readDir(path),
+        readFile: (path) => io.readFile(path),
+        writeFileAtomic: async (path, text) => {
+            try {
+                await io.writeFileAtomic(path, text);
+            }
+            catch (err) {
+                throw new EnvironmentFailure(err instanceof AtomicWriteFailure ? err.message : `cannot write ${path}: ${messageOf(err)}`, { cause: err });
+            }
+        },
+        removeFile: async (path) => {
+            try {
+                await io.removeFile(path);
+            }
+            catch (err) {
+                throw new EnvironmentFailure(`cannot remove ${path}: ${messageOf(err)}`, { cause: err });
+            }
+        },
+    };
+}
 /** 「有条目却没有域文档」的拒句:点名这个目录、说要的是 `config.d` 目录本身;`<dir>/config.d` 在场(探一次)就直接点它 —— 最常见的错是填了它的上一层。指路的命令里路径过 shell 引用,可直接粘贴。 */
 async function noDomainDocumentsSentence(dir, io) {
     const nested = joinDirPath(dir, "config.d");
@@ -85,10 +120,20 @@ export async function runSettingsSchemaCli(argv, io) {
         io.stderr(`${USAGE}\n`);
         return 2;
     }
-    const m = await migrateConfigDirectory(dir, { documents: COVERED_DOCUMENTS, io, check });
+    let m;
+    try {
+        m = await migrateConfigDirectory(dir, { documents: COVERED_DOCUMENTS, io: withEnvironmentArm(io), check });
+    }
+    catch (err) {
+        if (!(err instanceof EnvironmentFailure))
+            throw err;
+        // 写回阶段断在这里:之前写完的文档已在新形上,再跑一次幂等收尾(迁移只认形)。stdout 不出结论行 —— 没有 `outcome=applied`。
+        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) {
         case "unreadable":
-            io.stderr(`settings-schema: ${m.reason}\n`);
+            io.stderr(`settings-schema: ${oneLine(m.reason)}\n`);
             return 2;
         case "no-documents":
             if (m.entries.some((name) => !name.startsWith("."))) {

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

@@ -1,9 +1,19 @@
+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;
+/** 判一份 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,38 +1,65 @@
 /**
- * 包内私有(不进主桶、不进 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 } from "./config-fns.js";
+import { refuseRetiredDomain, sanitizeZodError } from "./config-fns.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`;
+}
+/** 判一份 remote-exec 文档的值(`RemoteExecSpec`),错误**脱敏**(zod 会回显出错的值 —— 粘错位置的密钥不许随抛出的错走);反射访问抛(恶意 getter /
+ *  Proxy)⇒ 定句。`loadRemoteExec` / `writeRemoteExec` 与目录迁移的整文档终判调同一只。 */
+export function parseRemoteExecDocument(raw) {
+    let r;
+    try {
+        r = RemoteExecSpec.safeParse(raw);
+    }
+    catch {
+        throw new Error("invalid remoteExec (a value could not be read during validation)");
+    }
+    if (r.success)
+        return r.data;
+    throw sanitizeZodError(r.error);
+}
 /** `<root>/config.d/<名>.json` 的路径 —— 名字的判也在这里(**一处**):不是配置域也不是 retired 域 ⇒ 拒(不拿用户给的名拼路径,防 `../` 穿越)。 */
 export function configDPath(root, name) {
     if (!isDomainName(name) && !isRetiredDomainName(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-io.js

@@ -1,13 +1,14 @@
 /**
  * `migrateConfigDirectory`(`./config-dir-migration`)的**真 I/O 绑定**(Node 专用):读目录 / 读文件 / 删文件走 `node:fs/promises`,写盘走本包唯一的原子写器
  * `./atomic-write`(同目录临时文件 → rename;`config-document` 类的模式规则:新建 0o644 经 umask、已有的沿用原模式;目标是符号链接则写到它指向的真文件)。
+ * 读目录 / 读文件先过写器同一只链接判法 `resolveSymlinkTarget`:链接读它指向的真文件 / 真目录,**悬空链接**抛与写器同一句(改前读阶段先撞 ENOENT,句子不提链接)。
  * 命令行入口与引擎起服的目录迁移注入同一份,写法与文件模式因此只在原子写器那一处定。
  */
 import { readdir, readFile, unlink } from "node:fs/promises";
-import { writeFileAtomic } from "./atomic-write.js";
+import { resolveSymlinkTarget, writeFileAtomic } from "./atomic-write.js";
 export const nodeConfigDirectoryIo = {
-    readDir: (path) => readdir(path),
-    readFile: (path) => readFile(path, "utf8"),
+    readDir: async (path) => readdir(resolveSymlinkTarget(path)),
+    readFile: async (path) => readFile(resolveSymlinkTarget(path), "utf8"),
     writeFileAtomic: async (path, text) => writeFileAtomic(path, text, "config-document"), // the files this migration writes are config.d domain documents
     removeFile: (path) => unlink(path),
 };

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

@@ -1,5 +1,5 @@
+import { type ConfigDDocumentName } from "./config-d-file.js";
 import { type MigrationReceipt } from "./one-time-migrations.js";
-import { type DomainName, type RetiredDomainName } from "./types.js";
 /** 注入的 I/O(本模块不碰 `node:fs`)。`writeFileAtomic` 必须原子(写临时文件再改名):半写的域文档比旧文档更糟。 */
 export interface ConfigDirectoryIo {
     readDir(path: string): Promise<string[]>;
@@ -43,12 +43,14 @@ export type ConfigDirectoryMigration = {
     readonly removed: readonly string[];
 };
 export interface MigrateConfigDirectoryOptions {
-    /** 覆盖面:调用方读的域名集(配置域或 retired 域)。拼错的名字 ⇒ 抛 `TypeError`,不让它悄悄变成「什么都没覆盖」。 */
-    readonly documents: readonly (DomainName | RetiredDomainName)[];
+    /** 覆盖面:调用方读的文档名集(配置域、retired 域,或 `remote-exec`)。拼错的名字 ⇒ 抛 `TypeError`,不让它悄悄变成「什么都没覆盖」。 */
+    readonly documents: readonly ConfigDirectoryDocument[];
     readonly io: ConfigDirectoryIo;
     /** 只判、不写:有改动且整域判得过 ⇒ `pending`。默认 `false`。 */
     readonly check?: boolean;
 }
+/** 目录迁移能读写的文档名:配置域、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

@@ -2,7 +2,8 @@
  * **一个 `config.d` 目录的一次性迁移** —— 「读目录 → 迁 → 整域终判 → 原子写 → 删 retired 域文件」这一条语义的唯一实现。命令行(`migrate <config.d 目录> [--check]`,
  * 见 `./cli`)是它的渲染器(退出码 + 报告行);引擎起服时对本地 `config.d` 的迁移调同一只函数,不按同语义自写一份。
  *
- * **覆盖面 = 调用方读的域名集**({@link MigrateConfigDirectoryOptions.documents}):覆盖面内没有的域文件就是从未设过(一次性迁移的 `coverage: "scope"`);
+ * **覆盖面 = 调用方读的文档名集**({@link MigrateConfigDirectoryOptions.documents}:配置域、retired 域,还可以是 `remote-exec` ——
+ * `config.d/remote-exec.json`,一次性迁移 SS-M7 的座位走查也读它;它与域文档同一条路:读 → 迁 → 改过的整文档终判 → 同一只写器写回):覆盖面内没有的域文件就是从未设过(一次性迁移的 `coverage: "scope"`);
  * 覆盖面外的文件不读、不判、不写、不删 —— 本调用方没有资格改写它从不消费的数据,它们是坏文件也挡不住覆盖面内的迁移。命令行的覆盖面是全部配置域加 retired 域;
  * 引擎的覆盖面是它本地读腿会读的那几份。**迁移不许越过覆盖面去写**:retired 的 `runtime` 域迁出时要写 `governance` 与 `limits`(`RUNTIME_LIFT_TARGETS`),
  * 覆盖面没把这两个域一并包进来时,目录算不上「一个 scope 的全集」—— 迁移按 `coverage: "partial"` 走(`runtime` 在那一支上以收据 `refused` 拒迁、一字不写),
@@ -22,10 +23,19 @@
  */
 import { z } from "zod";
 import { formatConfigPath, parseDomain } from "./config-fns.js";
-import { judgeConfigDText } 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;
+/** 改过的文档的整文档终判:域过读侧那一只 `parseDomain`,`remote-exec` 过 `loadRemoteExec` 那一只 `parseRemoteExecDocument`;retired 域不终判(它只会被删)。 */
+function judgeWholeDocument(name, doc) {
+    if (isDomainName(name))
+        parseDomain(name, doc);
+    else if (name === REMOTE_EXEC_DOCUMENT)
+        parseRemoteExecDocument(doc);
+}
 /** 目录加文件名(目录尾部的分隔符折掉)。包内私有(不进 `./node`)。 */
 export const joinDirPath = (dir, name) => `${dir.replace(/[\\/]+$/, "")}/${name}`;
 export function reportReceipt(r) {
@@ -63,10 +73,10 @@ function verdictOf(input, migrated, receipts) {
         return { kind: "noop" };
     const refused = [];
     for (const [name, doc] of Object.entries(migrated)) {
-        if (!isDomainName(name) || (Object.prototype.hasOwnProperty.call(input, name) && input[name] === doc))
+        if (Object.prototype.hasOwnProperty.call(input, name) && input[name] === doc)
             continue;
         try {
-            parseDomain(name, doc);
+            judgeWholeDocument(name, doc);
         }
         catch (err) {
             if (err instanceof z.ZodError)
@@ -89,8 +99,8 @@ const messageOf = (err) => (err instanceof Error ? err.message : String(err));
 export async function migrateConfigDirectory(dir, opts) {
     const covered = new Set();
     for (const name of opts.documents) {
-        if (!isDomainName(name) && !isRetiredDomainName(name))
-            throw new TypeError(`migrateConfigDirectory: "${String(name)}" is not a config domain or a retired domain — the coverage names the documents the caller reads`);
+        if (!isConfigDirectoryDocument(name))
+            throw new TypeError(`migrateConfigDirectory: "${String(name)}" is not a config domain, a retired domain or remote-exec — the coverage names the documents the caller reads`);
         covered.add(name);
     }
     const { io } = opts;
@@ -106,7 +116,7 @@ export async function migrateConfigDirectory(dir, opts) {
         if (name.startsWith(".") || !name.endsWith(".json"))
             continue;
         const base = name.slice(0, -".json".length);
-        if (!covered.has(base))
+        if (!covered.has(base) || !isConfigDirectoryDocument(base))
             continue;
         let text;
         try {
@@ -116,7 +126,7 @@ export async function migrateConfigDirectory(dir, opts) {
             return { kind: "unreadable", reason: `cannot read ${name}: ${messageOf(err)}` };
         }
         try {
-            docs[base] = judgeConfigDText(base, text); // the one config.d file judge: empty / whitespace / bad JSON / not an object ⇒ same sentence as FileConfigStore
+            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) };
@@ -154,7 +164,7 @@ export async function migrateConfigDirectory(dir, opts) {
     for (const [name, doc] of Object.entries(m.docs)) {
         if (Object.prototype.hasOwnProperty.call(docs, name) && docs[name] === doc)
             continue;
-        await io.writeFileAtomic(joinDirPath(dir, `${name}.json`), `${JSON.stringify(doc, null, 2)}\n`);
+        await io.writeFileAtomic(joinDirPath(dir, `${name}.json`), configDDocumentText(doc)); // the one config.d document text (writeDomainFile / writeRemoteExec write the same)
         written.push(`${name}.json`);
     }
     for (const name of Object.keys(docs)) {