@sema-agent/settings-schema 12.0.0 → 12.1.0

package/CHANGELOG.md

@@ -6,6 +6,50 @@
 > `@sema-agent/registry-core`(更早还曾是 `@sema-ai/registry-core`)。本档 `0.19.0` 以下各节里的
 > 包名是**历史记录**,如实保留不追改。
 
+## 12.1.0 — 2026-10-12 — minor:新导出 interpolateHookEnvVars(http 钩子 header 的 $VAR / ${VAR} 展开只有一只读法,照 CC 2.1.296:名单内展开、名单外与凭据名置空并回报 blanked 清单、大写名字形、剥 CR / LF / NUL);消费方 server hook runner / cli execHttpHook
+
+> minor:新增一只纯函数导出 `interpolateHookEnvVars(headers, allowedEnvVars, env)`(主 barrel 与 `./hooks` 两处),外加它的两个结果类型 `HookEnvInterpolation` / `HookEnvBlank`。
+> additive:零删、零改名、零改形;导出面登记表 +3 名 × 2 条子路径。消费方:服务器的钩子执行器(引擎跑的事件)与 cli 的 `execHttpHook`(壳本端跑的事件)改调这一只,零别的改动。
+
+### 新导出:http 钩子 header 里 `$VAR` / `${VAR}` 的展开只有一只读法 —— `interpolateHookEnvVars`
+
+此前壳(cli 的 `execHttpHook`)与服务器的钩子执行器各自带一份展开读法,同一份钩子定义发出的字节并不相同(例:`${TOKEN}` 花括号形壳里展开、服务器里原样;
+名单外的引用壳里置空、服务器里留字面;名字形、控制字符的处置也各不同)。现在两边调同一只函数,到桩的字节相同。读法照 CC 2.1.296 逐字节:
+- **只读 header 值**,header 名不动;引用是 `$NAME` 或 `${NAME}`,`NAME` = `[A-Z_][A-Z0-9_]*`(只认大写;小写、数字开头、`${}`、未闭合的 `${` 都是普通文字)。
+- **名单内**(`allowedEnvVars`)⇒ 展开成 `env` 里的值;`env` 没有这个名字 ⇒ 展开成空串(不进 `blanked`)。
+- **名单外** ⇒ **空串**(不留字面),进返回值的 `blanked` 清单(`{ header, name, reason: "not-allowed" }`);该变量的 `env` 值不被读取。
+- **凭据名变量**(CC 2.1.296 的闭集名字表:27 个名字 × 裸名与 `INPUT_` 前缀两种拼法,共 54 个)⇒ 即使名单点了名也是空串,进 `blanked`(`reason: "credential"`)。是名字表,不是后缀规则 —— `MY_TOKEN` 是普通变量。
+- **结果剥 CR / LF / NUL**(防 header 注入),对每个 header 值都做,不论有没有引用。
+- 纯函数:零 I/O、零日志、不读全局环境(`env` 是调用方给的视图)、不改入参。`blanked` 给调用方留痕(CC 对每条写一行 debug 日志),header 本身两种情形下都是定稿。
+  `blanked` 按 header 序、再按首次出现序;同一 header 里重复引用的同一个名字只列一次。
+
+与 cli 今天的展开函数(`execHttpHook.ts` 的 `interpolateEnvVars`)逐字节同 —— 名单内 / 名单外置空 / 无值 / 名字形 / 剥除五项读数相同;唯一不同是凭据名那一臂:cli 尚无,名单点了名的凭据名它会照常展开,
+改调本导出后收敛。CC 2.1.296 另有一族按 `env` 值与运行状态判的置空(远端汇点名、代理 / 包索引 URL 等),需要本函数不取的入参,不在这一读法里。
+
+## 12.0.1 — 2026-10-12 — patch:文件系统失败句一只铸点(errno × 落点 × 真实路径)覆盖写 / 删 / 改名 / 迁移拒句 —— 删除失败点名目录 · 拒句用真实路径不写死 config.d/ · 不可变目录提示 · ENAMETOOLONG 一句;零型面
+
+> patch:文件系统失败句收成一只铸点,覆盖写 / 删 / 改名 / 读与 `config.d` 文档拒句四处。零型面(零新导出、零删、零改名;导出面登记表不动),退出码、报告行、库写口抛的错的 `code` / `cause` 都不变;
+> 变的只是 stderr / 错误 `message` 里的句子文本,逐条列在下面。消费方:零改动(按 `code` 分支的调用方不受影响;逐字匹配这些句子的脚本按新读数改匹配)。
+
+### 行为修复:文件系统失败句只有一只铸点 —— 删除失败点名目录 · 拒句点名真实路径 · 不可变目录提示 · 路径过长一句
+
+12.0.0 只把写失败一臂按 errno 落点分了句,同一类事实在别处还是各自手写的话(删文件、读目录 / 文件、`config.d` 文档拒句、`ENAMETOOLONG`)。
+现在本包把文件系统错误说成人话只有一只铸点(错误码 × 落点 × 真实路径):落点是闭集(建临时文件 / `rename` / 删 / 读,外加写口整体失败这一档 —— 注入的写口抛的错,看不见是哪一步),
+原子写器、命令行写 / 删口、目录迁移读口全从这里出句;包内门看住「铸点之外没有第二处手写句」。四处读数:
+- **删除失败**(`migrate` 删 retired 域文件 `runtime.json` 时目录不可写):`cannot remove <文件> from directory <目录> (<errno>): make the directory writable`。
+  以前 `cannot remove <文件>: <errno>: <Node 句>`,点名的是文件,真因是目录(与 12.0.0 修掉的写失败同一形)。
+- **文档拒句点名读的那份真实路径**:`config.d` 里空 / 纯空白 / 坏 JSON / 不是对象(域文档、retired 域文档、`remote-exec.json` 同一只文本判)的三句,
+  以前一律写死 `config.d/<名>.json` 字面 —— 对两个 scope 目录各迁一遍时,两份拒句逐字相同、认不出是哪个目录。现在是 `<目录>/remote-exec.json is empty/whitespace — …`、
+  `invalid JSON in <目录>/models.json — …`、`<路径> must be a JSON object (got <形>) — …`;`FileConfigStore` / `readBundle` / `loadRemoteExec` / 命令行各点名自己读的那一份。
+  读不了目录 / 文件的句子同样点名真实路径(以前读文件只给裸文件名)。
+- **目录不可变 / 只读**:建临时文件与删目录项的 `EPERM` / `EROFS`,出路句尾加 `directory may be read-only or immutable (chflags / chattr)`
+  (目录带 `chflags uchg` / `chattr +i` 时,只改权限位修不好);`EACCES` / `ENOENT` 的 12.0.0 读数逐字不变。
+- **路径过长**(`ENAMETOOLONG`):一句 `path too long: <被操作系统拒的路径> (ENAMETOOLONG)`。
+  以前落在建临时文件上时读成 `cannot write into directory <目录> (ENAMETOOLONG): ENAMETOOLONG: name too long, …` —— errno 两遍,而且怪到目录头上。
+  「errno 只打一遍」对所有落点生效:别的 errno 的 Node 句子去掉自带的 `<errno>: ` 前缀(例:`cannot replace <文件> (ENOSPC): no space left on device, …`)。
+
+库写口(`writeDomainFile` / `writeRemoteExec` / 调度店写口)抛的错:`message` 是同一只铸点的句子,`code` 照抄底层 errno、原错误在 `cause`,不变。
+
 ## 12.0.0 — 2026-10-12 — 角色词随引擎收缩(`ModelRole` 8 → 6,一次性迁移 SS-M8)· 写失败按 errno 落点分句 · `config.d` 每份文档同一只文本判 · 扣名条目的可比记号 `identity.token`(major)
 
 > 本节一处硬破坏(角色词表收缩,持久面走一次性迁移 SS-M8)外加三件:命令行写失败按落点分句、`config.d` 每份文档同一只文本判(`remote-exec.json` 非对象不再被 `migrate`

package/README.md

@@ -411,7 +411,8 @@ therefore shows only `zod`. Node built-ins only (`node:crypto`, `node:fs`).
   `HOOK_EVENT_OWNER` (engine | shell), the matcher-field table, a per-event input schema (`HookInput`),
   the output/decision shapes (`SyncHookOutput` / `HookSpecificOutput` / `HookPermissionRequestDecision`),
   `HooksConfig` (the `settings.json` `hooks` shape — a CLOSED key set, so a typo is caught at the wire),
-  and stop attribution (`StoppedBy` / `stopAttributionText`).
+  stop attribution (`StoppedBy` / `stopAttributionText`), and the one reading of `$VAR` / `${VAR}` in an `http` hook's header values
+  (`interpolateHookEnvVars` — allow-listed names expand, everything else is blanked and reported, credential variables are never released, CR / LF / NUL stripped).
 - **Cross-session settings** (`cross-session.ts`): the two `settings.json` keys `crossSessionInbound`
   (wake/next-turn/hold/refuse — the core 7.30.0 vocabulary, `accept` retired in 6.0.0; `default` = unset) and `dialogExpiry` (60s/5m/10m/never), each with a reader that
   answers `ok:false` on a bad value instead of silently folding to the default.

package/conformance/VERSION

@@ -1 +1 @@
-12.0.0
+12.1.0

package/dist/atomic-write.js

@@ -20,15 +20,15 @@
  * 「链接 ⇒ 真文件、悬空 ⇒ 响亮抛」这一只判法是 {@link resolveSymlinkTarget}:目录迁移的读口(`./config-dir-io`)读目录 / 读文件前也问它,
  * 悬空链接在读阶段与写阶段是**同一句**({@link danglingSymlinkSentence})。
  *
- * ## 写失败(12.0.0)
- * 两步各一句({@link AtomicWriteFailure},句子在 `./write-failure`):临时文件建不出 ⇒ 「cannot write into directory <dir> (<errno>): …」(点名目录 —— 目录不可写时
+ * ## 写失败(12.0.0;句子归文件系统失败句的唯一铸点)
+ * 两步各一句({@link FsFailure},句子在 `./fs-failure`):临时文件建不出 ⇒ 「cannot write into directory <dir> (<errno>): …」(点名目录 —— 目录不可写时
  * 文件本身没错);`rename` 失败 ⇒ 「cannot replace <file> (<errno>): …」(点名真文件)。认得的 errno 给对应出路,别的给 Node 自己的句子;`code` / `cause` 留着。
  * 可写目录里的只读文件照常写得进(`rename` 换的是目录项)。
  */
 import { randomBytes } from "node:crypto";
 import { chmodSync, lstatSync, readlinkSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import path from "node:path";
-import { AtomicWriteFailure } from "./write-failure.js";
+import { FsFailure } from "./fs-failure.js";
 /** 按文档类的模式表(闭集)。 */
 export const ATOMIC_FILE_CLASSES = {
     "config-document": { newMode: 0o644, existing: "keep" },
@@ -87,12 +87,12 @@ export function writeFileAtomic(target, text, kind) {
     }
     const dir = path.dirname(real);
     const tmp = path.join(dir, `.${path.basename(real)}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`);
-    let step = "create";
+    let site = { landing: "dir-create-temp", path: tmp };
     try {
         writeFileSync(tmp, text, { encoding: "utf8", mode: kept ?? spec.newMode });
         if (kept !== undefined)
             chmodSync(tmp, kept); // a kept mode is restored exactly (the creation mode above went through the umask)
-        step = "replace";
+        site = { landing: "rename", path: real };
         renameSync(tmp, real);
     }
     catch (e) {
@@ -102,6 +102,6 @@ export function writeFileAtomic(target, text, kind) {
         catch {
             /* 临时文件没建成:没什么可清 */
         }
-        throw new AtomicWriteFailure(step, dir, real, e); // 12.0.0: the sentence names the step that failed and its way out (`./write-failure`)
+        throw new FsFailure(site, e); // the sentence names the step that failed and its way out (`./fs-failure`, the one mint)
     }
 }

package/dist/cli.d.ts

@@ -15,8 +15,8 @@
  * 零收据 = noop 退出 0 —— 新部署的空 `config.d` 是合法态,「没有东西可迁」不是「指错目录」(搬空之后再跑同一目录也因此幂等)。
  *
  * 退出码:0 = 已写回 / 无事可做(目录里有域文档只是没有要改的,或目录真空);1 = 有迁不了的坐标(收据 `refused`)**或**要写回的域文档整域读不进(整域终判,见 `migrateConfigDirectory`),**一字不写**;
- * 2 = 用法错,或**环境错**(读目录 / 读文件 / 写盘 / 删文件的 I/O 错:权限、磁盘、悬空符号链接 …;stdout 空、stderr 一行点名路径与 errno,不打栈;写盘失败按落点分句 ——
- * 目录建不出文件 ⇒ 点名目录、目标换不掉 ⇒ 点名文件,句尾是对应出路(原子写器的句子,`./write-failure`)——
+ * 2 = 用法错,或**环境错**(读目录 / 读文件 / 写盘 / 删文件的 I/O 错:权限、磁盘、悬空符号链接 …;stdout 空、stderr 一行点名路径与 errno,不打栈;句子按落点分句、
+ * 一律出自文件系统失败句的唯一铸点 `./fs-failure` —— 例:目录建不出文件 ⇒ 点名目录、目标换不掉 ⇒ 点名文件,句尾是对应出路)——
  * rc 1 是「拒迁」的约定码,不许被一个权限错冒充),或覆盖面内某份文档(域文档或 `remote-exec.json`)是坏文件(空 / 纯空白 / 坏 JSON / 不是 JSON 对象 —— 与 `FileConfigStore` / `loadRemoteExec` 同一只判、同一句),**或目录里有条目却没有一个是域文档**
  * (多半是填错了目录:要的是 `config.d` 目录本身;`<目录>/config.d` 在场时句子直接点它)(此时 stdout 为空);3 = `--check` 且会有改动、整域判得过(不写)。`--check` 与真跑过同一只判定,只在
  * 「有改动、且整域判得过」那一支上分开(pending vs applied)—— 整域会被拒的目录 `--check` 也报 refused / rc 1。

package/dist/cli.js

@@ -15,8 +15,8 @@
  * 零收据 = noop 退出 0 —— 新部署的空 `config.d` 是合法态,「没有东西可迁」不是「指错目录」(搬空之后再跑同一目录也因此幂等)。
  *
  * 退出码:0 = 已写回 / 无事可做(目录里有域文档只是没有要改的,或目录真空);1 = 有迁不了的坐标(收据 `refused`)**或**要写回的域文档整域读不进(整域终判,见 `migrateConfigDirectory`),**一字不写**;
- * 2 = 用法错,或**环境错**(读目录 / 读文件 / 写盘 / 删文件的 I/O 错:权限、磁盘、悬空符号链接 …;stdout 空、stderr 一行点名路径与 errno,不打栈;写盘失败按落点分句 ——
- * 目录建不出文件 ⇒ 点名目录、目标换不掉 ⇒ 点名文件,句尾是对应出路(原子写器的句子,`./write-failure`)——
+ * 2 = 用法错,或**环境错**(读目录 / 读文件 / 写盘 / 删文件的 I/O 错:权限、磁盘、悬空符号链接 …;stdout 空、stderr 一行点名路径与 errno,不打栈;句子按落点分句、
+ * 一律出自文件系统失败句的唯一铸点 `./fs-failure` —— 例:目录建不出文件 ⇒ 点名目录、目标换不掉 ⇒ 点名文件,句尾是对应出路)——
  * rc 1 是「拒迁」的约定码,不许被一个权限错冒充),或覆盖面内某份文档(域文档或 `remote-exec.json`)是坏文件(空 / 纯空白 / 坏 JSON / 不是 JSON 对象 —— 与 `FileConfigStore` / `loadRemoteExec` 同一只判、同一句),**或目录里有条目却没有一个是域文档**
  * (多半是填错了目录:要的是 `config.d` 目录本身;`<目录>/config.d` 在场时句子直接点它)(此时 stdout 为空);3 = `--check` 且会有改动、整域判得过(不写)。`--check` 与真跑过同一只判定,只在
  * 「有改动、且整域判得过」那一支上分开(pending vs applied)—— 整域会被拒的目录 `--check` 也报 refused / rc 1。
@@ -31,7 +31,7 @@
 import { reportReceipt, joinDirPath, migrateConfigDirectory } from "./config-dir-migration.js";
 import { MIGRATE_COMMAND_TEMPLATE, migrateCommandFor } from "./retired-form.js";
 import { REMOTE_EXEC_DOCUMENT } from "./remote-exec.js";
-import { AtomicWriteFailure } from "./write-failure.js";
+import { fsFailureMessage } from "./fs-failure.js";
 import { DOMAINS, RETIRED_DOMAINS } from "./types.js";
 /** 命令行的覆盖面:全部配置域、retired 域(便携与否不论 —— 离线的 `workers.json` 一样迁)与 `remote-exec.json`。 */
 export const COVERED_DOCUMENTS = [...DOMAINS, ...Object.keys(RETIRED_DOMAINS), REMOTE_EXEC_DOCUMENT];
@@ -78,10 +78,9 @@ function reportOf(outcome, dir, applied, refused) {
 class EnvironmentFailure extends Error {
 }
 const oneLine = (text) => text.replace(/\s*\n\s*/g, " ");
-const messageOf = (err) => oneLine(err instanceof Error ? err.message : String(err));
-/** 把注入的写口包一层:写盘 / 删文件抛 ⇒ {@link EnvironmentFailure}。本包的原子写器抛的是按失败那一步分好的句子({@link AtomicWriteFailure}:目录建不出文件 ⇒
- *  点名目录,目标换不掉 ⇒ 点名文件,句尾是对应出路)—— 原样用;别的写口(注入的替身)抛的错 ⇒ 点名**要写的那份文件**与原错误句。
- *  读口不包:读目录 / 读文件错由 `migrateConfigDirectory` 自己收成 `unreadable`(同为 rc 2)。 */
+/** 把注入的写口包一层:写盘 / 删文件抛 ⇒ {@link EnvironmentFailure},句子由铸点出(`fsFailureMessage`):本包的原子写器抛的是按失败那一步分好的句子
+ *  (目录建不出文件 ⇒ 点名目录,目标换不掉 ⇒ 点名文件,句尾是对应出路)—— 原样用;别的写口(注入的替身)抛的错步骤看不见 ⇒ 点名**要写的那份文件**与原错误句。
+ *  读口不包:读目录 / 读文件错由 `migrateConfigDirectory` 自己收成 `unreadable`(同为 rc 2,句子同出铸点)。 */
 function withEnvironmentArm(io) {
     return {
         readDir: (path) => io.readDir(path),
@@ -91,7 +90,7 @@ function withEnvironmentArm(io) {
                 await io.writeFileAtomic(path, text);
             }
             catch (err) {
-                throw new EnvironmentFailure(err instanceof AtomicWriteFailure ? err.message : `cannot write ${path}: ${messageOf(err)}`, { cause: err });
+                throw new EnvironmentFailure(fsFailureMessage({ landing: "write", path }, err), { cause: err });
             }
         },
         removeFile: async (path) => {
@@ -99,7 +98,7 @@ function withEnvironmentArm(io) {
                 await io.removeFile(path);
             }
             catch (err) {
-                throw new EnvironmentFailure(`cannot remove ${path}: ${messageOf(err)}`, { cause: err });
+                throw new EnvironmentFailure(fsFailureMessage({ landing: "remove", path }, err), { cause: err });
             }
         },
     };

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

@@ -11,9 +11,9 @@ export declare function configDPath(root: string, name: string): string;
 /** `config.d` 里能放的文档名:配置域、retired 域、`remote-exec`(`config.d/remote-exec.json`,不是配置域)。 */
 export type ConfigDDocumentName = DomainName | RetiredDomainName | typeof REMOTE_EXEC_DOCUMENT;
 /** 一个 `config.d/<名>.json` 在场时的**文本** → 它的值(纯判,零 I/O;见文件头的律):一个 JSON 对象 ⇒ 它;空 / 纯空白、坏 JSON、
- *  不是对象 ⇒ 抛,每种一句(点名文件与形,句尾 {@link documentWayOut})。读盘的入口(`readConfigDFile`、`loadRemoteExec`)与自己读文本的命令行(`migrate`)
- *  都过它 —— 一种坏形一句话,不论是哪份文档。 */
-export declare function judgeConfigDText(name: ConfigDDocumentName, text: string): Record<string, unknown>;
+ *  不是对象 ⇒ 抛,每种一句(点名 `file` —— 调用方读的那份文件的真实路径 —— 与形,句尾 {@link documentWayOut})。读盘的入口(`readConfigDFile`、`loadRemoteExec`)
+ *  与自己读文本的命令行(`migrate`)都过它 —— 一种坏形一句话,不论是哪份文档。 */
+export declare function judgeConfigDText(name: ConfigDDocumentName, text: string, file: string): Record<string, unknown>;
 /** 读一个 `config.d/<名>.json`:不存在(ENOENT)⇒ `undefined`;在场 ⇒ {@link judgeConfigDText}。 */
 export declare function readConfigDFile(root: string, name: DomainName | RetiredDomainName): Promise<Record<string, unknown> | undefined>;
 /**

package/dist/config-d-file.js

@@ -5,8 +5,9 @@
  *
  * 律:**只有不存在(ENOENT)= 缺席**(`undefined`);在场的文件必须是一个 JSON 对象。空 / 纯空白(半写、截断)、坏 JSON、解析出来不是对象
  * (`null` / 数组 / 数 / 串 / 布尔)一律是**坏文件** ⇒ 抛(fail-closed:把一个被截断的文件读成缺席,就是静默丢掉那一个域 —— 例:截断的
- * governance.json 丢掉它的护栏;截断的 remote-exec.json 把隔离车道降成宿主车道)。三种坏形每种一句,点名文件与形、句尾出路按文档类
- * ({@link documentWayOut}),从不回显文件原文。
+ * governance.json 丢掉它的护栏;截断的 remote-exec.json 把隔离车道降成宿主车道)。三种坏形每种一句,点名**调用方寻址这份文档用的路径**与形(读的人给路径,
+ * 判官不拼 `config.d/` 字面 —— 多个目录各有一份时,句子认得出是哪个 scope 的哪一份;文档是符号链接时点名链接这一端:句尾「delete it」删的是这个 scope 里的这一项,不是被几个 scope 共用的目标)、
+ * 句尾出路按文档类({@link documentWayOut}),从不回显文件原文。
  */
 import { readFile } from "node:fs/promises";
 import path from "node:path";
@@ -43,10 +44,9 @@ function documentWayOut(name) {
     return name === REMOTE_EXEC_DOCUMENT ? "delete it for the host default, or write a valid remoteExec spec" : "delete it for the domain default, or write a valid object";
 }
 /** 一个 `config.d/<名>.json` 在场时的**文本** → 它的值(纯判,零 I/O;见文件头的律):一个 JSON 对象 ⇒ 它;空 / 纯空白、坏 JSON、
- *  不是对象 ⇒ 抛,每种一句(点名文件与形,句尾 {@link documentWayOut})。读盘的入口(`readConfigDFile`、`loadRemoteExec`)与自己读文本的命令行(`migrate`)
- *  都过它 —— 一种坏形一句话,不论是哪份文档。 */
-export function judgeConfigDText(name, text) {
-    const file = `config.d/${name}.json`;
+ *  不是对象 ⇒ 抛,每种一句(点名 `file` —— 调用方读的那份文件的真实路径 —— 与形,句尾 {@link documentWayOut})。读盘的入口(`readConfigDFile`、`loadRemoteExec`)
+ *  与自己读文本的命令行(`migrate`)都过它 —— 一种坏形一句话,不论是哪份文档。 */
+export function judgeConfigDText(name, text, file) {
     const trimmed = text.trim();
     if (!trimmed)
         throw new Error(`${file} is empty/whitespace — ${documentWayOut(name)}`);
@@ -65,16 +65,17 @@ export function judgeConfigDText(name, text) {
 }
 /** 读一个 `config.d/<名>.json`:不存在(ENOENT)⇒ `undefined`;在场 ⇒ {@link judgeConfigDText}。 */
 export async function readConfigDFile(root, name) {
+    const file = configDPath(root, name);
     let text;
     try {
-        text = await readFile(configDPath(root, name), "utf8");
+        text = await readFile(file, "utf8");
     }
     catch (e) {
         if (e.code === "ENOENT")
             return undefined;
         throw e;
     }
-    return judgeConfigDText(name, text);
+    return judgeConfigDText(name, text, file);
 }
 /**
  * `config.d/` 里每个 **retired 域**的文件过一次墓碑(`refuseRetiredDomain`,与 `buildEffective` / `parseDomain` 同一只判官、同一句):带事实 ⇒

package/dist/config-dir-migration.js

@@ -24,6 +24,7 @@
 import { z } from "zod";
 import { formatConfigPath, parseDomain } from "./config-fns.js";
 import { configDDocumentText, judgeConfigDText, parseRemoteExecDocument } from "./config-d-file.js";
+import { fsFailureMessage } from "./fs-failure.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";
@@ -109,7 +110,7 @@ export async function migrateConfigDirectory(dir, opts) {
         names = await io.readDir(dir);
     }
     catch (err) {
-        return { kind: "unreadable", reason: `cannot read directory ${dir}: ${messageOf(err)}` };
+        return { kind: "unreadable", reason: fsFailureMessage({ landing: "read", path: dir, of: "directory" }, err) };
     }
     const docs = {};
     for (const name of [...names].sort()) {
@@ -119,14 +120,15 @@ export async function migrateConfigDirectory(dir, opts) {
         if (!covered.has(base) || !isConfigDirectoryDocument(base))
             continue;
         let text;
+        const file = joinDirPath(dir, name);
         try {
-            text = await io.readFile(joinDirPath(dir, name));
+            text = await io.readFile(file);
         }
         catch (err) {
-            return { kind: "unreadable", reason: `cannot read ${name}: ${messageOf(err)}` };
+            return { kind: "unreadable", reason: fsFailureMessage({ landing: "read", path: file, of: "file" }, err) };
         }
         try {
-            docs[base] = judgeConfigDText(base, text); // the one config.d text judge (FileConfigStore / loadRemoteExec read with it): empty / bad JSON / not an object ⇒ unreadable
+            docs[base] = judgeConfigDText(base, text, file); // the one config.d text judge (FileConfigStore / loadRemoteExec read with it): empty / bad JSON / not an object ⇒ unreadable
         }
         catch (err) {
             return { kind: "unreadable", reason: messageOf(err) };

package/dist/fs-failure.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 包内私有(不进主桶、不进 exports 表;零 `node:` 依赖):**文件系统失败句的唯一铸点** —— `(errno, 落点, 真实路径)` → 一句。
+ * 本包凡是把文件系统错误说成人话的地方(原子写器、命令行的写 / 删口、目录迁移的读口)都调 {@link fsFailureSentence},没有第二处手写的 `cannot …` 句子
+ * (`test/` 下的 `fs-failure-single-mint-gate` 门扫 `src/` 里的字符串字面量,铸点之外出现即红)。
+ *
+ * 落点({@link FsFailureSite}.`landing`,闭集)按失败发生在哪一步分句 —— 同一个 errno 在不同落点指向不同的东西:
+ *  · `dir-create-temp` —— 原子写器在目标所在目录里建临时文件。目录不让建 ⇒ 点名**目录**(文件本身没错);
+ *  · `rename`          —— 原子写器 `rename` 盖过目标。目录收了新文件、却换不掉这一份 ⇒ 点名**真文件**;
+ *  · `remove`          —— 删一个文件。删的是目录项:目录不让删 ⇒ 点名文件所在的**目录**(与建临时文件同一个因);
+ *  · `read`            —— 读一个目录或文件;
+ *  · `write`           —— 写口整体失败、步骤看不见(注入的写口抛的错,不是本包原子写器抛的):只点名要写的文件。
+ * 认得的 errno 给那一步对应的出路,别的 errno(磁盘满、I/O 错 …)给 Node 自己的句子 —— 照样响亮,只是不替它猜出路。两条与落点无关的律:
+ *  · errno 只打一遍 —— 句首括号里一次,Node 句子自带的 `<errno>: ` 前缀去掉;
+ *  · `ENAMETOOLONG`(路径某一节或整条超限)既不是目录的错也不是文件的错 ⇒ 一句 `path too long: <被操作系统拒的路径> (ENAMETOOLONG)`,不点名目录、不给权限类出路。
+ * 目录落点(`dir-create-temp` / `remove`)的 `EPERM` / `EROFS` 出路句尾加「目录可能是只读 / 不可变(chflags / chattr)」—— 改权限位修不好的那两种。
+ *
+ * 原子写器抛 {@link FsFailure}(句子在 `message`,`code` 照抄底层 errno,原错误在 `cause`);它在写器内部已经按更细的落点铸过句子,
+ * 命令行 / 迁移用 {@link fsFailureMessage} 取句 —— 已经是 {@link FsFailure} 的原样用,否则按它所在的口铸。
+ */
+/** 一次失败发生的地方(闭集):落点加那一步交给操作系统的真实路径(`dir-create-temp` 是要建的临时文件,点名的目录是它的父目录;`rename` 是被盖过的真文件;
+ *  `remove` / `write` 是那份文件;`read` 是读的目录或文件)。 */
+export type FsFailureSite = {
+    readonly landing: "dir-create-temp";
+    readonly path: string;
+} | {
+    readonly landing: "rename";
+    readonly path: string;
+} | {
+    readonly landing: "remove";
+    readonly path: string;
+} | {
+    readonly landing: "read";
+    readonly path: string;
+    readonly of: "directory" | "file";
+} | {
+    readonly landing: "write";
+    readonly path: string;
+};
+/** 一次文件系统失败的句子(纯函数)。 */
+export declare function fsFailureSentence(site: FsFailureSite, cause: unknown): string;
+/** 原子写器抛的错:句子见 {@link fsFailureSentence};`code` 照抄底层 errno(按 `code` 分支的调用方不受影响),原错误在 `cause`。 */
+export declare class FsFailure extends Error {
+    readonly landing: FsFailureSite["landing"];
+    readonly code: string | undefined;
+    constructor(site: FsFailureSite, cause: unknown);
+}
+/** 取一次失败的句子:{@link FsFailure}(已在更细的落点铸过)原样用,别的错按调用方所在的口 `site` 铸。 */
+export declare function fsFailureMessage(site: FsFailureSite, err: unknown): string;

package/dist/fs-failure.js

@@ -0,0 +1,83 @@
+/**
+ * 包内私有(不进主桶、不进 exports 表;零 `node:` 依赖):**文件系统失败句的唯一铸点** —— `(errno, 落点, 真实路径)` → 一句。
+ * 本包凡是把文件系统错误说成人话的地方(原子写器、命令行的写 / 删口、目录迁移的读口)都调 {@link fsFailureSentence},没有第二处手写的 `cannot …` 句子
+ * (`test/` 下的 `fs-failure-single-mint-gate` 门扫 `src/` 里的字符串字面量,铸点之外出现即红)。
+ *
+ * 落点({@link FsFailureSite}.`landing`,闭集)按失败发生在哪一步分句 —— 同一个 errno 在不同落点指向不同的东西:
+ *  · `dir-create-temp` —— 原子写器在目标所在目录里建临时文件。目录不让建 ⇒ 点名**目录**(文件本身没错);
+ *  · `rename`          —— 原子写器 `rename` 盖过目标。目录收了新文件、却换不掉这一份 ⇒ 点名**真文件**;
+ *  · `remove`          —— 删一个文件。删的是目录项:目录不让删 ⇒ 点名文件所在的**目录**(与建临时文件同一个因);
+ *  · `read`            —— 读一个目录或文件;
+ *  · `write`           —— 写口整体失败、步骤看不见(注入的写口抛的错,不是本包原子写器抛的):只点名要写的文件。
+ * 认得的 errno 给那一步对应的出路,别的 errno(磁盘满、I/O 错 …)给 Node 自己的句子 —— 照样响亮,只是不替它猜出路。两条与落点无关的律:
+ *  · errno 只打一遍 —— 句首括号里一次,Node 句子自带的 `<errno>: ` 前缀去掉;
+ *  · `ENAMETOOLONG`(路径某一节或整条超限)既不是目录的错也不是文件的错 ⇒ 一句 `path too long: <被操作系统拒的路径> (ENAMETOOLONG)`,不点名目录、不给权限类出路。
+ * 目录落点(`dir-create-temp` / `remove`)的 `EPERM` / `EROFS` 出路句尾加「目录可能是只读 / 不可变(chflags / chattr)」—— 改权限位修不好的那两种。
+ *
+ * 原子写器抛 {@link FsFailure}(句子在 `message`,`code` 照抄底层 errno,原错误在 `cause`);它在写器内部已经按更细的落点铸过句子,
+ * 命令行 / 迁移用 {@link fsFailureMessage} 取句 —— 已经是 {@link FsFailure} 的原样用,否则按它所在的口铸。
+ */
+/** `dir-create-temp` 里「目录本身不让建文件」的 errno:权限不够、只读文件系统、目录不在。出路 = 让目录可写。 */
+const DIRECTORY_NOT_WRITABLE = new Set(["EACCES", "EPERM", "EROFS", "ENOENT"]);
+/** `remove` 里「目录不让删目录项」的 errno(同一个因:目录不可写)。目录不在 / 文件已不在(ENOENT)不是这个因,给 Node 自己的句子。 */
+const DIRECTORY_ENTRY_NOT_REMOVABLE = new Set(["EACCES", "EPERM", "EROFS"]);
+/** `rename` 里「目录收新文件、却换不掉这一份」的 errno:不可变标志、粘滞目录里别人的文件。出路 = 让文件可被替换。 */
+const FILE_NOT_REPLACEABLE = new Set(["EACCES", "EPERM"]);
+/** 目录落点(`dir-create-temp` / `remove`)的出路。`EPERM`(目录带不可变标志:macOS `chflags uchg`、Linux `chattr +i`)与 `EROFS`(只读文件系统)靠改权限位修不好,
+ *  出路句尾提示这一种可能;`EACCES` / `ENOENT` 是纯权限位 / 目录不在,出路就是让目录可写。 */
+const directoryWayOut = (code) => (code === "EPERM" || code === "EROFS" ? "make the directory writable; directory may be read-only or immutable (chflags / chattr)" : "make the directory writable");
+const errnoOf = (e) => {
+    const code = e?.code;
+    return typeof code === "string" ? code : undefined;
+};
+/** Node 自己的句子,折成一行;开头自带的 `<errno>: ` 去掉(errno 由句首的 `(<errno>)` 打一遍,不打两遍)。 */
+const nodeSentenceOf = (e, code) => {
+    const line = (e instanceof Error ? e.message : String(e)).replace(/\s*\n\s*/g, " ");
+    return code !== undefined && line.startsWith(`${code}: `) ? line.slice(code.length + 2) : line;
+};
+/** 路径的父目录(字符串切法,零 `node:` 依赖;两种分隔符都认)。根下的文件 ⇒ 根;没有分隔符 ⇒ 当前目录。 */
+const parentDirectory = (p) => {
+    const i = Math.max(p.lastIndexOf("/"), p.lastIndexOf("\\"));
+    return i < 0 ? "." : i === 0 ? p.slice(0, 1) : p.slice(0, i);
+};
+/** 一次文件系统失败的句子(纯函数)。 */
+export function fsFailureSentence(site, cause) {
+    const code = errnoOf(cause);
+    // 路径本身不能用(某一节超过 NAME_MAX、整条超过 PATH_MAX):与落点无关,既不是目录的错也不是文件的错 —— 一句点名被操作系统拒的路径。
+    if (code === "ENAMETOOLONG")
+        return `path too long: ${site.path} (${code})`;
+    const tag = code === undefined ? "" : ` (${code})`;
+    switch (site.landing) {
+        case "dir-create-temp":
+            return `cannot write into directory ${parentDirectory(site.path)}${tag}: ${code !== undefined && DIRECTORY_NOT_WRITABLE.has(code) ? directoryWayOut(code) : nodeSentenceOf(cause, code)}`;
+        case "rename":
+            return code !== undefined && FILE_NOT_REPLACEABLE.has(code)
+                ? `cannot replace ${site.path}${tag}: make the file replaceable — clear an immutable flag; in a sticky directory only the file's owner may replace it`
+                : `cannot replace ${site.path}${tag}: ${nodeSentenceOf(cause, code)}`;
+        case "remove":
+            return `cannot remove ${site.path} from directory ${parentDirectory(site.path)}${tag}: ${code !== undefined && DIRECTORY_ENTRY_NOT_REMOVABLE.has(code) ? directoryWayOut(code) : nodeSentenceOf(cause, code)}`;
+        case "read":
+            return `cannot read ${site.of === "directory" ? "directory " : ""}${site.path}${tag}: ${nodeSentenceOf(cause, code)}`;
+        case "write":
+            return `cannot write ${site.path}${tag}: ${nodeSentenceOf(cause, code)}`;
+        default: {
+            const unhandled = site;
+            throw new Error(`fsFailureSentence: unhandled landing ${JSON.stringify(unhandled)}`);
+        }
+    }
+}
+/** 原子写器抛的错:句子见 {@link fsFailureSentence};`code` 照抄底层 errno(按 `code` 分支的调用方不受影响),原错误在 `cause`。 */
+export class FsFailure extends Error {
+    landing;
+    code;
+    constructor(site, cause) {
+        super(fsFailureSentence(site, cause), { cause });
+        this.name = "FsFailure";
+        this.landing = site.landing;
+        this.code = errnoOf(cause);
+    }
+}
+/** 取一次失败的句子:{@link FsFailure}(已在更细的落点铸过)原样用,别的错按调用方所在的口 `site` 铸。 */
+export function fsFailureMessage(site, err) {
+    return err instanceof FsFailure ? err.message : fsFailureSentence(site, err);
+}

package/dist/hooks.d.ts

@@ -2283,6 +2283,36 @@ export type HookMatcherForm = "literal" | "regex" | "invalid";
  * 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;
+/** One reference in a header value that {@link interpolateHookEnvVars} replaced with the empty string —— what the caller records. */
+export interface HookEnvBlank {
+    /** The header (its name, as keyed in the input) whose value held the reference. */
+    readonly header: string;
+    /** The variable name as written in the reference. The value is never part of this record. */
+    readonly name: string;
+    /** `"not-allowed"` —— the name is not in the hook's `allowedEnvVars`. `"credential"` —— the name is a credential variable, which no list releases. */
+    readonly reason: "not-allowed" | "credential";
+}
+/** What {@link interpolateHookEnvVars} returns: the headers as they go on the wire + the references it blanked. */
+export interface HookEnvInterpolation {
+    readonly headers: Record<string, string>;
+    /** In header order, then first-occurrence order within a header; a name that is referenced several times in one header is listed once. */
+    readonly blanked: readonly HookEnvBlank[];
+}
+/**
+ * The one reading of `$VAR` / `${VAR}` in an http hook's header values —— the shell and the server both call this; neither keeps a copy,
+ * so one hook definition puts the same bytes on the wire from either. The reading is CC 2.1.296's (`cli296.js:249576`), byte for byte:
+ *
+ *  · only header **values** are read (header names are never touched);
+ *  · a reference is `$NAME` or `${NAME}` with NAME = `[A-Z_][A-Z0-9_]*`; anything else (lower case, a digit first, `${}`, an unclosed `${`) is plain text;
+ *  · a name in `allowedEnvVars` ⇒ the env value (`""` when `env` has none —— expanded to empty, not listed in `blanked`);
+ *  · a name **not** in `allowedEnvVars` ⇒ `""`, listed in `blanked` (`reason: "not-allowed"`); its env value is not read;
+ *  · a credential variable ({@link HOOK_ENV_CREDENTIAL_NAMES}'s closed set) ⇒ `""` even when the list names it, listed in `blanked` (`reason: "credential"`);
+ *  · CR / LF / NUL are removed from every resulting header value, references or not.
+ *
+ * The caller decides what to do with `blanked` (a debug line per entry is what CC writes); the headers are final either way.
+ * Pure: no I/O, no logging, no global env —— `env` is the caller's view (`process.env` at the call site). Inputs are not modified.
+ */
+export declare function interpolateHookEnvVars(headers: Readonly<Record<string, string>>, allowedEnvVars: readonly string[], env: Readonly<Record<string, string | undefined>>): HookEnvInterpolation;
 /**
  * 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

@@ -768,6 +768,87 @@ export function hookMatcherForm(matcher) {
         }
     }
 }
+/** `${NAME}` or `$NAME`, NAME = `[A-Z_][A-Z0-9_]*` —— upper-case names only (lower-case and digit-led spellings are not references). */
+const HOOK_ENV_REFERENCE = /\$\{([A-Z_][A-Z0-9_]*)\}|\$([A-Z_][A-Z0-9_]*)/g;
+/** CR, LF and NUL never reach a header value (header injection through an env value or a configured template). */
+const HOOK_HEADER_FORBIDDEN = /[\r\n\0]/g;
+/**
+ * The credential variables an http hook header never receives, whatever `allowedEnvVars` says. The closed name set of CC 2.1.296
+ * (`cli296.js:237450` `_nn` / `ynn`, `:246731` `lGn` / `bft` / `hGn` / `vft`): 27 base names, each also under an `INPUT_` prefix
+ * (the spelling a CI action passes an input in). A name set, not a pattern —— `MY_TOKEN` is an ordinary variable.
+ * CC 296 also blanks, unless the managed policy lists the name, a second family decided from env values and live state
+ * (remote-sink names, proxy / registry URLs …); that family needs inputs this function does not take and is not part of this reading.
+ */
+const HOOK_ENV_CREDENTIAL_NAMES = new Set([
+    // CC 296 `_nn`: the OAuth token, the five file-descriptor spellings (`ynn`), then the bridge / device / proxy / background-session tokens
+    "CLAUDE_CODE_OAUTH_TOKEN",
+    "CLAUDE_CODE_OAUTH_TOKEN_FILE_DESCRIPTOR",
+    "CLAUDE_CODE_GATEWAY_TOKEN_FILE_DESCRIPTOR",
+    "CLAUDE_CODE_API_KEY_FILE_DESCRIPTOR",
+    "CLAUDE_CODE_WEBSOCKET_AUTH_FILE_DESCRIPTOR",
+    "CCR_AGENT_PROXY_TOKEN_FILE_DESCRIPTOR",
+    "CLAUDE_CODE_ARTIFACTS_API_TOKEN",
+    "CLAUDE_CODE_SLACK_TAG_TOKEN",
+    "CLAUDE_CODE_HFI_BEARER_TOKEN",
+    "CLAUDE_BRIDGE_OAUTH_TOKEN",
+    "CLAUDE_TRUSTED_DEVICE_TOKEN",
+    "AGENT_PROXY_AUTH_TOKEN",
+    "CLAUDE_CODE_MCP_SERVE_AUTH_TOKEN",
+    "CLAUDE_BG_AUTH_SNAPSHOT_PATH",
+    "CLAUDE_BG_SOCKET_TOKENS_PATH",
+    "CLAUDE_BG_RV_AUTH",
+    "CLAUDE_BG_PTY_AUTH",
+    "CLAUDE_BG_CLAIM_AUTH",
+    // CC 296 `lGn`: refresh / ingress / host-credential / messaging tokens, MCP client secrets, runner secrets
+    "CLAUDE_CODE_OAUTH_REFRESH_TOKEN",
+    "CLAUDE_SESSION_INGRESS_TOKEN_FILE",
+    "CLAUDE_CODE_HOST_CREDS_FILE",
+    "CLAUDE_CODE_MESSAGING_TOKEN",
+    "MCP_CLIENT_SECRET",
+    "MCP_XAA_IDP_CLIENT_SECRET",
+    "ENVIRONMENT_SERVICE_KEY",
+    "SELF_HOSTED_RUNNER_POOL_SECRET",
+    "SELF_HOSTED_RUNNER_ENVIRONMENT_SECRET",
+].flatMap((name) => [name, `INPUT_${name}`]));
+/**
+ * The one reading of `$VAR` / `${VAR}` in an http hook's header values —— the shell and the server both call this; neither keeps a copy,
+ * so one hook definition puts the same bytes on the wire from either. The reading is CC 2.1.296's (`cli296.js:249576`), byte for byte:
+ *
+ *  · only header **values** are read (header names are never touched);
+ *  · a reference is `$NAME` or `${NAME}` with NAME = `[A-Z_][A-Z0-9_]*`; anything else (lower case, a digit first, `${}`, an unclosed `${`) is plain text;
+ *  · a name in `allowedEnvVars` ⇒ the env value (`""` when `env` has none —— expanded to empty, not listed in `blanked`);
+ *  · a name **not** in `allowedEnvVars` ⇒ `""`, listed in `blanked` (`reason: "not-allowed"`); its env value is not read;
+ *  · a credential variable ({@link HOOK_ENV_CREDENTIAL_NAMES}'s closed set) ⇒ `""` even when the list names it, listed in `blanked` (`reason: "credential"`);
+ *  · CR / LF / NUL are removed from every resulting header value, references or not.
+ *
+ * The caller decides what to do with `blanked` (a debug line per entry is what CC writes); the headers are final either way.
+ * Pure: no I/O, no logging, no global env —— `env` is the caller's view (`process.env` at the call site). Inputs are not modified.
+ */
+export function interpolateHookEnvVars(headers, allowedEnvVars, env) {
+    const allowed = new Set(allowedEnvVars);
+    const blanked = [];
+    const entries = Object.entries(headers).map(([header, value]) => {
+        const listed = new Set();
+        const blank = (name, reason) => {
+            if (!listed.has(name)) {
+                listed.add(name);
+                blanked.push({ header, name, reason });
+            }
+            return "";
+        };
+        const expanded = value.replace(HOOK_ENV_REFERENCE, (reference) => {
+            const name = reference.startsWith("${") ? reference.slice(2, -1) : reference.slice(1);
+            if (!allowed.has(name))
+                return blank(name, "not-allowed");
+            if (HOOK_ENV_CREDENTIAL_NAMES.has(name))
+                return blank(name, "credential");
+            return env[name] ?? "";
+        });
+        return [header, expanded.replace(HOOK_HEADER_FORBIDDEN, "")];
+    });
+    // fromEntries defines own properties: a header keyed `__proto__` stays a header instead of replacing the prototype.
+    return { headers: Object.fromEntries(entries), blanked };
+}
 export const HooksConfig = z.partialRecord(HookEventName, z.array(HookMatcherEntry));
 /**
  * DESIGN POINT ③ (slot semantics — RESERVED, core to finalize): how `spec.hooks` composes with the

package/dist/local-load.js

@@ -23,9 +23,10 @@ export function remoteExecPath(root) {
 /** 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. */
 export async function loadRemoteExec(root) {
+    const file = remoteExecPath(root);
     let text;
     try {
-        text = await readFile(remoteExecPath(root), "utf8");
+        text = await readFile(file, "utf8");
     }
     catch (e) {
         if (e.code === "ENOENT")
@@ -36,7 +37,7 @@ export async function loadRemoteExec(root) {
     // 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. 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));
+    return parseRemoteExecDocument(judgeConfigDText(REMOTE_EXEC_DOCUMENT, text, file));
 }
 /** 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. */

package/dist/safety-merge-spec.d.ts

@@ -53,8 +53,8 @@
 import { z } from "zod";
 /** How values from different layers/principals combine for a category. */
 export declare const MergeShape: z.ZodEnum<{
-    replace: "replace";
     concat: "concat";
+    replace: "replace";
     denyFirst: "denyFirst";
     runAll: "runAll";
     overrideByName: "overrideByName";
@@ -185,8 +185,8 @@ export declare const TightenRule: z.ZodDiscriminatedUnion<[z.ZodObject<{
 export type TightenRule = z.infer<typeof TightenRule>;
 export declare const MergeCategorySpec: z.ZodObject<{
     mergeShape: z.ZodEnum<{
-        replace: "replace";
         concat: "concat";
+        replace: "replace";
         denyFirst: "denyFirst";
         runAll: "runAll";
         overrideByName: "overrideByName";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/settings-schema",
-  "version": "12.0.0",
+  "version": "12.1.0",
   "description": "Sema settings schema — pure config contract (zod domains + effective-config + roster resolution + ref-integrity + remoteExec) shared by sema-web-admin, sema-server, and the TOC desktop/CLI. One source of truth. (Renamed at 1.0.0 from @sema-agent/registry-core — name and docs only, no behavior change; note the range moves 0.19.0 -> 1.0.0, so a dependency must become ^1.0.0. The old names @sema-agent/registry-core <=0.19.0 and @sema-ai/registry-core remain published, frozen, for migration.)",
   "type": "module",
   "license": "BUSL-1.1",

package/dist/write-failure.d.ts

@@ -1,16 +0,0 @@
-/**
- * 包内私有(不进主桶、不进 exports 表;零 `node:` 依赖):原子写器(`./atomic-write`)写失败的**唯一一句** —— 按失败落在哪一步、errno 是什么分句,
- * 句尾给那一步对应的出路。写器有两步:在目标所在目录里建临时文件(`create`,连同恢复沿用的模式)、`rename` 盖过目标(`replace`)。
- * 改前一句话包打天下(「cannot write <文件>: <Node 的错误句> … fix the cause」):目录不可写时点名的却是文件(Node 句子里是临时文件的路径),
- * 而可写目录里的只读文件照常写得进 —— 句子把人指向了错的那一个。命令行(`./cli`)认这只错误类型、原样印它的句子。
- */
-/** 原子写的两步(闭集)。 */
-export type AtomicWriteStep = "create" | "replace";
-/** 一次写失败的句子(纯函数)。认得的 errno 给对应出路;别的 errno(磁盘满、I/O 错 …)给 Node 自己的句子 —— 照样响亮,只是不替它猜出路。 */
-export declare function atomicWriteFailureSentence(step: AtomicWriteStep, dir: string, file: string, cause: unknown): string;
-/** 原子写器抛的错:句子见 {@link atomicWriteFailureSentence};`code` 照抄底层 errno(按 `code` 分支的调用方不受影响),原错误在 `cause`。 */
-export declare class AtomicWriteFailure extends Error {
-    readonly step: AtomicWriteStep;
-    readonly code: string | undefined;
-    constructor(step: AtomicWriteStep, dir: string, file: string, cause: unknown);
-}

package/dist/write-failure.js

@@ -1,43 +0,0 @@
-/**
- * 包内私有(不进主桶、不进 exports 表;零 `node:` 依赖):原子写器(`./atomic-write`)写失败的**唯一一句** —— 按失败落在哪一步、errno 是什么分句,
- * 句尾给那一步对应的出路。写器有两步:在目标所在目录里建临时文件(`create`,连同恢复沿用的模式)、`rename` 盖过目标(`replace`)。
- * 改前一句话包打天下(「cannot write <文件>: <Node 的错误句> … fix the cause」):目录不可写时点名的却是文件(Node 句子里是临时文件的路径),
- * 而可写目录里的只读文件照常写得进 —— 句子把人指向了错的那一个。命令行(`./cli`)认这只错误类型、原样印它的句子。
- */
-/** `create` 步里「目录本身不让建文件」的 errno:权限不够、只读文件系统、目录不在。出路 = 让目录可写。 */
-const DIRECTORY_NOT_WRITABLE = new Set(["EACCES", "EPERM", "EROFS", "ENOENT"]);
-/** `replace` 步里「目录收新文件、却换不掉这一份」的 errno:不可变标志、粘滞目录里别人的文件。出路 = 让文件可被替换。 */
-const FILE_NOT_REPLACEABLE = new Set(["EACCES", "EPERM"]);
-const errnoOf = (e) => {
-    const code = e?.code;
-    return typeof code === "string" ? code : undefined;
-};
-const messageOf = (e) => (e instanceof Error ? e.message : String(e)).replace(/\s*\n\s*/g, " ");
-/** 一次写失败的句子(纯函数)。认得的 errno 给对应出路;别的 errno(磁盘满、I/O 错 …)给 Node 自己的句子 —— 照样响亮,只是不替它猜出路。 */
-export function atomicWriteFailureSentence(step, dir, file, cause) {
-    const code = errnoOf(cause);
-    const tag = code === undefined ? "" : ` (${code})`;
-    switch (step) {
-        case "create":
-            return code !== undefined && DIRECTORY_NOT_WRITABLE.has(code) ? `cannot write into directory ${dir}${tag}: make the directory writable` : `cannot write into directory ${dir}${tag}: ${messageOf(cause)}`;
-        case "replace":
-            return code !== undefined && FILE_NOT_REPLACEABLE.has(code)
-                ? `cannot replace ${file}${tag}: make the file replaceable — clear an immutable flag; in a sticky directory only the file's owner may replace it`
-                : `cannot replace ${file}${tag}: ${messageOf(cause)}`;
-        default: {
-            const unhandled = step;
-            throw new Error(`atomicWriteFailureSentence: unhandled step ${String(unhandled)}`);
-        }
-    }
-}
-/** 原子写器抛的错:句子见 {@link atomicWriteFailureSentence};`code` 照抄底层 errno(按 `code` 分支的调用方不受影响),原错误在 `cause`。 */
-export class AtomicWriteFailure extends Error {
-    step;
-    code;
-    constructor(step, dir, file, cause) {
-        super(atomicWriteFailureSentence(step, dir, file, cause), { cause });
-        this.name = "AtomicWriteFailure";
-        this.step = step;
-        this.code = errnoOf(cause);
-    }
-}