@sema-agent/settings-schema 1.2.0 → 1.4.0

package/CHANGELOG.md

@@ -6,6 +6,173 @@
 > `@sema-agent/registry-core`(更早还曾是 `@sema-ai/registry-core`)。本档 `0.19.0` 以下各节里的
 > 包名是**历史记录**,如实保留不追改。
 
+## 1.4.0 — 2026-09-02 — settings-schema 批八件(DEBTS-server S-59;新键=minor 按本批成文政策)
+
+七件 = 两把新可选键(①⑥,additive)+ 三件文案/论证面(②③④)+ 一件文档重写(⑤)+ 一件发布物中性化(⑦)。
+
+**① `McpServerSpec.contentOrigin?: "local"|"execution"|"external"`(A-075.4 / A-075.111④)** + 新导出
+`MCP_CONTENT_ORIGINS` / `McpContentOrigin`。病:默认 strip 的 zod object 没有该键,部署方写在
+`config.d/mcp.json` 的信任出处声明在本地腿(FileConfigStore)与远端消费腿(readEffectiveWire)各被剥一次,
+消费方的词表门结构性够不着。修:可选枚举键、无默认(缺席 = 引擎 pre-declaration 行为,fail-closed 全判
+external);表外值 parse 拒(大小写不折——信任词写坏绝不折成合法词)。钉 `test/mcp-content-origin.test.ts`
+六判据(保值 / 缺席恒缺席 / 拒表外 / 本地 round-trip / wire 透传 / 词表镜像字面量钉——与引擎/消费方的相等由
+消费方的编译钉+提货门执法,本仓刻意不带引擎依赖轴,钉只拒本地静默改词)。消费方提货后其两条
+`it.fails` 绊线按约翻正(见发布帖点名)。
+
+**② `hooks.ts` `SyncHookOutput` 文案(A-075.15)**:「any other exit = non-blocking error (stderr shown to
+the user)」→ 点名消费方真机制——非阻断故障(exit≠0∧≠2 / 超时 / spawn 失败 / 坏 JSON)由 hook-runner 铸
+`hook_non_blocking_failure` 通知(`hook_notice` 帧上任务/fleet 流;stderr 先脱敏后截断 512 字);本包无
+「展示给用户」的面,用户看到什么取决于其客户端如何渲染该帧。改注不改行为。
+
+**③ `LimitsConfig` `.passthrough()` 论证重写(A-075.33)**:原论证依赖「消费方 `^0.x`、脱字号不跨 minor」,
+1.0.0 改名后消费方段进 1.x(`^1.x` 跨 minor),前提失效。重写为 1.x 语境:键集按消费方发布节奏生长
+(消费方先开键读 env 底、契约层后声明),「认识键→声明键」的窗口由**发包与提货**决定(server 精确 pin /
+cli lockfile 钉住的 `^1.x` 皆需显式提货),与 range 写法无关;默认 strip 会把窗口变成天花板静默回落 env 底。
+**决策与行为零变**(`.passthrough()` 一字未动,`limits-domain-0.19.test.ts` ⑤b 行为钉照旧);补写失效条件
+与「改回 strip/`.strict()` = 行为面收紧,须走 BREAKING 通道」。同批改 `test/limits-domain-0.19.test.ts` ⑤b
+注释同口径。
+
+**④ README「发版纪律(semver)」1.x 政策成文(A-075.34)**:破坏性(改名/改形/删除/默认值变更/校验收紧
+或放宽/枚举重排)必 bump **major**;新键/新导出/词表尾插 = **minor**(穷举表消费方提货编译红 = 提货成本,
+发布走显式表态制点名,不因此升 major——1.2.0/1.3.0 口径,codex 严格 semver 异议原样留档候裁);文案/注释/
+测试/bug 修复 = **patch**。0.x 规矩撤为历史注记(0.7.1 例外一并归档);CLAUDE.md / ROADMAP /
+docs/CONSUMER-INTEGRATION §9 同步改写;本档 1.0.0 段的旧指路(「1.x 规矩待后续批补」)撤,改指本段。
+
+**⑤ `llms.txt` / `llms-full.txt` 重写(A-075.35)**:自 0.1.30(2026-06-23)STALE(15 域时代;错称
+「无 CHANGELOG、无 git tag」等已烂断言)。无生成脚本,按当前树手写事实版:17 域 / 21 subpath / 31 hook
+事件 / 7 provider / 五族纯契约(hooks·fleet·scheduler-store·safety-merge-spec·api)全部入档;证据坐标改
+「文件: 符号」形(行号逐版腐烂);撤 STALE 横幅。防再烂:`test/docs-hygiene.test.ts` D 组把「包版本:」行
+钉到 package.json、域数/事件数/subpath 数钉到运行时表——**发版 bump 时须同步改两档各一行版本号**。
+
+**⑥ `EntitlementRuntimeCaps.allowMemoryOptOut?: boolean`(A-075.99 另半)** + `RUNTIME_CAP_STRICT.
+allowMemoryOptOut = false`。语义对表消费方 `RuntimeCaps.allowMemoryOptOut`(design/383 §3.1):`false` =
+该 principal 强制留存(opt-out 声明被拒,terminal `memory.capture_optout_denied`);`true` = 显式无限制;
+缺席 = center 不表态、**不下发键**(三态;隐私轴故障过境契约:resolver 故障 = 键缺席,绝不铸 `false` 替身
+——`open` 姿态故障放行+具名披露,`governed` 姿态 verdict 缺席拒跑,两臂都以故障为输入)。合成极性 allow*
+族(`false` 胜,见 RUNTIME_CAP_STRICT)。消费方侧:本地 grant 表优先、center 值其次;其 cap 映射
+(`toCoreRuntimeCaps`)今日**不含**本键,提货后补一行才到引擎——在那之前本键只是「parse 不再剥、wire 承运」
+(窗口如实:center 先发 `false` 而消费方未提货时,引擎仍只读本地 grant 表——与此前「键被静默 strip」相比,多的是 wire 在场 + 成文披露,少的是零;发布协调走表态制点名,消费方提货批同时补映射行与其 contentOrigin 双绊线翻正)。
+钉 `test/entitlement.test.ts` 末段五格。
+
+**⑧ `SAFETY_MERGE_SPEC.sandboxNetwork` 成员级准入 `members`(S-59 件八,cli 上收候件)**:此前 sandboxNetwork
+是整键类目(global floor 拒/收整块),cli 壳侧「哪个 sandbox 子键算收紧」方向表是临时落点。本版把该表的
+**方向/floor 半场**上收为 11 员闭集 members(全部 `tighten@"local"`,路径形键名:enabled /
+allowUnsandboxedCommands / autoAllowBashIfSandboxed / enableWeakerNestedSandbox / enableWeakerNetworkIsolation /
+network.allowManagedDomainsOnly / network.allowAllUnixSockets / network.allowLocalBinding /
+filesystem.allowManagedReadPathsOnly / filesystem.denyWrite / filesystem.denyRead)。**刻意不入表**(按 1.1.0
+头注法:未声明成员回落类目 minTrust "global" = 消费方 fail-closed 扣下臂,未来新子键默认被扣):放宽面
+(allowedDomains / allowUnixSockets / allowWrite / allowRead / excludedCommands / ignoreViolations / ripgrep)、
+可用性硬闸 failIfUnavailable(安全轴收紧但后果=拒启,克隆仓两键 DoS 形,随放宽面同 floor)、
+indeterminate 三条候 cli 对表(httpProxyPort / socksProxyPort / enabledPlatforms,unlisted 即 fail-closed)。
+布尔成员的**值向极性已建模**(codex 末轮 [high] 采纳——只发方向不发极性会让「按表办事」的消费方在 local
+层放行 `enabled:false` 这类松极写,比整键现状更松):`MemberAdmission` 增可选 `boolPole {strict, minTrust}`,
+准入解析改值向(`memberAdmission(类目, 成员, 值?)`,严格相等判极、绝不 truthiness);九个布尔成员行 floor 留在
+松面 "global" + `boolPole.minTrust:"local"`——**代际安全律**:不识 boolPole 的老 schema 剥掉该键后读到
+tighten@global,对低信任层两极皆扣(fail-closed,只损失低信任收紧的便利,绝不放行松极);两个 deny 数组
+每种写法都收窄,保持素 tighten@local。红先:双极钉先红(tsc 值参不存在 ×9 + 松极 floor 断言红)→ 建模后绿;
+FROZEN 1.1.0 钉同步断言「1.1.0 消费方看到的剥后视图 = 全布尔 tighten@global」(独立字面量)。
+类目行五轴(mergeShape/minTrust/tighten/enforcement/seam)一字未动 ⇒ pre-members 消费方整键行为逐字节不变
+(FROZEN 1.1.0 钉演进为「全表相等除 sandboxNetwork;其去 members 后与 1.1.0 字面量相等」——照 FROZEN 1.0.0
+permissions 先例形)。红先:3 新钉先红(members 缺席)→ 加表后 2 旧守钉红(permissions-唯一钉 + 1.1.0 全表钉,
+证明守钉真在看表)→ 演进后全绿。cli 到货动作:sandboxKeyGate 方向表退役改走 `memberAdmission("sandboxNetwork", 子键)`。
+
+**⑦ 发布物内部工艺词中性化(消费方 cli 点名件)**:按其 dist 卫生棘轮三族口径(`board \[\d` /
+`clay (拍|亲|令|裁|定|问责)` / `sema-server\b`)扫**全 src**(不止点名三文件),注释/文档面逐处中性化
+(帖号 → `[ref]`、人名令词 → 「产品裁定/产品令」等角色词、内部仓名 → 「worker 服务/消费方」);另清
+`Clay's decision` 等裸人名形(dist 裸人名现为 0)。**运行期默认值 `image: ….default("sema-server:latest")`
+一字不动**——成文理由:它是行为面(未显式配 image 的部署实际拉取的镜像名),且是公开镜像名、与 npm 包名
+同源,非内部工艺词;改它 = 部署可见变更,须走 BREAKING 通道 + 迁移注,不随注释批盲动([5958] 表态原文)。
+计数(cli 计数法,build 后 literal 视图,三族合计):点名三文件 `dist/types.js` 15→1 / `dist/remote-exec.js`
+4→0 / `dist/remote-exec.d.ts` 4→0;**全 dist 52→1**,唯一剩余 = 上述默认值行。钉
+`test/docs-hygiene.test.ts` E 组(src 三族零命中、唯一放行行 = 该默认值字面;裸人名零命中)。
+
+## 1.3.0 — hooks 域加员 `DirectoryAdded`(CC 2.1.219 新事件;`HooksConfig` 拒键病形修复)
+
+**`HOOK_EVENTS` 30 → 31:`POST_198_HOOK_EVENTS` **尾插** `DirectoryAdded`(1.2.0 三员声明序逐字节不动;重排 = BREAKING,
+免裁)。additive:既有 30 员的 matcher 字段 / owner / 输入形 / `hookSpecificOutput` 臂一字不动(FROZEN 1.2.0 全表字面量夹具钉,
+`test/hooks-directory-added-1.3.0.test.ts`,字面量独立誊自 bfbd140、非从现表派生——1.1.0/1.2.0 safety-merge-spec 夹具同律)。
+版号 minor = 加词(1.2.0 口径)。**
+
+### 病形(修前)
+
+`HooksConfig = z.record(HookEventName, …)` 键集**闭合**(设计如此:wire 上抓 typo)——用户 settings 里 `hooks.DirectoryAdded`
+(壳自 CC 2.1.219 起真会点亮的事件)在 1.2.0 下**整条** hooks 配置被拒(zod `Invalid enum value` at key);同时 `HookInput`
+union 无该臂、`HookEventName` 不收该词。壳认得、schema 不收——与 cli `hooksSchema218.test.ts` 建门帖所述「壳自己认得的
+输入形,壳自己的注册面不收」同形。
+
+### CC 真形(亲读镜像坐标,非按名推断)
+
+来源 = cli 树 `node_modules/@sema-agent/agent-types`(`@anthropic-ai/claude-agent-sdk@0.3.220` `sdk.d.ts` 的镜像,CC 2.1.220,
+与 0.3.219 逐字节同):
+
+- `hooks.d.ts:582-586` `DirectoryAddedHookInput = BaseHookInput & { hook_event_name:'DirectoryAdded'; directory:string;
+  source:'slash_command'|'register_repo_root' }`,`@since CC 2.1.219`(:574-575:目录经 `/add-dir` 或 repo-root 注册加入会话
+  工作集;cli `hooksConfigManager.ts:283-287` 文案:`directory` 为绝对路径)。
+- `hooks.d.ts:638` / `runtime.d.ts:111`:CC 序位于 `FileChanged` 与 `MessageDisplay` 之间;本包**尾插**——声明序非规范,
+  枚举当集合用(与 `MinTrust` 1.2.0 同律);夹具钉「1.2.0 三十员 = `HOOK_EVENTS` 逐字节前缀」。
+- `hooks.d.ts:14-17`:上游**无** `hookSpecificOutput` 臂——本版不加臂,测试钉「缺席」(非遗漏)。
+- **matcher 语义**:cli `src/utils/hooks.ts:1706-1760` `getMatchingHooks` 开关**无** `DirectoryAdded` 臂 → 落 `default` →
+  `matchQuery` 空 → 所有 matcher 组皆触发;`hooksConfigManager.ts` 该员亦无 `matcherMetadata` ⇒
+  `HOOK_EVENT_MATCHER_FIELD.DirectoryAdded = null`(与 CwdChanged / MessageDisplay 同族;entry 上写 `matcher` 仍是合法配置,
+  只是不被查阅)。
+- **owner = `shell`**(工作集在壳;`ENGINE_OWNED_HOOK_EVENTS` 9 员不动,`HOOK_EVENT_OWNER` 为派生表、自动含新员)。
+
+### API 形(全文)
+
+```ts
+export const POST_198_HOOK_EVENTS = ["CwdChanged", "FileChanged", "MessageDisplay", "DirectoryAdded"] as const; // 尾插
+export const DIRECTORY_ADDED_SOURCES = ["slash_command", "register_repo_root"] as const;
+export const DirectoryAddedHookInput = BaseHookInput.extend({
+  hook_event_name: z.literal("DirectoryAdded"),
+  directory: z.string(),
+  source: z.enum(DIRECTORY_ADDED_SOURCES),
+});
+export type DirectoryAddedHookInput = z.infer<typeof DirectoryAddedHookInput>;
+// HookInput union + 1 臂(尾);HOOK_EVENT_MATCHER_FIELD + 1 行(null);HookSpecificOutput 不动;HooksSlotSemantics 不动(非逐员表)
+```
+
+### 消费方可见(与 1.2.0 同一课:「表不动」≠「消费方零感知」)
+
+- **cli**(`package.json` 范围 `^1.2.0`,但 `package-lock.json:1261-1264` **钉 1.2.0**——`npm ci` 不会静默提到 1.3.0;
+  只有 `npm update` / 无锁重解析才命中):**运行时零影响**——cli `src/` 非测试文件对本包只 import `isAtLeast`
+  (`src/sema/settings/resolver.ts:28`),hook 符号零运行时消费(亲 grep)。提货影响全在常驻门
+  `src/types/hooksSchema218.test.ts`(以本包 `HOOK_EVENTS` 为 canonical 钉三面集合等式):亲读该门代码推断(**未实测**,
+  不动 cli 树)提货 1.3.0 后 **五条**红——**H2**(T1 缺 `DirectoryAdded`)/ **H6**(计数 30≠31)/ **H7**(字面量
+  `CANON.length === 30` 与差集 `=== 3`)/ **H8**(按 CANON 31 键铺满喂 initialize,`DirectoryAdded` 对 T1 的 partialRecord
+  是未知键 ⇒ 拒)/ **H10a**(`OLD_27 = CANON − 3` 亦含新员 ⇒ 同因拒);修法 = 该门自注「三面同动」:`coreSchemas.HOOK_EVENTS`
+  加员 + `HookInputSchema` 加臂 + H7 字面量改 31 / 4。其 :177-178 把「`DirectoryAdded` 该不该进 settings 域」记为候裁,
+  本版加员即回应该候裁项(cli 提货时表态);`coreTypes.HOOK_EVENTS`(31 员)与本版集合恰好相等。发布帖须 @cli 点名
+  (能力显式表态制)。
+- 持 `Record<HookEventName, …>` 字面量 / 对 `HookEventName` 穷举 `switch` 的消费方:升级即**编译错**(响亮,正是要的)。
+- 用 `HookEventName` / `HookInput` / `HooksConfig` 校验**外部**值的 1.2.0 消费方:收不下 `DirectoryAdded`(名词拒、整条
+  config 拒)——这正是本版修的病形;夹具钉住 1.2.0 行为供对照(frozen `z.record(z.enum(HOOK_EVENTS_1_2_0), …)` 拒、1.3.0 收)。
+- **server**(`package.json:58` **精确钉** `"1.2.0"`,无 caret——永不自动提货):亲读 `src/hooks/hook-runner.ts`——
+  `parseHooksConfig` 走 `HooksConfig.safeParse`(:200),`createTaskHooks` 按 `HOOK_EVENT_OWNER` 分流(:1179/:1185);提货后
+  wire 上 `settings.hooks.DirectoryAdded` 不再被拒,落 shell-owned 分支 = `debug("hook_events_shell_owned")` 记账不点亮不告警
+  (:1185-1188)——「配置合法但 owner 是壳」本就是既定语义(非本版新义)。server 无 `Record<HookEventName,…>` 穷举表、
+  无 30 计数钉(亲 grep src + test),提货零编译红零测试红(推断自 grep,提货批自证)。
+
+### 门
+
+- **红先**:修前 solo 跑 `test/hooks.test.ts` + `test/hooks-directory-added-1.3.0.test.ts` = **11 红**(新文件 8:集合/
+  `HooksConfig` 收键/`HookInput` 判别/导出符号/owner/matcher/前缀冻结/1.2.0 对照;`hooks.test.ts` 计数钉 3)+ `tsc --noEmit`
+  **10 错**(全在测试文件——`Record<HookEventName,…>` 无该键、union 收窄为 `never`);修后 34/34 绿、tsc 0 错。
+- **变异刀 4/4 红**(每刀后源文件复原逐字节一致):K1 `POST_198_HOOK_EVENTS` 去员 → vitest 8 红 + tsc 5 错(矩阵多余键 =
+  编译红,穷举表如约响);K2 输入字段 `directory`→`dir` → 判别钉 2 红 + tsc 1 错;K3 matcher `null`→`"directory"` → 1 红;
+  K4 重排到 CC 序(DirectoryAdded 前置 MessageDisplay)→ 前缀冻结钉 2 红。
+- **全门**:`npm run build` exit 0;`npm test` 40 文件 / 631 用例全过;`tsc --noEmit` exit 0;dist 亲验(`node -e` 加载
+  `dist/index.js`):`HOOK_EVENTS.length===31`、末员 `DirectoryAdded`、owner `shell`、matcher `null`、`HooksConfig` 收
+  `{DirectoryAdded:[…]}`;`dist/hooks.d.ts` 含 `DIRECTORY_ADDED_SOURCES` / `DirectoryAddedHookInput`(值+类型)。
+- README 无 hooks 员数句(模块清单未列 hooks 域),无需同步。
+- **codex 对抗复审 R1**(`adversarial-review`,工作树 diff):verdict needs-attention,**1 条 [high]** =「minor 发版必破
+  cli 消费方(`^1.2.0` 自动命中,契约门红),建议先落 cli 再发或改用 `^1.2.0` 选不中的版号」。处置:**不是代码缺陷,是发版
+  协同事实**(且是从本段 CHANGELOG 自述推出的)——实证如上:cli 锁文件钉 1.2.0、cli 运行时零 hook 消费、server 精确钉;
+  「破」的实体 = cli 常驻门(该门建门即自注「三面同动」),提货批修门是 cli 侧既定动作;发布走能力显式表态制 @cli。
+  「改版号避开 `^1.2.0`」= 升 major,与 1.2.0 段 codex R2 严格 semver 异议同类,当时记为**候裁项**——本版沿用 minor 口径,
+  异议原样留档供裁。另:codex 沙箱内 `npm run typecheck && npm test` exit 1——**同命令标准环境复跑 exit 0**(typecheck 0
+  错 + 40 文件 631 用例),归因 codex `--sandbox read-only` 下 vitest 写 `node_modules/.vite/vitest` 缓存失败(目录亲验存在;
+  归因为假设,复跑绿为实测)。
+
 ## 1.2.0 — `MinTrust` 排序原语 + `task` 员([5796] 序题 → [5805] schema 认领 / [5807] cli 表态三点)
 
 **新导出 `trustRank(layer)` / `isAtLeast(layer, minTrust)`——规范信任阶梯的**单源**(v2-design §1:29 逐字);
