@sema-agent/settings-schema 11.1.0 → 11.3.0

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.d.ts

@@ -0,0 +1,2 @@
+import type { ConfigDirectoryIo } from "./config-dir-migration.js";
+export declare const nodeConfigDirectoryIo: ConfigDirectoryIo;

package/dist/config-dir-io.js

@@ -0,0 +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 { resolveSymlinkTarget, writeFileAtomic } from "./atomic-write.js";
+export const nodeConfigDirectoryIo = {
+    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

@@ -0,0 +1,67 @@
+import { type MigrationReceipt } from "./one-time-migrations.js";
+import { REMOTE_EXEC_DOCUMENT } from "./remote-exec.js";
+import { type DomainName, type RetiredDomainName } from "./types.js";
+/** 注入的 I/O(本模块不碰 `node:fs`)。`writeFileAtomic` 必须原子(写临时文件再改名):半写的域文档比旧文档更糟。 */
+export interface ConfigDirectoryIo {
+    readDir(path: string): Promise<string[]>;
+    readFile(path: string): Promise<string>;
+    writeFileAtomic(path: string, text: string): Promise<void>;
+    removeFile(path: string): Promise<void>;
+}
+/** 一条拒绝 —— 迁移步的拒(收据 `refused`)与整域终判的拒**同一套形**:`migration`(整域终判拒为 `null`)/ `document` / `path`(相对该域文档,出门形)/ `appliedAs: "refused"` / `reason`。
+ *  句子来自本包唯一的脱敏器,坐标段与句子都是出门形、不带值。 */
+export type ConfigDirectoryRefusal = {
+    readonly migration: string | null;
+    readonly document: string;
+    readonly path: string;
+    readonly appliedAs: "refused";
+    readonly reason: string;
+};
+export type ConfigDirectoryMigration = {
+    readonly kind: "unreadable";
+    readonly reason: string;
+} | {
+    readonly kind: "no-documents";
+    readonly entries: readonly string[];
+} | {
+    readonly kind: "refused";
+    readonly read: readonly string[];
+    readonly applied: readonly MigrationReceipt[];
+    readonly refused: readonly ConfigDirectoryRefusal[];
+    readonly why: string;
+} | {
+    readonly kind: "noop";
+    readonly read: readonly string[];
+} | {
+    readonly kind: "pending";
+    readonly read: readonly string[];
+    readonly applied: readonly MigrationReceipt[];
+} | {
+    readonly kind: "applied";
+    readonly read: readonly string[];
+    readonly applied: readonly MigrationReceipt[];
+    readonly written: readonly string[];
+    readonly removed: readonly string[];
+};
+export interface MigrateConfigDirectoryOptions {
+    /** 覆盖面:调用方读的文档名集(配置域、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, {
+    readonly appliedAs: "refused";
+}>;
+/** 一张收据的出门形(坐标只点名、不带值):`refused` 带 `reason`(= {@link ConfigDirectoryRefusal} 的形),`moved` 带 `to`。包内私有 —— 命令行报告用它渲染 `applied`。 */
+export declare function reportReceipt(r: RefusedReceipt): ConfigDirectoryRefusal;
+export declare function reportReceipt(r: MigrationReceipt): Record<string, unknown>;
+/**
+ * 对 `dir`(一个 `config.d` 目录)的覆盖面内文档跑一次一次性迁移;语义与结果见文件头。`dir` 与目录内文件名的拼接用 `/`。
+ */
+export declare function migrateConfigDirectory(dir: string, opts: MigrateConfigDirectoryOptions): Promise<ConfigDirectoryMigration>;
+export {};

package/dist/config-dir-migration.js

@@ -0,0 +1,181 @@
+/**
+ * **一个 `config.d` 目录的一次性迁移** —— 「读目录 → 迁 → 整域终判 → 原子写 → 删 retired 域文件」这一条语义的唯一实现。命令行(`migrate <config.d 目录> [--check]`,
+ * 见 `./cli`)是它的渲染器(退出码 + 报告行);引擎起服时对本地 `config.d` 的迁移调同一只函数,不按同语义自写一份。
+ *
+ * **覆盖面 = 调用方读的文档名集**({@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` 拒迁、一字不写),
+ * 不会把覆盖面外已有的 `governance.json` / `limits.json` 当作「从未设过」覆盖掉;日后若别的迁移步新建覆盖面外的文档,函数响亮抛(守卫),不静默写。
+ *
+ * 本模块不碰 `node:fs`:读写由注入的 {@link ConfigDirectoryIo} 做(真绑定是 `./config-dir-io` 的 `nodeConfigDirectoryIo`,写盘用 `./atomic-write` 那一只原子写器与它的模式表),
+ * 所以测试可以直接喂内存实现。
+ *
+ * ## 结果是一个闭集({@link ConfigDirectoryMigration}),调用方穷举
+ *  · `unreadable`  —— 读不了目录 / 某份文件,或某份文档是坏文件(空 / 纯空白 / 坏 JSON / 不是 JSON 对象,与 `FileConfigStore` 同一只判、同一句)。一字不写。
+ *  · `no-documents`—— 覆盖面内一份文档都没找到;带回目录清单 `entries`(调用方自己判这是「填错了目录」还是「真空的新目录」)。一字不写。
+ *  · `refused`     —— 迁移步拒(收据 `refused`:要猜才改得动的形)**或**要写回的文档整域读不进(整域终判:名字 / 路由唯一这类跨行规则只有整域判得出)。一字不写。
+ *  · `noop`        —— 读到了文档、没有要改的。
+ *  · `pending`     —— `check: true` 且有改动、整域判得过:一字不写。
+ *  · `applied`     —— 已写回:先写改过 / 新建的文档,最后删被移除的 retired 域文件 —— 中途断掉再跑一次,迁移照样恒等收尾(已搬过去的值在新位上,旧文件里同名键按「新位赢」丢弃)。
+ * 写盘阶段的 I/O 错误**原样抛出**(不吞、不改写):已写完的文档留在新位上,再跑一次幂等收尾。
+ */
+import { z } from "zod";
+import { formatConfigPath, parseDomain } from "./config-fns.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) {
+    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((r) => reportReceipt(r)), 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 (Object.prototype.hasOwnProperty.call(input, name) && input[name] === doc)
+            continue;
+        try {
+            judgeWholeDocument(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) => 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" };
+}
+const messageOf = (err) => (err instanceof Error ? err.message : String(err));
+/**
+ * 对 `dir`(一个 `config.d` 目录)的覆盖面内文档跑一次一次性迁移;语义与结果见文件头。`dir` 与目录内文件名的拼接用 `/`。
+ */
+export async function migrateConfigDirectory(dir, opts) {
+    const covered = new Set();
+    for (const name of opts.documents) {
+        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;
+    let names;
+    try {
+        names = await io.readDir(dir);
+    }
+    catch (err) {
+        return { kind: "unreadable", reason: `cannot read directory ${dir}: ${messageOf(err)}` };
+    }
+    const docs = {};
+    for (const name of [...names].sort()) {
+        if (name.startsWith(".") || !name.endsWith(".json"))
+            continue;
+        const base = name.slice(0, -".json".length);
+        if (!covered.has(base) || !isConfigDirectoryDocument(base))
+            continue;
+        let text;
+        try {
+            text = await io.readFile(joinDirPath(dir, name));
+        }
+        catch (err) {
+            return { kind: "unreadable", reason: `cannot read ${name}: ${messageOf(err)}` };
+        }
+        try {
+            docs[base] = judgeDocumentText(dir, base, text); // the one judge per document kind: a domain file's is FileConfigStore's, remote-exec.json's is loadRemoteExec's
+        }
+        catch (err) {
+            return { kind: "unreadable", reason: messageOf(err) };
+        }
+    }
+    const read = Object.keys(docs);
+    if (read.length === 0)
+        return { kind: "no-documents", entries: names };
+    // 目录是不是「一个 scope 的全集」只看一件事:SS-M1 要写的目标域是不是都在覆盖面里(见文件头);不是 ⇒ partial,runtime 的迁移被它自己拒掉。
+    const coverage = RUNTIME_LIFT_TARGETS.every((target) => covered.has(target)) ? "scope" : "partial";
+    const m = migrateStoredDocuments(docs, { coverage });
+    const outside = Object.keys(m.docs).filter((name) => !Object.prototype.hasOwnProperty.call(docs, name) && !covered.has(name));
+    if (outside.length > 0) {
+        // 守卫:迁移新建了覆盖面外的文档。那份文件调用方没读过,「从未设过」只对覆盖面内成立 —— 写下去会覆盖它。今天不会发生(见文件头);发生了就是迁移步的写入域变了,这里先红。
+        throw new Error(`migrateConfigDirectory: the migration produced document(s) outside the coverage (${outside.join(", ")}) — refusing to write files the caller did not read`);
+    }
+    const applied = m.receipts.filter((r) => r.appliedAs !== "refused");
+    const verdict = verdictOf(docs, m.docs, m.receipts);
+    switch (verdict.kind) {
+        case "refused":
+            return { kind: "refused", read, applied, refused: verdict.refused, why: verdict.why };
+        case "noop":
+            return { kind: "noop", read };
+        case "changes":
+            break;
+        default: {
+            const unhandled = verdict;
+            throw new Error(`settings-schema: unhandled verdict ${JSON.stringify(unhandled)}`);
+        }
+    }
+    if (opts.check === true)
+        return { kind: "pending", read, applied };
+    const written = [];
+    const removed = [];
+    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`), configDDocumentText(doc)); // the one config.d document text (writeDomainFile / writeRemoteExec write the same)
+        written.push(`${name}.json`);
+    }
+    for (const name of Object.keys(docs)) {
+        if (Object.prototype.hasOwnProperty.call(m.docs, name))
+            continue;
+        await io.removeFile(joinDirPath(dir, `${name}.json`));
+        removed.push(`${name}.json`);
+    }
+    return { kind: "applied", read, applied, written, removed };
+}

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

package/dist/hooks.js

@@ -30,6 +30,7 @@
  */
 import { z } from "zod";
 import { INTEGER } from "./integer.js";
+import { buildQuotedIssue } from "./quoted-issue.js";
 // ── event set ──────────────────────────────────────────────────────────────────────────────────────────
 // The two halves below are where each word came from (CC 2.1.198's own table, then the later additions) — provenance for the
 // reader of this file, not a contract: they are module-private, and the ONE exported closed set is {@link HOOK_EVENTS}.
@@ -623,7 +624,7 @@ export const HOOK_INJECTED_ENV = [
 /** Default per-hook timeout when an entry does not set one (seconds; CC default). */
 export const DEFAULT_HOOK_TIMEOUT_SECONDS = 60;
 /** A non-empty string with no NUL byte (spawn()/JSON-safe). */
-const hookStr = z.string().min(1).refine((s) => !s.includes("\0"), "must not contain a NUL byte");
+const hookStr = z.string().min(1).refine((s) => !s.includes("\0"), buildQuotedIssue `must not contain a NUL byte`);
 /**
  * `if` condition — permission-rule syntax (e.g. "Bash(git *)") evaluated against tool_name/tool_input
  * BEFORE spawning the hook (only meaningful on tool events). Shell superset field, CC-compatible.
@@ -684,6 +685,25 @@ export const HookMatcherEntry = z.object({
 });
 /** The characters a matcher may consist of to be read as a NAME LIST rather than a regex. */
 const HOOK_MATCHER_NAME_LIST = /^[a-zA-Z0-9_|, -]+$/;
+function readHookMatcher(matcher) {
+    if (matcher === undefined || matcher === "" || matcher === "*")
+        return { form: "all" };
+    if (HOOK_MATCHER_NAME_LIST.test(matcher)) {
+        return {
+            form: "names",
+            names: matcher
+                .split(/[|,]/)
+                .map((part) => part.trim())
+                .filter((part) => part !== ""),
+        };
+    }
+    try {
+        return { form: "regex", pattern: new RegExp(matcher) };
+    }
+    catch {
+        return { form: "invalid" };
+    }
+}
 /**
  * Does `matcher` select `name`? —— **the one reading** of a hooks matcher (11.0.0). The shell and the server both ask this
  * function; neither keeps a copy.
@@ -703,25 +723,50 @@ const HOOK_MATCHER_NAME_LIST = /^[a-zA-Z0-9_|, -]+$/;
  *    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 function hookMatcherSelects(matcher, name) {
-    if (matcher === undefined || matcher === "" || matcher === "*")
-        return true;
-    if (HOOK_MATCHER_NAME_LIST.test(matcher)) {
-        return matcher
-            .split(/[|,]/)
-            .map((part) => part.trim())
-            .some((part) => part !== "" && part === name);
-    }
-    let pattern;
-    try {
-        pattern = new RegExp(matcher);
+    const r = readHookMatcher(matcher);
+    switch (r.form) {
+        case "all":
+            return true;
+        case "names":
+            return r.names.includes(name);
+        case "regex":
+            return r.pattern.test(name);
+        case "invalid":
+            return "invalid";
+        default: {
+            const unhandled = r;
+            throw new Error(`hookMatcherSelects: unhandled matcher reading ${JSON.stringify(unhandled)}`);
+        }
     }
-    catch {
-        return "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 function hookMatcherForm(matcher) {
+    const r = readHookMatcher(matcher);
+    switch (r.form) {
+        case "all":
+        case "names":
+            return "literal";
+        case "regex":
+            return "regex";
+        case "invalid":
+            return "invalid";
+        default: {
+            const unhandled = r;
+            throw new Error(`hookMatcherForm: unhandled matcher reading ${JSON.stringify(unhandled)}`);
+        }
     }
-    return pattern.test(name);
 }
 export const HooksConfig = z.partialRecord(HookEventName, z.array(HookMatcherEntry));
 /**