@sema-agent/settings-schema 11.2.0 → 11.3.0

package/dist/cli.d.ts

@@ -2,20 +2,21 @@
  * `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 码在 Node 的错误句里),不打栈 ——
+ * rc 1 是「拒迁」的约定码,不许被一个权限错冒充),或某个域文件是坏文件(空 / 纯空白 / 坏 JSON / 不是 JSON 对象 —— 与 `FileConfigStore` 同一只判、同一句),**或目录里有条目却没有一个是域文档**
  * (多半是填错了目录:要的是 `config.d` 目录本身;`<目录>/config.d` 在场时句子直接点它)(此时 stdout 为空);3 = `--check` 且会有改动、整域判得过(不写)。`--check` 与真跑过同一只判定,只在
  * 「有改动、且整域判得过」那一支上分开(pending vs applied)—— 整域会被拒的目录 `--check` 也报 refused / rc 1。
  *
@@ -32,4 +33,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,21 @@
  * `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 码在 Node 的错误句里),不打栈 ——
+ * rc 1 是「拒迁」的约定码,不许被一个权限错冒充),或某个域文件是坏文件(空 / 纯空白 / 坏 JSON / 不是 JSON 对象 —— 与 `FileConfigStore` 同一只判、同一句),**或目录里有条目却没有一个是域文档**
  * (多半是填错了目录:要的是 `config.d` 目录本身;`<目录>/config.d` 在场时句子直接点它)(此时 stdout 为空);3 = `--check` 且会有改动、整域判得过(不写)。`--check` 与真跑过同一只判定,只在
  * 「有改动、且整域判得过」那一支上分开(pending vs applied)—— 整域会被拒的目录 `--check` 也报 refused / rc 1。
  *
@@ -28,16 +29,18 @@
  */
 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` 一样迁)。 */
-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 +72,35 @@ 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},句子点名**要写的那份文件**(原子写器的错误句里是临时文件的路径)与原错误句。
+ *  读口不包:读目录 / 读文件错由 `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 = joinDirPath(dir, "config.d");
@@ -85,10 +117,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; fix the cause and re-run\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,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、

package/dist/config-d-file.js

