@sema-agent/settings-schema 11.1.0 → 11.3.0

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

@@ -0,0 +1,89 @@
+{
+  "domains": {
+    "outcome": "rejected",
+    "stage": "validate"
+  },
+  "strictWrite": {
+    "outcome": "rejected",
+    "stage": "validate",
+    "why": "拒:example.com/acme/shared 已登记给前一个项目;坐标 projects.<后来者>.gitRemotes[1]。"
+  },
+  "wire": {
+    "outcome": "rejected",
+    "stage": "validate",
+    "why": "domains 腿是拒绝态,不派生;wire 腿把同一份文档交给同一个 buildEffective,拒绝层相同"
+  },
+  "localRoot": {
+    "outcome": "effective",
+    "effective": {
+      "collab": {
+        "templates": []
+      },
+      "entitlement": {
+        "budgetGroups": [],
+        "groupBindings": [],
+        "subjects": [],
+        "tiers": []
+      },
+      "execution": {
+        "allowedLanes": [
+          "host"
+        ],
+        "required": false
+      },
+      "governance": {},
+      "hosts": {
+        "hosts": []
+      },
+      "limits": {},
+      "mcp": {
+        "servers": []
+      },
+      "models": {
+        "atMention": {
+          "mode": "all"
+        },
+        "models": [],
+        "roles": {},
+        "tierGroups": []
+      },
+      "plugins": {
+        "plugins": []
+      },
+      "projects": {
+        "projects": {}
+      },
+      "prompts": {
+        "bindings": []
+      },
+      "rosters": {
+        "rosters": []
+      },
+      "scenarios": {
+        "scenarios": []
+      },
+      "skills": {
+        "skills": []
+      },
+      "systems": {
+        "systems": []
+      },
+      "workers": {
+        "workers": []
+      }
+    },
+    "warnings": [
+      {
+        "domain": "projects",
+        "file": "projects.json",
+        "kind": "unread-config-file",
+        "why": "non-portable-domain"
+      }
+    ],
+    "metadata": {
+      "version": 2617555914511015,
+      "updatedAt": "1970-01-01T00:00:00.000Z"
+    },
+    "why": "projects 不是便携域:config.d 腿不读它(T3),文件报 unread-config-file、域取默认"
+  }
+}

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/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;
-/** 原子写 `text`(UTF-8)到 `target`;模式按 `kind` 在 {@link 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

@@ -11,23 +11,61 @@
  *    **已有的文件沿用它原来的模式**(运维 chmod 过的文件不被一次写回覆盖)。
  *  · `scheduler-store` —— 调度店耐久记录(可能带 principal / session 标识):新建 = 0o600,且**每次写都回到 0o600**(已有的更宽的文件被收回)。
  * 新建的模式照常经进程 umask 遮一道(`writeFile` 的 `mode` 语义):比表更严的 umask 只会更严,不会被这里放宽;沿用的模式原样恢复(不再过 umask)。
+ *
+ * ## 目标是符号链接
+ * 域文件可以是符号链接 —— 运维用链接把 `config.d` 指到别处管理的部署,那是有意的布局,写器不替他改布局。规则一条:**先把目标解析到真文件(`realpath`),
+ * 临时文件建在真文件所在目录、rename 到真文件**:链接(及链上每一环)原样保留,真文件的内容更新,模式规则作用在真文件上。临时文件与目标同目录 ⇒ rename 不会跨文件系统;
+ * 真文件所在目录写不进、或 rename 因别的原因失败 ⇒ 响亮抛,**绝不**回退成「在链接位置写一个普通文件」(那是静默换形)。路径本身是悬空链接 ⇒ 响亮抛
+ * (不在链接位置建普通文件,也不替链接建它指向的文件);成环的链接由 `realpath` 抛 `ELOOP`。目标不存在 ⇒ 新建(没有链接可言;经符号链接的目录写新文件时,文件落在真目录里)。
+ * 「链接 ⇒ 真文件、悬空 ⇒ 响亮抛」这一只判法是 {@link resolveSymlinkTarget}:目录迁移的读口(`./config-dir-io`)读目录 / 读文件前也问它,
+ * 悬空链接在读阶段与写阶段是**同一句**({@link danglingSymlinkSentence})。
  */
 import { randomBytes } from "node:crypto";
