@sema-agent/settings-schema 11.2.0 → 12.0.0

package/dist/config-fns.d.ts

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

package/dist/config-fns.js

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

package/dist/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));
 /**

package/dist/host-path.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 叶子模块(纯、浏览器安全):**一只**「主机绝对路径」形判 —— 任务请求的 `cwd`(服务器受理时判)与项目登记里 `folder` / `file`
+ * 条目的值读同一只,不各写一份。只判形,不判存在(不碰文件系统)。
+ */
+import { z } from "zod";
+/** 一条主机绝对路径的长度上界(字符数)。 */
+export declare const ABSOLUTE_HOST_PATH_MAX = 4096;
+/**
+ * `p` 是不是一条形上合法的**主机绝对路径**:字符串、非空、≤ {@link ABSOLUTE_HOST_PATH_MAX}、不含 NUL、以 `/` 开头(posix 绝对)、没有 `..` 段
+ * (`/` 与 `\` 都算分隔符 —— `path.isAbsolute` 是语法判,`/a/../../etc` 也「绝对」,而读方 `path.resolve` 会把它解到别处;拒掉它,读到的就是写下的那一条)。
+ *
+ * posix 口径是有意的:读这些路径的主机车道今天跑 posix 树,而这一律在 posix 宿主上与 Node 的 `path.isAbsolute` 逐字同判(`C:\x`、`\\host\share`
+ * 在 posix 上不绝对)。哪天主机车道要接 win 树,换的是这一只(按树的家族判),读方跟着同一只走。
+ */
+export declare function isAbsoluteHostPath(p: unknown): p is string;
+/** {@link isAbsoluteHostPath} 的 zod 座位(一条 issue,定句)。 */
+export declare const AbsoluteHostPath: z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;

package/dist/host-path.js

@@ -0,0 +1,22 @@
+/**
+ * 叶子模块(纯、浏览器安全):**一只**「主机绝对路径」形判 —— 任务请求的 `cwd`(服务器受理时判)与项目登记里 `folder` / `file`
+ * 条目的值读同一只,不各写一份。只判形,不判存在(不碰文件系统)。
+ */
+import { z } from "zod";
+import { buildQuotedIssue, fixed } from "./quoted-issue.js";
+/** 一条主机绝对路径的长度上界(字符数)。 */
+export const ABSOLUTE_HOST_PATH_MAX = 4096;
+/**
+ * `p` 是不是一条形上合法的**主机绝对路径**:字符串、非空、≤ {@link ABSOLUTE_HOST_PATH_MAX}、不含 NUL、以 `/` 开头(posix 绝对)、没有 `..` 段
+ * (`/` 与 `\` 都算分隔符 —— `path.isAbsolute` 是语法判,`/a/../../etc` 也「绝对」,而读方 `path.resolve` 会把它解到别处;拒掉它,读到的就是写下的那一条)。
+ *
+ * posix 口径是有意的:读这些路径的主机车道今天跑 posix 树,而这一律在 posix 宿主上与 Node 的 `path.isAbsolute` 逐字同判(`C:\x`、`\\host\share`
+ * 在 posix 上不绝对)。哪天主机车道要接 win 树,换的是这一只(按树的家族判),读方跟着同一只走。
+ */
+export function isAbsoluteHostPath(p) {
+    return typeof p === "string" && p.length > 0 && p.length <= ABSOLUTE_HOST_PATH_MAX && !p.includes("\0") && p.startsWith("/") && !p.split(/[/\\]/).includes("..");
+}
+/** {@link isAbsoluteHostPath} 的 zod 座位(一条 issue,定句)。 */
+export const AbsoluteHostPath = z
+    .string()
+    .refine(isAbsoluteHostPath, buildQuotedIssue `must be an absolute host path: starts with "/", no ".." segment, no NUL, at most ${fixed(String(ABSOLUTE_HOST_PATH_MAX))} characters`);

package/dist/integer.js

@@ -8,4 +8,5 @@
  * written down here once, instead of being borrowed from the library and changing whenever the library does.
  */
 import { z } from "zod";
-export const INTEGER = z.number().refine((n) => Number.isInteger(n), "Expected integer, received float");
+import { buildQuotedIssue } from "./quoted-issue.js";
+export const INTEGER = z.number().refine((n) => Number.isInteger(n), buildQuotedIssue `Expected integer, received float`);

package/dist/local-load.d.ts

@@ -1,6 +1,6 @@
 import { type RequiredEnvName } from "./file-edit.js";
 import { type EffectiveReadWarning } from "./config-fns.js";
-import { RemoteExecSpec } from "./remote-exec.js";
+import { type RemoteExecSpec } from "./remote-exec.js";
 import type { EffectiveConfig } from "./types.js";
 /** The remoteExec file path under a config root (under config.d/, beside the per-domain files). */
 export declare function remoteExecPath(root: string): string;

package/dist/local-load.js

@@ -13,25 +13,12 @@ import path from "node:path";
 import { writeFileAtomic } from "./atomic-write.js";
 import { FileConfigStore } from "./file-store.js";
 import { listRequiredEnvNames } from "./file-edit.js";