@@ -9,8 +9,42 @@
  */
 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 { 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) {
+    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))

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,4 +1,5 @@
 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 {
@@ -43,12 +44,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`)。 */
+export type ConfigDirectoryDocument = DomainName | RetiredDomainName | typeof REMOTE_EXEC_DOCUMENT;
 /** 目录加文件名(目录尾部的分隔符折掉)。包内私有(不进 `./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,23 @@
  */
 import { z } from "zod";
 import { formatConfigPath, parseDomain } from "./config-fns.js";
-import { judgeConfigDText } from "./config-d-file.js";
+import { configDDocumentText, judgeConfigDText, judgeRemoteExecText, 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))
+        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 +77,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 +103,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 +120,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 +130,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] = judgeDocumentText(dir, base, text); // the one judge per document kind: a domain file's is FileConfigStore's, remote-exec.json's is loadRemoteExec's
         }
         catch (err) {
             return { kind: "unreadable", reason: messageOf(err) };
@@ -154,7 +168,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)) {

package/dist/cross-domain.d.ts

@@ -12,6 +12,7 @@
  */
 import type { ConfigReader } from "./reader.js";
 import type { DomainConfig } from "./types.js";
+import { type QuotedIssueParams } from "./quoted-issue.js";
 /** What a dangling reference failed to find —— the closed set (S-1075, 11.0.0): one word per referenced domain. */
 export declare const REF_ISSUE_KINDS: readonly ["unknown_model", "unknown_roster", "unknown_worker", "unknown_skill", "unknown_mcp", "unknown_plugin"];
 export type RefIssueKind = (typeof REF_ISSUE_KINDS)[number];
@@ -37,7 +38,9 @@ export interface RefReferrer {
  *  holds the reference), `target` (the name that was not found), `path` (where the reference sits; `path[0]` = the referrer's
  *  domain key). `message` is {@link renderRefIssue} of them — a reader that must treat the user-written values differently from
  *  the sentence's fixed words (a log boundary fingerprinting each value) re-renders with its own `show` instead of parsing the
- *  sentence. Before 11.0.0 the values were only inside `message`. */
+ *  sentence. Before 11.0.0 the values were only inside `message`. `params` is the same sentence in the form every custom
+ *  issue of this package carries (`QuotedIssueParams`: fixed words + the two values as operands) —— a reader that reads custom issues one
+ *  way reads this one the same way. */
 export interface RefIssue {
     path: (string | number)[];
     code: "custom";
@@ -45,10 +48,12 @@ export interface RefIssue {
     referrer: RefReferrer;
     target: string;
     message: string;
+    params: QuotedIssueParams;
 }
 /** The ONE rendering of a {@link RefIssue}'s sentence: `<referrer> → unknown <noun> "<target>" (at <path>)`. `show` maps each
- *  user-written value (the referrer's name, the target); the default shows them as written — that is how `message` is minted. */
-export declare function renderRefIssue(issue: Omit<RefIssue, "message">, show?: (value: string) => string): string;
+ *  user-written value (the referrer's name, the target); the default shows them as written — that is how `message` is minted.
+ *  It renders {@link refIssueSentence}'s params through `renderQuotedSentence` (the one renderer of every custom issue's sentence). */
+export declare function renderRefIssue(issue: Omit<RefIssue, "message" | "params">, show?: (value: string) => string): string;
 /** Resolve a sibling domain's effective value for integrity checks. */
 export type SiblingResolver = <K extends keyof DomainConfig>(domain: K) => Promise<DomainConfig[K] | undefined>;
 /** A resolver over the reader, optionally shadowed by pending (same-operation) writes keyed by domain.

package/dist/cross-domain.js

@@ -1,4 +1,5 @@
 import { formatConfigPath } from "./config-fns.js";
+import { buildQuotedIssue, fixed, renderQuotedSentence } from "./quoted-issue.js";
 /** What a dangling reference failed to find —— the closed set (S-1075, 11.0.0): one word per referenced domain. */
 export const REF_ISSUE_KINDS = ["unknown_model", "unknown_roster", "unknown_worker", "unknown_skill", "unknown_mcp", "unknown_plugin"];
 /** The domain a {@link RefIssueKind}'s target lives in. */
@@ -29,33 +30,42 @@ function refTargetNoun(kind) {
             return "plugin";
     }
 }
-/** How a referrer is named in the sentence (its name through `show`). */
-function refReferrerLabel(r, show) {
-    const named = (noun) => (r.name === undefined ? noun : `${noun} "${show(r.name)}"`);
+/** How a referrer is named in the sentence: the noun for its domain (its own name, when it has one, follows as an operand). */
+function refReferrerNoun(r) {
     switch (r.domain) {
         case "rosters":
-            return named("roster");
+            return "roster";
         case "workers":
-            return named("worker");
+            return "worker";
         case "models":
-            return named("models");
+            return "models";
         case "collab":
-            return named("collab template");
+            return "collab template";
         case "systems":
-            return named("system");
+            return "system";
         case "entitlement":
-            return named("tier");
+            return "tier";
     }
 }
+/** A {@link RefIssue}'s sentence —— THE one sentence builder (`<referrer> → unknown <noun> "<target>" (at <path>)`): the referrer's name and
+ *  the target are operands, everything else (nouns, the coordinate) is fixed text. `message`, `params` and {@link renderRefIssue} all come from it. */
+function refIssueSentence(issue) {
+    const noun = refReferrerNoun(issue.referrer);
+    const at = formatConfigPath(issue.path);
+    return issue.referrer.name === undefined
+        ? buildQuotedIssue `${fixed(noun)} → unknown ${fixed(refTargetNoun(issue.kind))} "${issue.target}" (at ${fixed(at)})`
+        : buildQuotedIssue `${fixed(noun)} "${issue.referrer.name}" → unknown ${fixed(refTargetNoun(issue.kind))} "${issue.target}" (at ${fixed(at)})`;
+}
 /** The ONE rendering of a {@link RefIssue}'s sentence: `<referrer> → unknown <noun> "<target>" (at <path>)`. `show` maps each
- *  user-written value (the referrer's name, the target); the default shows them as written — that is how `message` is minted. */
+ *  user-written value (the referrer's name, the target); the default shows them as written — that is how `message` is minted.
+ *  It renders {@link refIssueSentence}'s params through `renderQuotedSentence` (the one renderer of every custom issue's sentence). */
 export function renderRefIssue(issue, show = (v) => v) {
-    return `${refReferrerLabel(issue.referrer, show)} → unknown ${refTargetNoun(issue.kind)} "${show(issue.target)}" (at ${formatConfigPath(issue.path)})`;
+    return renderQuotedSentence(refIssueSentence(issue).params, (operand) => show(String(operand)));
 }
 /** The one minting point of a {@link RefIssue}. */
 function danglingRef(path, kind, referrer, target) {
-    const operands = { path, code: "custom", kind, referrer, target };
-    return { ...operands, message: renderRefIssue(operands) };
+    const sentence = refIssueSentence({ path, kind, referrer, target });
+    return { path, code: "custom", kind, referrer, target, ...sentence };
 }
 /** A resolver over the reader, optionally shadowed by pending (same-operation) writes keyed by domain.
  *  Widened from the fat ConfigStore to the narrow {@link ConfigReader} (it only calls `getDomain`) so a TOC

package/dist/file-edit.js

@@ -9,7 +9,9 @@ import { mkdir } from "node:fs/promises";
 import path from "node:path";
 import { writeFileAtomic } from "./atomic-write.js";
 import { collectEnvRefs } from "./secret-refs.js";
-import { RemoteExecSpec } from "./remote-exec.js";
+import { REMOTE_EXEC_DOCUMENT, RemoteExecSpec } from "./remote-exec.js";
+import { configDDocumentText } from "./config-d-file.js";
+import { buildQuotedIssue, fixed } from "./quoted-issue.js";
 import { RetiredDomainError, parseDomain, sanitizeZodError } from "./config-fns.js";
 import { DOMAIN_SCHEMAS, isDomainName, isRetiredDomainName } from "./types.js";
 /** Throw a CLEAR error for a non-domain key instead of the cryptic `undefined.parse(...)` you'd get from
@@ -21,7 +23,7 @@ function assertDomainName(domain) {
     if (isRetiredDomainName(domain))
         throw new RetiredDomainError(domain);
     if (!isDomainName(domain)) {
-        const hint = domain === "remote-exec" ? " — the exec backend is NOT a domain; use writeRemoteExec (config.d/remote-exec.json)" : "";
+        const hint = domain === REMOTE_EXEC_DOCUMENT ? " — the exec backend is NOT a domain; use writeRemoteExec (config.d/remote-exec.json)" : "";
         throw new Error(`"${domain}" is not a config domain (expected one of: ${DOMAINS_LIST})${hint}`);
     }
 }
@@ -37,7 +39,7 @@ export function validateDomain(domain, raw) {
     }
     catch {
         // a hostile getter/Proxy trap threw during traversal — never surface its (secret-bearing) message. R13.
-        return { ok: false, issues: [{ code: "custom", message: `invalid "${domain}" config (a value could not be read during validation)`, path: [] }] };
+        return { ok: false, issues: [{ code: "custom", ...buildQuotedIssue `invalid "${fixed(domain)}" config (a value could not be read during validation)`, path: [] }] };
     }
     if (r.success)
         return { ok: true, value: r.data };
@@ -50,7 +52,7 @@ export function validateRemoteExec(raw) {
         r = RemoteExecSpec.safeParse(raw);
     }
     catch {
-        return { ok: false, issues: [{ code: "custom", message: "invalid remoteExec (a value could not be read during validation)", path: [] }] };
+        return { ok: false, issues: [{ code: "custom", ...buildQuotedIssue `invalid remoteExec (a value could not be read during validation)`, path: [] }] };
     }
     return r.success ? { ok: true, value: r.data } : { ok: false, issues: sanitizeZodError(r.error).issues }; // no secret echo (R14)
 }
@@ -68,7 +70,7 @@ export async function writeDomainFile(root, domain, value) {
     const parsed = parseDomain(domain, value); // routes through the SANITIZED parser (explicit-null reject R4 + no secret echo R14)
     const dir = path.join(root, "config.d");
     await mkdir(dir, { recursive: true });
-    writeFileAtomic(path.join(dir, `${domain}.json`), JSON.stringify(parsed, null, 2) + "\n", "config-document");
+    writeFileAtomic(path.join(dir, `${domain}.json`), configDDocumentText(parsed), "config-document");
     return parsed;
 }
 /** LIST every env-NAME the current local config requires (across models/workers/mcp + the

package/dist/file-store.js

@@ -29,6 +29,7 @@ import path from "node:path";
 import { buildEffective, DOMAIN_READ_FALLBACK, parseDomainLoud } from "./config-fns.js";
 import { configDPath, readConfigDFile, refuseRetiredDomainFiles } from "./config-d-file.js";
 import { stableHash } from "./hash.js";
+import { REMOTE_EXEC_DOCUMENT } from "./remote-exec.js";
 import { RETIRED_DOMAINS, isDomainName, isRetiredDomainName } from "./types.js";
 /** The retired domain names (`RETIRED_DOMAINS` keys) — read from `config.d/` for their tombstone only. */
 const RETIRED_DOMAIN_NAMES = Object.keys(RETIRED_DOMAINS);
@@ -53,7 +54,7 @@ export const PORTABLE_DOMAINS = ["models", "rosters", "skills", "mcp", "plugins"
  *
  *  **导出**(3.0.0):一致性门的语料派生要按同一张表给本地腿的文件分类(域文件 / 专用文件 / 忽略),
  *  手抄一份必漂 —— 漂了的那一天,门会把一个合法的 `remote-exec.json` 报成未知文件。 */
-export const NON_DOMAIN_CONFIG_FILES = new Set(["remote-exec.json"]);
+export const NON_DOMAIN_CONFIG_FILES = new Set([`${REMOTE_EXEC_DOCUMENT}.json`]);
 /**
  * 非便携域的**排除理由表**(#282 件5 附带裁定:禁裸排除)。
  *

package/dist/fleet.js

@@ -20,6 +20,7 @@
 import { z } from "zod";
 import { INTEGER } from "./integer.js";
 import { fnv1a64 } from "./hash.js";
+import { buildQuotedIssue } from "./quoted-issue.js";
 // ── Web-admin's fleet endpoints (paths, one spelling) ─────────────────────────────────────────────────────
 /**
  * Web-admin's `/api/fleet/*` endpoints that are addressed from outside web-admin, relative to its origin. ONE spelling: whoever
@@ -115,7 +116,7 @@ export function compareGeneration(a, b) {
     return a === b ? 0 : a < b ? -1 : 1;
 }
 /** The generation field of every wire shape that carries one — a string judged by {@link isCanonicalGeneration}. */
-const Generation = z.string().refine(isCanonicalGeneration, { message: "a generation is a canonical non-negative decimal string (no sign, no leading zero)" });
+const Generation = z.string().refine(isCanonicalGeneration, buildQuotedIssue `a generation is a canonical non-negative decimal string (no sign, no leading zero)`);
 /**
  * The serving lease as the ENGINE holds it — a CLOSED set of four words, owned here (the engine's vocabulary, word for word;
  * a reader that switches on it exhaustively is told by the compiler when a word is added):
@@ -271,9 +272,7 @@ export const ModelRefusalsWire = z
     entries: z.record(z.string().min(1), z.string().min(1)),
     plane: z.string().min(1).optional(),
 })
-    .refine((s) => Object.keys(s.entries).length > 0 || s.plane !== undefined, {
-    message: "an empty model-refusals signal is not a signal — omit the key instead (absent ⇔ no reportable refusals)",
-});
+    .refine((s) => Object.keys(s.entries).length > 0 || s.plane !== undefined, buildQuotedIssue `an empty model-refusals signal is not a signal — omit the key instead (absent ⇔ no reportable refusals)`);
 const isModelEntryRefusalCode = (c) => MODEL_ENTRY_REFUSAL_CODES.includes(c);
 const isModelPlaneRefusalCode = (c) => MODEL_PLANE_REFUSAL_CODES.includes(c);
 /**

package/dist/hooks.d.ts

@@ -2267,9 +2267,22 @@ export type HookMatcherEntry = z.infer<typeof HookMatcherEntry>;
  *    for the bad matcher itself.
  * Before 11.0.0 the server anchored the regex form (`^(?:…)$`) while the shell did not, so one regex matcher selected different
  * tools in the two places. A deployment whose regex matchers relied on that anchoring selects MORE tools now — add `^…$`.
- * Pure: no budget / timeout — a caller evaluating untrusted regex matchers under a deadline does so around this call.
+ * Pure: no budget / timeout — a caller evaluating untrusted regex matchers under a deadline does so around this call
+ * ({@link hookMatcherForm} tells it beforehand which matchers run a regex at all).
  */
 export declare function hookMatcherSelects(matcher: string | undefined, name: string): boolean | "invalid";
+/** The form of a hooks matcher under {@link hookMatcherSelects}' reading (closed set). */
+export type HookMatcherForm = "literal" | "regex" | "invalid";
+/**
+ * Which form `matcher` takes under the one reading —— the same parse step as {@link hookMatcherSelects}, so for every
+ * matcher `hookMatcherForm(m) === "invalid"` ⇔ `hookMatcherSelects(m, name) === "invalid"` (for any `name`):
+ *  · `"literal"` —— no regex is compiled or run: absent / `""` / `"*"` (selects everything) and the NAME-LIST form (only name
+ *    characters, `|`, `,` and spaces — membership after splitting);
+ *  · `"regex"`   —— anything else that compiles as a JS regex (tested unanchored);
+ *  · `"invalid"` —— a regex that does not compile (the caller does not run the hook).
+ * For a caller that must route matchers before evaluating them (run the literal ones inline, give the regex ones a deadline).
+ */
+export declare function hookMatcherForm(matcher: string | undefined): HookMatcherForm;
 /**
  * The hooks config record — the shape `TaskRequest.settings.hooks` carries on the wire and the shell
  * reads from settings JSON: `{ [eventName]: [{ matcher?, hooks: [...] }] }`. Keys limited to the 33