-import { chmodSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { chmodSync, lstatSync, readlinkSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import path from "node:path";
 /** 按文档类的模式表(闭集)。 */
 export const ATOMIC_FILE_CLASSES = {
     "config-document": { newMode: 0o644, existing: "keep" },
     "scheduler-store": { newMode: 0o600, existing: "reset" },
 };
-/** 原子写 `text`(UTF-8)到 `target`;模式按 `kind` 在 {@link ATOMIC_FILE_CLASSES} 里的行。父目录须已存在。 */
+/** 悬空符号链接的**唯一一句**(写器与目录迁移的读口抛同一句;不带 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();
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return target; // 不存在:新建
+        throw e;
+    }
+    if (!link)
+        return target;
+    try {
+        return realpathSync(target);
+    }
+    catch (e) {
+        if (e.code === "ENOENT") {
+            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 = resolveSymlinkTarget(target);
     const spec = ATOMIC_FILE_CLASSES[kind];
     let kept; // the existing file's mode, when this class keeps it
     switch (spec.existing) {
         case "keep":
             try {
-                kept = statSync(target).mode & 0o777;
+                kept = statSync(real).mode & 0o777;
             }
             catch (e) {
                 if (e.code !== "ENOENT")
@@ -41,12 +79,12 @@ export function writeFileAtomic(target, text, kind) {
             throw new Error(`writeFileAtomic: unhandled existing-file rule ${String(unhandled)}`);
         }
     }
-    const tmp = path.join(path.dirname(target), `.${path.basename(target)}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`);
+    const tmp = path.join(path.dirname(real), `.${path.basename(real)}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`);
     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)
-        renameSync(tmp, target);
+        renameSync(tmp, real);
     }
     catch (e) {
         try {

package/dist/cli.d.ts

@@ -1,10 +1,38 @@
-/** 入口注入的 I/O(核心不碰 node:fs)。`writeFileAtomic` 必须原子(写临时文件再改名):半写的域文档比旧文档更糟;入口注入的就是 `./atomic-write` 的那一只。 */
-export interface SettingsSchemaCliIo {
-    readDir(path: string): Promise<string[]>;
-    readFile(path: string): Promise<string>;
-    writeFileAtomic(path: string, text: string): Promise<void>;
-    removeFile(path: string): Promise<void>;
+/**
+ * `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 域与 `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`
+ * (一次性迁移 SS-M7 的座位走查也走它的两个端点);别的文件(隐藏文件、不认识的名、非 `.json`)不读不动。
+ *
+ * 零域文档分两形:**有条目却没有域文档**(任何非 `.` 开头的条目 —— 子目录、说明文件、不认识的名)⇒ 退出 2;**目录真空**(零条目,或只有以 `.` 开头的条目)⇒ 照常走判定,
+ * 零收据 = noop 退出 0 —— 新部署的空 `config.d` 是合法态,「没有东西可迁」不是「指错目录」(搬空之后再跑同一目录也因此幂等)。
+ *
+ * 退出码:0 = 已写回 / 无事可做(目录里有域文档只是没有要改的,或目录真空);1 = 有迁不了的坐标(收据 `refused`)**或**要写回的域文档整域读不进(整域终判,见 `migrateConfigDirectory`),**一字不写**;
+ * 2 = 用法错,或**环境错**(读目录 / 读文件 / 写盘 / 删文件的 I/O 错:权限、磁盘、悬空符号链接 …;stdout 空、stderr 一行点名路径与错误(errno 码在 Node 的错误句里),不打栈 ——
+ * rc 1 是「拒迁」的约定码,不许被一个权限错冒充),或某个域文件是坏文件(空 / 纯空白 / 坏 JSON / 不是 JSON 对象 —— 与 `FileConfigStore` 同一只判、同一句),**或目录里有条目却没有一个是域文档**
+ * (多半是填错了目录:要的是 `config.d` 目录本身;`<目录>/config.d` 在场时句子直接点它)(此时 stdout 为空);3 = `--check` 且会有改动、整域判得过(不写)。`--check` 与真跑过同一只判定,只在
+ * 「有改动、且整域判得过」那一支上分开(pending vs applied)—— 整域会被拒的目录 `--check` 也报 refused / rc 1。
+ *
+ * ## 报告形(让「没写」在机读上不可能被读成「写了」)
+ * 退出码 0 / 1 / 3 时 stdout 恰两行:第 1 行 = **唯一结论行** `outcome=<refused|applied|noop|pending> written=<true|false>`;第 2 行 = JSON 报告
+ * (`event: "stored_documents_migrated"`,逐条收据只点名坐标与处置、不带值),同带 `outcome` / `written`。`written` 由 `outcome` 派生
+ * (只有 `applied` 写盘)。**键名带时态**:`written=true` 才有 `applied`;没写(refused / noop / pending)时是 `wouldApply`。
+ * 结论行在**写盘成功之后**才出(写盘抛错 ⇒ 没有 `outcome=applied`)。写盘次序:先写改过 / 新建的文件,最后删被移除的 retired 域文件 ——
+ * 中途断掉再跑一次,迁移照样恒等收尾(已搬过去的值在新位上,旧文件里同名键按「新位赢」丢弃)。
+ */
+import { type ConfigDirectoryIo } from "./config-dir-migration.js";
+/** 入口注入的 I/O(核心不碰 node:fs):目录迁移的四个口加 stdout / stderr。入口注入的写盘是 `./atomic-write` 的那一只(经 `./config-dir-io`)。 */
+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

@@ -1,19 +1,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 域与 `remote-exec.json`。
  * 目录被当作**一个 scope 的全集**(`coverage: "scope"`):目录里没有的域文件就是从未设过。
  *
- * 本模块不碰 `node:fs`:读写文件由入口 `bin/settings-schema.mjs` 注入(写盘用的是 `./atomic-write` 那一只原子写器 —— 写法与文件模式在那里一处定),所以测试可以直接驱动它。
+ * 本模块不碰 `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`)**或**要写回的域文档整域读不进(整域终判,见 {@link verdictOf}),**一字不写**;
- * 2 = 用法 / 读目录 / 读文件错,或某个域文件是坏文件(空 / 纯空白 / 坏 JSON / 不是 JSON 对象 —— 与 `FileConfigStore` 同一只判、同一句),**或目录里有条目却没有一个是域文档**
+ * 退出码:0 = 已写回 / 无事可做(目录里有域文档只是没有要改的,或目录真空);1 = 有迁不了的坐标(收据 `refused`)**或**要写回的域文档整域读不进(整域终判,见 `migrateConfigDirectory`),**一字不写**;
+ * 2 = 用法错,或**环境错**(读目录 / 读文件 / 写盘 / 删文件的 I/O 错:权限、磁盘、悬空符号链接 …;stdout 空、stderr 一行点名路径与错误(errno 码在 Node 的错误句里),不打栈 ——
+ * rc 1 是「拒迁」的约定码,不许被一个权限错冒充),或某个域文件是坏文件(空 / 纯空白 / 坏 JSON / 不是 JSON 对象 —— 与 `FileConfigStore` 同一只判、同一句),**或目录里有条目却没有一个是域文档**
  * (多半是填错了目录:要的是 `config.d` 目录本身;`<目录>/config.d` 在场时句子直接点它)(此时 stdout 为空);3 = `--check` 且会有改动、整域判得过(不写)。`--check` 与真跑过同一只判定,只在
  * 「有改动、且整域判得过」那一支上分开(pending vs applied)—— 整域会被拒的目录 `--check` 也报 refused / rc 1。
  *
@@ -21,22 +24,23 @@
  * 退出码 0 / 1 / 3 时 stdout 恰两行:第 1 行 = **唯一结论行** `outcome=<refused|applied|noop|pending> written=<true|false>`;第 2 行 = JSON 报告
  * (`event: "stored_documents_migrated"`,逐条收据只点名坐标与处置、不带值),同带 `outcome` / `written`。`written` 由 `outcome` 派生
  * (只有 `applied` 写盘)。**键名带时态**:`written=true` 才有 `applied`;没写(refused / noop / pending)时是 `wouldApply`。
- * 结论行在**写盘成功之后**才出(写盘抛错 ⇒ 没有 `outcome=applied`)。写盘次序:先写改过 / 新建的文件,最后删被移除的retired 域文件 ——
+ * 结论行在**写盘成功之后**才出(写盘抛错 ⇒ 没有 `outcome=applied`)。写盘次序:先写改过 / 新建的文件,最后删被移除的 retired 域文件 ——
  * 中途断掉再跑一次,迁移照样恒等收尾(已搬过去的值在新位上,旧文件里同名键按「新位赢」丢弃)。
  */
-import { z } from "zod";
-import { formatConfigPath, parseDomain } from "./config-fns.js";
-import { judgeConfigDText } from "./config-d-file.js";
-import { migrateStoredDocuments } from "./one-time-migrations.js";
-import { MIGRATE_COMMAND } from "./retired-form.js";
-import { isDomainName, isRetiredDomainName } from "./types.js";
+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 { DOMAINS, RETIRED_DOMAINS } from "./types.js";
+/** 命令行的覆盖面:全部配置域、retired 域(便携与否不论 —— 离线的 `workers.json` 一样迁)与 `remote-exec.json`。 */
+export const COVERED_DOCUMENTS = [...DOMAINS, ...Object.keys(RETIRED_DOMAINS), REMOTE_EXEC_DOCUMENT];
 const USAGE = [
-    `usage: ${MIGRATE_COMMAND} <config.d directory> [--check]`,
-    "  Runs the one-time migrations (@sema-agent/settings-schema/one-time-migrations) over every <domain>.json in the directory, read as one",
+    `usage: ${MIGRATE_COMMAND_TEMPLATE} [--check]`,
+    "  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");
@@ -55,61 +59,6 @@ function writtenOf(outcome) {
         }
     }
 }