@@ -269,8 +436,8 @@ process.exit(tok.length === 0 && erased.length === 0 ? 0 : 1);
 
 **不是**「契约进入稳定期 / API 冻结」的语义信号。旧名的 `0.x` 段已走到 `0.19.0`,新名需要一个不与
 旧段混淆、也不会被 `^0.x` 脱字号规则(0.x 下不跨 minor)拖累的新起点,故直接从 `1.0.0` 开。
-⚠️ README「发版纪律(semver)」一节写的是 `0.x` 破坏性必 bump minor 的旧规矩;`1.x` 段的对应
-规矩(破坏性必 bump major)尚未成文,待后续批补。
+README「发版纪律(semver)」一节当时仍写 `0.x` 破坏性必 bump minor 的旧规矩;`1.x` 段的对应
+规矩(破坏性必 bump major)已在本档 **Unreleased 段件④** 成文(README 同节改写),此处的指路撤。
 
 ### 21 个 subpath 1:1 平移(一个不动)
 

package/README.md

@@ -5,7 +5,8 @@
 > **这是一次纯改名,不加料**:`0.19.0` → `1.0.0` 之间**零语义变更**——没有字段增删、没有校验收紧
 > (无 `.strict()` 化)、没有默认值改动、没有行为变化;`exports` 的 **21 个 subpath 一个不动**
 > (`.` / `./types` / `./node` / `./api/auth` / `./api/wire` …… 逐条 1:1 平移,只换包名前缀)。