-import { sanitizeZodError } from "./config-fns.js";
-import { RemoteExecSpec } from "./remote-exec.js";
-/** Parse a RemoteExecSpec with a SANITIZED error (zod echoes the offending value — never let a pasted secret
- *  ride the thrown error). A hostile getter/Proxy trap → a fixed message. R14. */
-function parseRemoteExec(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);
-}
+import {} from "./config-fns.js";
+import { configDDocumentText, judgeConfigDText, parseRemoteExecDocument } from "./config-d-file.js";
+import { REMOTE_EXEC_DOCUMENT } from "./remote-exec.js";
 /** The remoteExec file path under a config root (under config.d/, beside the per-domain files). */
 export function remoteExecPath(root) {
-    return path.join(root, "config.d", "remote-exec.json");
+    return path.join(root, "config.d", `${REMOTE_EXEC_DOCUMENT}.json`);
 }
 /** Read `<root>/config.d/remote-exec.json` → a VALIDATED RemoteExecSpec, or undefined if the file is absent
  *  (→ the engine defaults to `host` under CONFIG_PROVIDER=local). Throws (zod) on a present-but-invalid file. */
@@ -45,28 +32,19 @@ export async function loadRemoteExec(root) {
             return undefined;
         throw e;
     }
-    const trimmed = text.trim();
     // A present-but-empty file is a corruption/half-write, NOT "use the default" — FAIL CLOSED (an empty file
     // silently falling back to the host lane would be an isolation DOWNGRADE if the user meant local-docker).
-    // To get the host default, the file must be ABSENT, not empty.
-    if (!trimmed)
-        throw new Error(`${remoteExecPath(root)} is empty/corrupt — delete it for the host default, or write a valid remoteExec spec`);
-    let json;
-    try {
-        json = JSON.parse(trimmed); // sanitized: don't let a SyntaxError echo the raw (possibly secret-bearing) file text
-    }
-    catch {
-        throw new Error(`${remoteExecPath(root)} — invalid JSON (delete it for the host default, or write a valid remoteExec spec)`);
-    }
-    return parseRemoteExec(json);
+    // To get the host default, the file must be ABSENT, not empty. The text judge is THE config.d one (empty / bad JSON / not an object, one sentence
+    // each — the same judge FileConfigStore and the directory migration read with); the sanitized value judge is the migration's too (`./config-d-file`).
+    return parseRemoteExecDocument(judgeConfigDText(REMOTE_EXEC_DOCUMENT, text));
 }
 /** Validate + ATOMICALLY write `<root>/config.d/remote-exec.json` (the package's one atomic writer, `./atomic-write`; never a half file). The
  *  client's `config` editor writes the exec backend through this; the engine reads it via loadRemoteExec. */
 export async function writeRemoteExec(root, spec) {
-    const parsed = parseRemoteExec(spec);
+    const parsed = parseRemoteExecDocument(spec);
     const dir = path.join(root, "config.d");
     await mkdir(dir, { recursive: true });
-    writeFileAtomic(remoteExecPath(root), JSON.stringify(parsed, null, 2) + "\n", "config-document");
+    writeFileAtomic(remoteExecPath(root), configDDocumentText(parsed), "config-document");
     return parsed;
 }
 /** Resolve a `file:<path>` .env VALUE → the file's trimmed content (the file-NAME secret ref, config-research

package/dist/migration-receipt.d.ts

@@ -2,10 +2,11 @@
  * 一次性迁移的**收据形**与两张闭集(11.0.0)—— 叶子模块(运行期零依赖;只有型导入),由 `./one-time-migrations` 再导出(不进主桶)。
  * 单拆出来只为一件事:调度店的读口(`./scheduler-store`,轻、浏览器安全)要在告警里带收据,不该为一个型把整套域 schema 拉进来。
  */
+import type { REMOTE_EXEC_DOCUMENT } from "./remote-exec.js";
 import type { DomainName, RetiredDomainName } from "./types.js";
 /** 本版登记的一次性**数据**迁移 id(闭集;每个 id 在 `ONE_TIME_MIGRATIONS` 登记表里恰一行)。收据只许这些 id —— 同表登记的 wire 删码位
  *  (`WIRE_RETIREMENT_IDS`,`./one-time-migrations`)不改任何存储形,铸不出收据,不在本集。 */
-export declare const ONE_TIME_MIGRATION_IDS: readonly ["SS-M1", "SS-M2", "SS-M3", "SS-M4", "SS-M5", "SS-M6", "SS-M7", "SS-M9"];
+export declare const ONE_TIME_MIGRATION_IDS: readonly ["SS-M1", "SS-M2", "SS-M3", "SS-M4", "SS-M5", "SS-M6", "SS-M7", "SS-M8", "SS-M9"];
 export type OneTimeMigrationId = (typeof ONE_TIME_MIGRATION_IDS)[number];
 /**
  * 一条收据说迁移**对一个坐标做了什么**(闭集,每词一义):
@@ -17,8 +18,8 @@ export type OneTimeMigrationId = (typeof ONE_TIME_MIGRATION_IDS)[number];
  */
 export declare const MIGRATION_APPLIED_AS: readonly ["moved", "rewritten", "dropped-shadowed", "dropped-inert", "refused"];
 export type MigrationAppliedAs = (typeof MIGRATION_APPLIED_AS)[number];