-/** 报告里的一张收据(坐标出门形;不带值)。 */
-function reportReceipt(r) {
-    const base = { migration: r.migration, document: r.document, path: formatConfigPath(r.path), appliedAs: r.appliedAs };
-    switch (r.appliedAs) {
-        case "moved":
-            return { ...base, to: `${r.to.document}:${formatConfigPath(r.to.path)}` };
-        case "refused":
-            return { ...base, reason: r.reason };
-        case "rewritten":
-        case "dropped-shadowed":
-        case "dropped-inert":
-            return base;
-        default: {
-            const unhandled = r;
-            throw new Error(`settings-schema: unhandled receipt ${JSON.stringify(unhandled)}`);
-        }
-    }
-}
-/** 整域终判的一条拒(issue 来自 `parseDomain`,已过本包唯一的脱敏器 —— 坐标段与句子都是出门形)。 */
-function wholeDomainRefusal(document, path, reason) {
-    return { migration: null, document, path: formatConfigPath(path), appliedAs: "refused", reason };
-}
-/**
- * 迁移结果 → 结论。顺序:迁移步拒 → 无改动 ⇒ noop → **整域终判**(要写回的每个域文档 —— 改过的、新建的 —— 过读侧那一只
- * `parseDomain`:名字 / 路由唯一这类跨行规则只有整域判得出)→ 有改动。整域终判在 `--check` 之前:否则同一个目录 `--check` 报 pending、
- * 真跑写出一份读侧必拒的文档。没改的文件不归这里判(迁移不碰它,它读不读得进是读者的事)。
- */
-function verdictOf(input, migrated, receipts) {
-    const refusedReceipts = receipts.filter((r) => r.appliedAs === "refused");
-    if (refusedReceipts.length > 0) {
-        return { kind: "refused", refused: refusedReceipts.map(reportReceipt), why: `${refusedReceipts.length} coordinate(s) cannot be migrated (see "refused") — fix them by hand and re-run` };
-    }
-    if (receipts.length === 0)
-        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))
-            continue;
-        try {
-            parseDomain(name, doc);
-        }
-        catch (err) {
-            if (err instanceof z.ZodError)
-                for (const i of err.issues)
-                    refused.push(wholeDomainRefusal(name, i.path, i.message));
-            else
-                refused.push(wholeDomainRefusal(name, [], err instanceof Error ? err.message : String(err)));
-        }
-    }
-    if (refused.length > 0) {
-        const documents = [...new Set(refused.map((r) => String(r.document)))];
-        return { kind: "refused", refused, why: `the migrated ${documents.join(" / ")} document(s) do not read as a whole domain (see "refused") — fix them by hand and re-run` };
-    }
-    return { kind: "changes" };
-}
 /** 一次发出报告:结论行 + JSON 行(一次 `stdout` 调用)。 */
 function reportOf(outcome, dir, applied, refused) {
     const written = writtenOf(outcome);
@@ -118,18 +67,46 @@ function reportOf(outcome, dir, applied, refused) {
         outcome,
         written,
         dir,
-        [written ? "applied" : "wouldApply"]: applied.map(reportReceipt),
+        [written ? "applied" : "wouldApply"]: applied.map((r) => reportReceipt(r)),
         refused,
     });
     return `outcome=${outcome} written=${written}\n${json}\n`;
 }