-> 版号跳到 `1.0.0` **不是**「契约进入稳定期」的语义信号——改名需要一个不与旧 `0.x` 段混淆的新起点而已。
+> 版号跳到 `1.0.0` **不是**「契约进入稳定期」的语义信号——改名需要一个不与旧 `0.x` 段混淆的新起点而已
+> (但自 `1.0.0` 起本包按标准 semver 发版:破坏性 = major,见下文「发版纪律」)。
 >
 > **消费方迁移(两步,注意版号段也要动)**:
 > 1. `package.json` 依赖:`"@sema-agent/registry-core": "^0.19.0"` → `"@sema-agent/settings-schema": "^1.0.0"`。
@@ -129,15 +130,28 @@ local `.env`). This package never carries a credential.
 Fleet-only domains (`workers`, `hosts`, `systems`) are omitted on a single machine — they resolve to schema
 defaults. Each `config.d/<domain>.json` is exactly that domain's zod object.
 
-## 发版纪律(semver)
-
-- **0.x 破坏性变更必 bump minor**(0.7 → 0.8),不许塞 patch——`^0.7.0` 这类脱字号 range 在 0.x 下
-  会自动收 patch,把 BREAKING 塞进 patch = 未 pin 精确版的下游 `npm install` 静默拿到破坏。
-- patch 只装:additive 字段、修 bug、文档/测试。commit message 的 `feat!`/`BREAKING` 标记照旧,
-  但标记不豁免版号义务。
-- **历史注记(0.7.1,2026-07-10)**:0.7.1 携带了两件预协调 BREAKING(撤 governance effective 双写
-  镜像、撤 QuotaLease 0.5 `tokens` 别名 shim)——名义上违反本条。当时下游(center/service 1.150.0)
-  均已显式迁移、实际破坏面为零,PM 拍板不重发 0.8.0(纯扰动);本段即为该例外的收账与今后的规矩。
+## 发版纪律(semver,1.x)
+
+自 `1.0.0`(改名)起本包按**标准 semver** 发版;`0.x` 时代的「破坏性变更必 bump minor」规矩**已撤**
+(末条仅作历史注记)。判档看**消费方可见性**,不看 diff 大小:
+
+- **破坏性变更必 bump major**:字段/导出改名、改形(retype)、删除、默认值变更、校验收紧或放宽
+  (例:`.passthrough()` → 默认 strip、宽读 → 严判)、枚举**重排**——凡是能让一个按上一版契约写的
+  消费方在**运行期**变红、或让同一份配置解析出不同结果的改动;编译期同判,**唯一裁定例外** = 下一条的
+  additive 词表尾插(穷举表消费方的编译红按「提货成本」处理,不构成 major,见下条与其留档异议)。
+  `^1.x` 脱字号**跨 minor**,任何塞进 minor/patch 的破坏都会被未 pin 精确版的下游 `npm install` 静默拿到。
+- **新键 / 新导出 / 词表加词 = minor**(additive):可选键(无默认)、新 subpath、枚举**尾插**新词。
+  ⚠️ 「表不动」≠「消费方零感知」:持 `Record<Word, …>` / 穷举 `switch` 的消费方在提货时会编译红——
+  那是**提货成本**,按能力显式表态制 @点名消费方并附迁移句,不因此升 major(1.2.0 / 1.3.0 口径;
+  codex 复审持「严格 semver 应升 major」异议,原样留档候裁)。
+- **文案 / 注释 / 测试 / bug 修复 = patch**:不改任何 wire 形、类型面、默认值与校验结果。行为面的
+  「修 bug」若改变了合法输入的解析结果,按上两档判,不按 patch。
+- 契约破坏面动之前先盘 center / server / CLI 三方消费点;commit message 的 `feat!`/`BREAKING` 标记照旧,
+  但标记不豁免版号义务。每版 CHANGELOG 一节,git tag `v<version>` 同名。
+- **历史注记(0.x 时代)**:0.x 下 `^0.7.0` 这类 range 只自动收 patch,故当年规矩是「破坏性必 bump
+  minor,patch 只装 additive/修 bug/文档」。0.7.1(2026-07-10)曾携带两件预协调 BREAKING(撤 governance
+  effective 双写镜像、撤 QuotaLease 0.5 `tokens` 别名 shim),名义上违反该条;当时下游(center/service
+  1.150.0)均已显式迁移、实际破坏面为零,PM 拍板不重发 0.8.0(纯扰动)。该例外随 1.x 政策一并归档。
 - 发布(单腿 npmjs,内网腿已废止):`npm run publish:npm`;发后必须 curl 直打 npmjs 复验 shasum。
 
 ## 贡献指引