-/** 收据指向的那份文档:配置域名、retired 域名(`runtime`),或调度店(`scheduler-store`)。 */
-export type MigrationDocument = DomainName | RetiredDomainName | "scheduler-store";
+/** 收据指向的那份文档:配置域名、retired 域名(`runtime`)、`config.d/remote-exec.json`(`remote-exec`),或调度店(`scheduler-store`)。 */
+export type MigrationDocument = DomainName | RetiredDomainName | typeof REMOTE_EXEC_DOCUMENT | "scheduler-store";
 /** 文档里的段坐标(字符串段 = 对象键,数字段 = 数组下标;与告警坐标同一形)。 */
 export type MigrationPath = readonly (string | number)[];
 interface ReceiptBase {

package/dist/migration-receipt.js

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

package/dist/node.d.ts

@@ -10,5 +10,5 @@ export * from "./bundle.js";
 export * from "./local-load.js";
 export * from "./scheduler-store-node.js";
 export * from "./prompts-digest.js";
-export { migrateConfigDirectory, type ConfigDirectoryIo, type ConfigDirectoryMigration, type ConfigDirectoryRefusal, type MigrateConfigDirectoryOptions } from "./config-dir-migration.js";
+export { migrateConfigDirectory, type ConfigDirectoryDocument, type ConfigDirectoryIo, type ConfigDirectoryMigration, type ConfigDirectoryRefusal, type MigrateConfigDirectoryOptions } from "./config-dir-migration.js";
 export { nodeConfigDirectoryIo } from "./config-dir-io.js";

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

@@ -1,4 +1,5 @@
 import type { MigrationReceipt, OneTimeMigrationId } from "./migration-receipt.js";
+import { REMOTE_EXEC_DOCUMENT } from "./remote-exec.js";
 import { type DomainName, type RetiredDomainName } from "./types.js";
 export { MIGRATION_APPLIED_AS, ONE_TIME_MIGRATION_IDS, type MigrationAppliedAs, type MigrationDocument, type MigrationPath, type MigrationReceipt, type OneTimeMigrationId } from "./migration-receipt.js";
 export { migrateSchedulerRecords } from "./scheduler-store-migration.js";
@@ -33,12 +34,12 @@ export declare const ONE_TIME_MIGRATIONS: readonly OneTimeMigrationWindow[];
 /** 一组存储文档是不是**一个 scope 的全集**:`"scope"` = 缺席的域就是从未设过;`"partial"` = 缺席的域只是没给(principal 层、回滚史的
  *  单域行、任意子集)。只有 SS-M1 读它。 */
 export type DocumentCoverage = "scope" | "partial";
-/** 一组存储文档(域名 / retired 域名 → 文档)。别的键原样带过、不动。 */
-export type StoredDocuments = Readonly<Partial<Record<DomainName | RetiredDomainName, unknown>>>;
+/** 一组存储文档(域名 / retired 域名 / `remote-exec` → 文档)。别的键原样带过、不动。 */
+export type StoredDocuments = Readonly<Partial<Record<DomainName | RetiredDomainName | typeof REMOTE_EXEC_DOCUMENT, unknown>>>;
 export interface StoredDocumentsMigration {
     /** 迁移后的文档集:没改的文档是**同一引用**;被移除的(retired 域)不在;新建的(例:迁出的 `governance` / `limits`)在。 */
     readonly docs: Readonly<Record<string, unknown>>;
-    /** 逐条收据(步序 SS-M1 → SS-M2 → SS-M5 → SS-M6 → SS-M9 → SS-M7 → SS-M4:纯改写步在前,用新 schema 终判的 SS-M4 最后;步内按坐标)。
+    /** 逐条收据(步序 SS-M1 → SS-M2 → SS-M5 → SS-M6 → SS-M8 → SS-M9 → SS-M7 → SS-M4:纯改写步在前,用新 schema 终判的 SS-M4 最后;步内按坐标)。
      *  只有 `refused` 的收据 = 什么都没改。 */
     readonly receipts: readonly MigrationReceipt[];
 }
@@ -58,5 +59,6 @@ export declare function migrateEffectiveSnapshot(effective: unknown): {
     readonly effective: unknown;
     readonly receipts: readonly MigrationReceipt[];
 };
-/** 本包域 schema 里全部 URL 座位的坐标模式(派生;数组 / Record 位写 `*`)—— 迁移不用它,它给钉与说明看「今天派生出哪些座位」。 */
+/** SS-M7 走查的全部 URL 座位的坐标模式(派生;数组 / Record 位写 `*`;域文档以域名起头,`remote-exec.json` 以 `remote-exec` 起头)—— 迁移不用它,
+ *  它给钉与说明看「今天派生出哪些座位」。 */
 export declare function urlSeatPatterns(): string[];