-const join = (dir, name) => `${dir.replace(/[\\/]+$/, "")}/${name}`;
-/** 「有条目却没有域文档」的拒句:点名这个目录、说要的是 `config.d` 目录本身;`<dir>/config.d` 在场(探一次)就直接点它 —— 最常见的错是填了它的上一层。 */
+/** 写回阶段(写盘 / 删文件)的一次 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},句子点名**要写的那份文件**(原子写器的错误句里是临时文件的路径)与原错误句。
+ *  读口不包:读目录 / 读文件错由 `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(`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 = join(dir, "config.d");
+    const nested = joinDirPath(dir, "config.d");
     const nestedExists = await io.readDir(nested).then(() => true, () => false);
     const base = `settings-schema: no domain documents in ${dir} (a domain document is <domain>.json, e.g. models.json) — the argument is the config.d directory itself`;
-    return nestedExists ? `${base}; ${nested} exists — run: ${MIGRATE_COMMAND} ${nested}` : base;
+    return nestedExists ? `${base}; ${nested} exists — run: ${migrateCommandFor(nested)}` : base;
 }
 export async function runSettingsSchemaCli(argv, io) {
     const [command, ...rest] = argv;
@@ -140,73 +117,46 @@ export async function runSettingsSchemaCli(argv, io) {
         io.stderr(`${USAGE}\n`);
         return 2;
     }
-    let names;
+    let m;
     try {
-        names = await io.readDir(dir);
+        m = await migrateConfigDirectory(dir, { documents: COVERED_DOCUMENTS, io: withEnvironmentArm(io), check });
     }
     catch (err) {
-        io.stderr(`settings-schema: cannot read directory ${dir}: ${err instanceof Error ? err.message : String(err)}\n`);
+        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`);
         return 2;
     }
-    const docs = {};
-    for (const name of [...names].sort()) {
-        if (name.startsWith(".") || !name.endsWith(".json"))
-            continue;
-        const base = name.slice(0, -".json".length);
-        if (!isDomainName(base) && !isRetiredDomainName(base))
-            continue;
-        let text;
-        try {
-            text = await io.readFile(join(dir, name));
-        }
-        catch (err) {
-            io.stderr(`settings-schema: cannot read ${name}: ${err instanceof Error ? err.message : String(err)}\n`);
-            return 2;
-        }
-        try {
-            docs[base] = judgeConfigDText(base, text); // the one config.d file judge: empty / whitespace / bad JSON / not an object ⇒ same sentence as FileConfigStore
-        }
-        catch (err) {
-            io.stderr(`settings-schema: ${err instanceof Error ? err.message : String(err)}\n`);
+    switch (m.kind) {
+        case "unreadable":
+            io.stderr(`settings-schema: ${oneLine(m.reason)}\n`);
             return 2;
-        }
-    }
-    if (Object.keys(docs).length === 0 && names.some((name) => !name.startsWith("."))) {
-        // The directory has entries and none of them is a domain document: a no-op report (rc 0) would read as "this scope is migrated" for a
-        // directory the command never looked into. A directory with nothing visible in it (empty, or only dot entries) is a legitimate scope.
-        io.stderr(`${await noDomainDocumentsSentence(dir, io)}\n`);
-        return 2;
-    }
-    const m = migrateStoredDocuments(docs, { coverage: "scope" });
-    const applied = m.receipts.filter((r) => r.appliedAs !== "refused");
-    const verdict = verdictOf(docs, m.docs, m.receipts);
-    switch (verdict.kind) {
+        case "no-documents":
+            if (m.entries.some((name) => !name.startsWith("."))) {
+                // The directory has entries and none of them is a domain document: a no-op report (rc 0) would read as "this scope is migrated" for a
+                // directory the command never looked into. A directory with nothing visible in it (empty, or only dot entries) is a legitimate scope.
+                io.stderr(`${await noDomainDocumentsSentence(dir, io)}\n`);
+                return 2;
+            }
+            io.stdout(reportOf("noop", dir, [], []));
+            return 0;
         case "refused":
-            io.stdout(reportOf("refused", dir, applied, verdict.refused));
-            io.stderr(`settings-schema: ${verdict.why}; nothing was written\n`);
+            io.stdout(reportOf("refused", dir, m.applied, m.refused));
+            io.stderr(`settings-schema: ${m.why}; nothing was written\n`);
             return 1;
         case "noop":
             io.stdout(reportOf("noop", dir, [], []));
             return 0;
-        case "changes":
-            break;
+        case "pending":
+            io.stdout(reportOf("pending", dir, m.applied, []));
+            return 3;
+        case "applied":
+            io.stdout(reportOf("applied", dir, m.applied, [])); // 写盘成功之后才报 applied
+            return 0;
         default: {
-            const unhandled = verdict;
-            throw new Error(`settings-schema: unhandled verdict ${JSON.stringify(unhandled)}`);
+            const unhandled = m;
+            throw new Error(`settings-schema: unhandled migration result ${JSON.stringify(unhandled)}`);
         }
     }
-    if (check) {
-        io.stdout(reportOf("pending", dir, applied, []));
-        return 3;
-    }
-    for (const [name, doc] of Object.entries(m.docs)) {
-        if (Object.prototype.hasOwnProperty.call(docs, name) && docs[name] === doc)
-            continue;
-        await io.writeFileAtomic(join(dir, `${name}.json`), `${JSON.stringify(doc, null, 2)}\n`);
-    }
-    for (const name of Object.keys(docs))
-        if (!Object.prototype.hasOwnProperty.call(m.docs, name))
-            await io.removeFile(join(dir, `${name}.json`));
-    io.stdout(reportOf("applied", dir, applied, [])); // 写盘成功之后才报 applied
-    return 0;
 }

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

@@ -1,4 +1,15 @@
+import { 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/<名>.json` 在场时的**文本** → 它的值(纯判,零 I/O;见文件头的律):一个 JSON 对象 ⇒ 它;空 / 纯空白、坏 JSON、