@@ -145,4 +159,4 @@ defaults. Each `config.d/<domain>.json` is exactly that domain's zod object.
 - 真源 = `sema-agent/sema-settings-schema` org 仓 `main`(2026-08-26 由 sema-registry-core 改名),所有变更直接落 org main(或 PR 进 main);
   不再向任何个人位/镜像位 push。
 - 提交门 = `npm run build` + `npx vitest run`;改域/契约后必跑 `npm run e2e`(examples/toc-e2e.mjs)。
-- 契约破坏面动之前先盘 center / server / CLI 三方消费点;0.x 破坏性变更必 bump minor(见上节)。
+- 契约破坏面动之前先盘 center / server / CLI 三方消费点;破坏性变更必 bump major(见上节)。

package/dist/api/auth-bridge.d.ts

@@ -1,5 +1,5 @@
 /**
- * `api/auth-bridge` — the 鉴权桥 contract: how a WORKER (sema-server / any data-plane service) verifies a
+ * `api/auth-bridge` — the 鉴权桥 contract: how a WORKER (the worker service / any data-plane service) verifies a
  * registry-minted USER access JWT and maps it into its existing `x-agent-principal` identity system.
  * (REGISTRY-REBUILD-DESIGN §5, M3 — registry half = JWKS already shipped; service half = ONE verifier
  * middleware implementing the rules below. This file is the schema + normative spec the service copies.)

package/dist/api/auth-bridge.js

@@ -1,5 +1,5 @@
 /**
- * `api/auth-bridge` — the 鉴权桥 contract: how a WORKER (sema-server / any data-plane service) verifies a
+ * `api/auth-bridge` — the 鉴权桥 contract: how a WORKER (the worker service / any data-plane service) verifies a
  * registry-minted USER access JWT and maps it into its existing `x-agent-principal` identity system.
  * (REGISTRY-REBUILD-DESIGN §5, M3 — registry half = JWKS already shipped; service half = ONE verifier
  * middleware implementing the rules below. This file is the schema + normative spec the service copies.)

package/dist/config-fns.d.ts

@@ -161,7 +161,7 @@ export declare function legacyGovernanceFromRuntime(rawRuntime: unknown): unknow
  *  their audit stream; omitting the callback keeps the resilience but drops the telemetry.
  *
  *  0.19.0 加了两个 kind(additive union member —— 用 `switch` 穷举本类型的消费方需补臂):
- *  `"unknown-keys-dropped"` / `"unread-config-file"`,成案见 {@link droppedKeys}(sema-server
+ *  `"unknown-keys-dropped"` / `"unread-config-file"`,成案见 {@link droppedKeys}(消费方
  *  #322:配置写了、进程跑着、值没到,而没有任何一个字说出来)。 */
 export type EffectiveReadWarning = {
     domain: "hosts";
@@ -198,7 +198,7 @@ export type EffectiveReadWarning = {
 /**
  * 一份域文档里被域 schema **丢掉的键**(zod 对象默认 `"strip"`),点号路径形。
  *
- * 成案(sema-server #322 真事故):往 `runtime` 文档里加一个不属于该域的键,两条腿都会把它剥掉,
+ * 成案(消费方 #322 真事故):往 `runtime` 文档里加一个不属于该域的键,两条腿都会把它剥掉,
  * `domainErrors` 空、解析"成功"——配置写了、值没到、零告警。剥除行为本身是**刻意的前向兼容**
  * (新 center 的新键不该炸老消费方),所以修法不是收紧成 `.strict()`,而是让它**响亮**:
  * {@link buildEffective} 每域解析成功后调用本函数,非空即发 `"unknown-keys-dropped"` 警告。

package/dist/config-fns.js

@@ -66,7 +66,7 @@ export const DOMAIN_WRITE_ROLE = {
     // entitlement governs who-can-USE-what (models/skills/mcp/budget/runtime caps) per principal — a governance +
     // security surface (budget ceilings, bypass kill-switch) on par with systems. Same raised gate.
     entitlement: "publisher",
-    // prompts (0.10.19, board [1069]③/[1050]②d): declaration text goes STRAIGHT into the system prompt of
+    // prompts (0.10.19, [ref]③/②d): declaration text goes STRAIGHT into the system prompt of
     // every worker×scenario the binding covers — the same injection surface (and rationale) as skills/mcp,
     // so the same raised gate. Center had pre-raised this locally per governance precedent; this row is the
     // contract-side source of truth so every consumer of the shared write gate gets publisher, not editor.
@@ -177,7 +177,7 @@ function collectDropped(raw, parsed, prefix, depth, spared, out) {
 /**
  * 一份域文档里被域 schema **丢掉的键**(zod 对象默认 `"strip"`),点号路径形。
  *
- * 成案(sema-server #322 真事故):往 `runtime` 文档里加一个不属于该域的键,两条腿都会把它剥掉,
+ * 成案(消费方 #322 真事故):往 `runtime` 文档里加一个不属于该域的键,两条腿都会把它剥掉,
  * `domainErrors` 空、解析"成功"——配置写了、值没到、零告警。剥除行为本身是**刻意的前向兼容**
  * (新 center 的新键不该炸老消费方),所以修法不是收紧成 `.strict()`,而是让它**响亮**:
  * {@link buildEffective} 每域解析成功后调用本函数,非空即发 `"unknown-keys-dropped"` 警告。
@@ -399,7 +399,7 @@ export function buildEffective(version, getRaw, updatedAt, onWarning) {
         // prompts (0.10.18, [1064]②): content domain → parseOr(坏形回空默认=「无 prompts 管理」语义;
         // fail-closed 由 PUBLISH_MODE 发布闸承担,空 bindings 不下发内容,default 不扩权)。
         prompts: parseOr("prompts", getRaw("prompts")),
-        // limits (0.19.0, sema-server #322 批1): THROW 档 → parseLoud(坏形绝不静默降级成「没有天花板」)。
+        // limits (0.19.0, 消费方 #322 批1): THROW 档 → parseLoud(坏形绝不静默降级成「没有天花板」)。
         limits: parseLoud("limits", getRaw("limits")),
     };
 }

package/dist/file-edit.js

@@ -1,6 +1,6 @@
 /**
  * TOC editor helpers — the read/write/VALIDATE surface the desktop/CLI builds its OWN config UX on top of
- * (Clay's decision: only the LIB is shared, the TOC builds its own UI). These expose write/validate, not just
+ * (product decision: only the LIB is shared, the TOC builds its own UI). These expose write/validate, not just
  * read, so a single-machine consumer never needs the server's routes.
  *
  * Validation uses the SAME zod schemas as the server's parseDomain → identical rules on both sides.

package/dist/file-store.d.ts

@@ -10,7 +10,7 @@ import { type DomainConfig, type DomainName, type EffectiveConfig } from "./type
  *  bundle 的那条口子归调用方纪律(以及各自域的导出面),不是本常量能挡住的;要不要把 bundle API 收窄到
  *  `PortableDomain` 是一个独立的行为面裁定(#282 未决项,需三问),本批不擅自改。
  *
- *  🔴 **开新顶层域时必须同步登记本表**(成案 = sema-server #322 真事故):域表是**闭集**,不在这里的
+ *  🔴 **开新顶层域时必须同步登记本表**(成案 = 消费方 #322 真事故):域表是**闭集**,不在这里的
  *  域名,`config.d/<域>.json` 不会被读进 effective —— 消费方拿到的是「该域缺席」,和文件不存在**逐字
  *  同形**。当年 `limits` 域就是这样在单机腿静默丢了一整片限额发布(远端腿同批可用,所以更难看出来)。
  *  今日的兜底:漏登记的文件会被 {@link FileConfigStore} 的 `"unread-config-file"` 警告点名(fail-loud,

package/dist/file-store.js

@@ -35,7 +35,7 @@ import { isDomainName } from "./types.js";
  *  bundle 的那条口子归调用方纪律(以及各自域的导出面),不是本常量能挡住的;要不要把 bundle API 收窄到
  *  `PortableDomain` 是一个独立的行为面裁定(#282 未决项,需三问),本批不擅自改。
  *
- *  🔴 **开新顶层域时必须同步登记本表**(成案 = sema-server #322 真事故):域表是**闭集**,不在这里的
+ *  🔴 **开新顶层域时必须同步登记本表**(成案 = 消费方 #322 真事故):域表是**闭集**,不在这里的
  *  域名,`config.d/<域>.json` 不会被读进 effective —— 消费方拿到的是「该域缺席」,和文件不存在**逐字
  *  同形**。当年 `limits` 域就是这样在单机腿静默丢了一整片限额发布(远端腿同批可用,所以更难看出来)。
  *  今日的兜底:漏登记的文件会被 {@link FileConfigStore} 的 `"unread-config-file"` 警告点名(fail-loud,
@@ -119,7 +119,7 @@ export class FileConfigStore {
      * FAIL-LOUD 扫描(0.19.0):`config.d/` 里存在、但本地读取集**永远不会读**的 `*.json` 文件,逐个经
      * `onWarning` 点名(`"unread-config-file"`)。
      *
-     * 成案 = sema-server #322:消费方开了新顶层域 `limits` 并发布 `config.d/limits.json`,而本包的域表是
+     * 成案 = 消费方 #322:消费方开了新顶层域 `limits` 并发布 `config.d/limits.json`,而本包的域表是
      * 闭集 —— 文件在、进程跑、限额还是 env 老值,**零告警**(「域缺席」与「文件不存在」在下游逐字同形)。
      * 修法方向是**响亮,不是收紧**:未登记文件照旧不读(拒收会让一个无害的散落文件打死整个部署),但必须
      * 说出来。两类分开报,因为处置不同:`not-a-domain` = 名字打错 / 消费方开了本包还不认识的域(要来本包

package/dist/fleet.d.ts

@@ -324,7 +324,7 @@ export declare function reconcileLease(l: QuotaLease, reported: {
 /** One principal×model line in a report window(worker 的 fleet 批报腿累计)。0.12.1 语义澄清:早年注写
  *  「mirrors the worker's modelUsageTracker accumulation」——engine 3.0 计量语义统一后该说法失真:worker 的
  *  per-task modelUsage 面存**未命中输入分量**(与 cacheRead/Write 分列),而**本面 `inputTokens` 是归一化
- *  总输入(含 cache)**,两面同名不同义,以本注为准(producer 见 sema-server budget.ts fleet 批报腿)。 */
+ *  总输入(含 cache)**,两面同名不同义,以本注为准(producer 见 worker 服务 budget 模块的 fleet 批报腿)。 */
 export declare const UsageEntry: z.ZodObject<{
     principal: z.ZodString;
     model: z.ZodString;

package/dist/fleet.js

@@ -236,7 +236,7 @@ export function reconcileLease(l, reported) {
 /** One principal×model line in a report window(worker 的 fleet 批报腿累计)。0.12.1 语义澄清:早年注写
  *  「mirrors the worker's modelUsageTracker accumulation」——engine 3.0 计量语义统一后该说法失真:worker 的
  *  per-task modelUsage 面存**未命中输入分量**(与 cacheRead/Write 分列),而**本面 `inputTokens` 是归一化
- *  总输入(含 cache)**,两面同名不同义,以本注为准(producer 见 sema-server budget.ts fleet 批报腿)。 */
+ *  总输入(含 cache)**,两面同名不同义,以本注为准(producer 见 worker 服务 budget 模块的 fleet 批报腿)。 */
 export const UsageEntry = z.object({
     principal: z.string().min(1),
     model: z.string().min(1),

package/dist/hooks.d.ts

@@ -2,13 +2,13 @@
  * `hooks` — the CC-parity hooks contract (incl. stop attribution).
  *
  * ONE definition of the FULL hook-event set — 27 CC 2.1.198 events (REF: the `jP` array in
- * claude-cli-2.1.198.pretty.js) + 3 post-198 events the shell already ships (CwdChanged / FileChanged /
- * MessageDisplay). Per the product ruling: the CONTRACT is the full set from day one; the engine
- * hook-runner (service) and the shell light events up in PHASES — adding an event later is pure
- * implementation, never a schema change.
+ * claude-cli-2.1.198.pretty.js) + 4 post-198 events the shell already ships (CwdChanged / FileChanged /
+ * MessageDisplay, and DirectoryAdded from CC 2.1.219). Per the product ruling: the CONTRACT is the full set
+ * from day one; the engine hook-runner (service) and the shell light events up in PHASES — adding an event
+ * later is pure implementation, never a schema change.
  *
  * CONSUMERS
- * - service (sema-server): `TaskRequest.settings.hooks` wire face = `HooksConfig` below; the worker-side
+ * - service (the worker server): `TaskRequest.settings.hooks` wire face = `HooksConfig` below; the worker-side
  *   hook-runner translates matching entries into core `TaskSpec.hooks` in-process callbacks. Single-user
  *   gate first (requirePrincipal semantics, same as MCP injection ).
  * - core (engine): per-event input/output shapes for the engine-owned events; `stoppedBy` on settle.
@@ -26,11 +26,15 @@
 import { z } from "zod";
 /** CC 2.1.198 full hook-event set (jP array) — 27 events. Order matches the shell's HOOK_EVENTS. */
 export declare const CC_198_HOOK_EVENTS: readonly ["PreToolUse", "PostToolUse", "PostToolUseFailure", "PostToolBatch", "Notification", "UserPromptSubmit", "UserPromptExpansion", "SessionStart", "SessionEnd", "Stop", "StopFailure", "SubagentStart", "SubagentStop", "PreCompact", "PostCompact", "PermissionRequest", "PermissionDenied", "Setup", "TeammateIdle", "TaskCreated", "TaskCompleted", "Elicitation", "ElicitationResult", "ConfigChange", "WorktreeCreate", "WorktreeRemove", "InstructionsLoaded"];
-/** Post-CC-2.1.198 additions the shell already ships (sema superset; CC added them after 198). */
-export declare const POST_198_HOOK_EVENTS: readonly ["CwdChanged", "FileChanged", "MessageDisplay"];
-/** The full 30-event contract set = CC 198's 27 + the 3 post-198 shell events. */
-export declare const HOOK_EVENTS: readonly ["PreToolUse", "PostToolUse", "PostToolUseFailure", "PostToolBatch", "Notification", "UserPromptSubmit", "UserPromptExpansion", "SessionStart", "SessionEnd", "Stop", "StopFailure", "SubagentStart", "SubagentStop", "PreCompact", "PostCompact", "PermissionRequest", "PermissionDenied", "Setup", "TeammateIdle", "TaskCreated", "TaskCompleted", "Elicitation", "ElicitationResult", "ConfigChange", "WorktreeCreate", "WorktreeRemove", "InstructionsLoaded", "CwdChanged", "FileChanged", "MessageDisplay"];
-export declare const HookEventName: z.ZodEnum<["PreToolUse", "PostToolUse", "PostToolUseFailure", "PostToolBatch", "Notification", "UserPromptSubmit", "UserPromptExpansion", "SessionStart", "SessionEnd", "Stop", "StopFailure", "SubagentStart", "SubagentStop", "PreCompact", "PostCompact", "PermissionRequest", "PermissionDenied", "Setup", "TeammateIdle", "TaskCreated", "TaskCompleted", "Elicitation", "ElicitationResult", "ConfigChange", "WorktreeCreate", "WorktreeRemove", "InstructionsLoaded", "CwdChanged", "FileChanged", "MessageDisplay"]>;
+/**
+ * Post-CC-2.1.198 additions the shell already ships (sema superset; CC added them after 198).
+ * APPEND-ONLY: new members go at the tail (1.3.0 `DirectoryAdded`, CC 2.1.219 — CC's own tuple places it
+ * between FileChanged and MessageDisplay; the declaration order here is not normative, the enum is a set).
+ */
+export declare const POST_198_HOOK_EVENTS: readonly ["CwdChanged", "FileChanged", "MessageDisplay", "DirectoryAdded"];
+/** The full 31-event contract set = CC 198's 27 + the 4 post-198 shell events. */
+export declare const HOOK_EVENTS: readonly ["PreToolUse", "PostToolUse", "PostToolUseFailure", "PostToolBatch", "Notification", "UserPromptSubmit", "UserPromptExpansion", "SessionStart", "SessionEnd", "Stop", "StopFailure", "SubagentStart", "SubagentStop", "PreCompact", "PostCompact", "PermissionRequest", "PermissionDenied", "Setup", "TeammateIdle", "TaskCreated", "TaskCompleted", "Elicitation", "ElicitationResult", "ConfigChange", "WorktreeCreate", "WorktreeRemove", "InstructionsLoaded", "CwdChanged", "FileChanged", "MessageDisplay", "DirectoryAdded"];
+export declare const HookEventName: z.ZodEnum<["PreToolUse", "PostToolUse", "PostToolUseFailure", "PostToolBatch", "Notification", "UserPromptSubmit", "UserPromptExpansion", "SessionStart", "SessionEnd", "Stop", "StopFailure", "SubagentStart", "SubagentStop", "PreCompact", "PostCompact", "PermissionRequest", "PermissionDenied", "Setup", "TeammateIdle", "TaskCreated", "TaskCompleted", "Elicitation", "ElicitationResult", "ConfigChange", "WorktreeCreate", "WorktreeRemove", "InstructionsLoaded", "CwdChanged", "FileChanged", "MessageDisplay", "DirectoryAdded"]>;
 export type HookEventName = z.infer<typeof HookEventName>;
 export declare const HookOwner: z.ZodEnum<["engine", "shell"]>;
 export type HookOwner = z.infer<typeof HookOwner>;
@@ -1586,7 +1590,48 @@ export declare const MessageDisplayHookInput: z.ZodObject<{
     permission_mode?: string | undefined;
     agent_id?: string | undefined;
 }>;
-/** Any hook input — discriminated on `hook_event_name` (all 30 events). */
+/** How a directory joined the session working set: the `/add-dir` slash command or repo-root registration. */
+export declare const DIRECTORY_ADDED_SOURCES: readonly ["slash_command", "register_repo_root"];
+/**
+ * Fired after a directory joins the session's working set (CC 2.1.219; agent-types hooks.d.ts:582-586 —
+ * `directory` is the absolute path). Shell-owned; matcher ignored; no hookSpecificOutput arm upstream.
+ */
+export declare const DirectoryAddedHookInput: z.ZodObject<{
+    session_id: z.ZodString;
+    transcript_path: z.ZodString;
+    cwd: z.ZodString;
+    permission_mode: z.ZodOptional<z.ZodString>;
+    /** Subagent id — present only when the hook fires from within a subagent. */
+    agent_id: z.ZodOptional<z.ZodString>;
+    /** Agent type name (e.g. "general-purpose") — present alongside agent_id, or on --agent main threads. */
+    agent_type: z.ZodOptional<z.ZodString>;
+} & {
+    hook_event_name: z.ZodLiteral<"DirectoryAdded">;
+    directory: z.ZodString;
+    source: z.ZodEnum<["slash_command", "register_repo_root"]>;
+}, "strip", z.ZodTypeAny, {
+    source: "slash_command" | "register_repo_root";
+    session_id: string;
+    transcript_path: string;
+    cwd: string;
+    hook_event_name: "DirectoryAdded";
+    directory: string;
+    agent_type?: string | undefined;
+    permission_mode?: string | undefined;
+    agent_id?: string | undefined;
+}, {
+    source: "slash_command" | "register_repo_root";
+    session_id: string;
+    transcript_path: string;
+    cwd: string;
+    hook_event_name: "DirectoryAdded";
+    directory: string;
+    agent_type?: string | undefined;
+    permission_mode?: string | undefined;
+    agent_id?: string | undefined;
+}>;
+export type DirectoryAddedHookInput = z.infer<typeof DirectoryAddedHookInput>;
+/** Any hook input — discriminated on `hook_event_name` (all 31 events). */
 export declare const HookInput: z.ZodDiscriminatedUnion<"hook_event_name", [z.ZodObject<{
     session_id: z.ZodString;
     transcript_path: z.ZodString;
@@ -2884,6 +2929,39 @@ export declare const HookInput: z.ZodDiscriminatedUnion<"hook_event_name", [z.Zo
     agent_type?: string | undefined;
     permission_mode?: string | undefined;
     agent_id?: string | undefined;
+}>, z.ZodObject<{
+    session_id: z.ZodString;
+    transcript_path: z.ZodString;
+    cwd: z.ZodString;
+    permission_mode: z.ZodOptional<z.ZodString>;
+    /** Subagent id — present only when the hook fires from within a subagent. */
+    agent_id: z.ZodOptional<z.ZodString>;
+    /** Agent type name (e.g. "general-purpose") — present alongside agent_id, or on --agent main threads. */
+    agent_type: z.ZodOptional<z.ZodString>;
+} & {
+    hook_event_name: z.ZodLiteral<"DirectoryAdded">;
+    directory: z.ZodString;
+    source: z.ZodEnum<["slash_command", "register_repo_root"]>;
+}, "strip", z.ZodTypeAny, {
+    source: "slash_command" | "register_repo_root";
+    session_id: string;
+    transcript_path: string;
+    cwd: string;
+    hook_event_name: "DirectoryAdded";
+    directory: string;
+    agent_type?: string | undefined;
+    permission_mode?: string | undefined;
+    agent_id?: string | undefined;
+}, {
+    source: "slash_command" | "register_repo_root";
+    session_id: string;
+    transcript_path: string;
+    cwd: string;
+    hook_event_name: "DirectoryAdded";
+    directory: string;
+    agent_type?: string | undefined;
+    permission_mode?: string | undefined;
+    agent_id?: string | undefined;
 }>]>;
 export type HookInput = z.infer<typeof HookInput>;
 /** Legacy top-level decision (CC): "approve" ≈ allow, "block" feeds `reason` back to the model. */
@@ -3592,8 +3670,13 @@ export declare const HookSpecificOutput: z.ZodUnion<[z.ZodObject<{
 export type HookSpecificOutput = z.infer<typeof HookSpecificOutput>;
 /**
  * Synchronous hook JSON output (stdout of a command hook, CC-verbatim). Exit-code semantics ride
- * alongside: exit 0 = success (stdout parsed as this shape when JSON), exit 2 = BLOCKING error (stderr
- * fed back to the model), any other exit = non-blocking error (stderr shown to the user).
+ * alongside: exit 0 = success (stdout parsed as this shape when JSON); exit 2 = BLOCKING error (stderr is fed
+ * back to the model as the block reason / additionalContext, per event); any other exit, a timeout, a spawn
+ * failure or malformed JSON = NON-BLOCKING failure: the run continues, and the consumer's hook-runner forwards
+ * it as a `hook_non_blocking_failure` notice (a `hook_notice` frame on the task/fleet stream carrying hook name,
+ * event, reason, exit code and the stderr text redacted-then-bounded to 512 chars), so the failure is visible
+ * from the task's point of view instead of only in server logs. There is no separate "shown to the user"
+ * surface: what a user sees is whatever their client renders from that notice frame.
  */
 export declare const SyncHookOutput: z.ZodObject<{
     /** Whether the run should continue after the hook (default true). */
@@ -5442,7 +5525,7 @@ export declare const HookMatcherEntry: z.ZodObject<{
 export type HookMatcherEntry = z.infer<typeof HookMatcherEntry>;
 /**
  * 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 30
+ * reads from settings JSON: `{ [eventName]: [{ matcher?, hooks: [...] }] }`. Keys limited to the 31
  * contract events (an unknown event name fails parse — catch typos at the wire); all keys optional.
  */
 export type HooksConfig = Partial<Record<HookEventName, HookMatcherEntry[]>>;