@sema-agent/settings-schema 11.0.0 → 11.1.0

package/CHANGELOG.md

@@ -6,6 +6,60 @@
 > `@sema-agent/registry-core`(更早还曾是 `@sema-ai/registry-core`)。本档 `0.19.0` 以下各节里的
 > 包名是**历史记录**,如实保留不追改。
 
+## 11.1.0 — 2026-10-10 — 11.0.0 持久面三件收口:URL fragment 拒句补迁移指路 + 全称律源码钉 · 迁移命令对零域文档目录响亮拒 · 写盘处收成一只原子写器与模式表(minor:一个新导出,零删零改名)
+
+> 本节三件,都是对 11.0.0 持久面的收口:拒句补指路、迁移命令填错目录响亮拒、写盘处收成一只。一个新导出(`NON_SECRET_URL_NO_MIGRATION`,additive),零删零改名。
+
+### URL 带 `#` 的拒句点名迁移 SS-M7;全称律进源码钉;登记表加 `oldForm` 格
+
+11.0.0 的律是「读写两面遇旧形一律响亮拒,拒句点名迁移 id」,但 `NON_SECRET_URL` 座位上的 fragment 拒句(`must not carry a fragment (…)`)没带指路 ——
+存量带 `#` 的 URL 被拒时,读到的句子不说有一条迁移能改写它。现在 fragment 拒句尾接迁移指路(`<规则句>; data stored before 11.0.0: run the one-time migration SS-M7 (…)`),
+与钥匙双设的 SS-M5 拒句同形,对新写入同样生效;userinfo / 非 http(s) 的拒句没有迁移可指,保持判官的规则句原样。
+
+- **谁需要**:持有带 `#` 的 `baseUrl` / MCP `url` / `engineUrl` / `gitApiBaseUrl` 存量的运维 —— 拒句直接告诉他跑哪一条迁移。
+- **谁受伤**:按整句字面匹配 fragment 拒句的消费方(句子变长了:尾部多了 `; <指路>`);`issue.params.flaw`(`"fragment"`)不变,按它分流的不受影响。
+- **补偿**:按 `params.flaw` 取规则词,别拿整句比对;要规则句本身用 `httpUrlRule("fragment")`。
+- **指路只挂在 SS-M7 够得着的座位上**:`NON_SECRET_URL` 是域文档里 URL 座位的判官(SS-M7 按这只 schema 的身份找座位,所以「带指路」与「被 SS-M7 改写」是同一件事);不在域文档里的座位 ——
+  `remoteExec` 的端点(`apiUrl` / `s3Snapshot.endpoint`)、web-admin 凭据信封的 `issuer` —— 改用新导出 `NON_SECRET_URL_NO_MIGRATION`:同一判官、同样的规则句,只是 fragment 拒句不带迁移指路
+  (迁移命令改不到那些值,指过去只会让运维白跑一趟)。自己在宿主里拿 `NON_SECRET_URL` 校验非域文档 URL 的代码,按这个口径选一只。
+- **全称律进源码钉**:登记表每行新增 `oldForm`(`"refused"` 旧形被拒、拒句点名本行 id / `"rewritten-on-read"` 读时改写不拒 / `"not-stored"` 没有存储形),
+  律的两个例外(调度店 SS-M3、wire 删码位 SS-W1)从散文变成表里的字段;一道源码钉(读 AST)要求每个 `refused` 行的 id 在 `src/` 至少有一处铸点
+  (`migrationSignpost("<id>"` 调用或 retired 形字面),非 `refused` 行零铸点 —— 加一行迁移而不加指路 ⇒ 门红。`OneTimeMigrationWindow` 因此多一个必填只读字段
+  (读登记表的代码不受影响;自己手造该型字面的代码要补这一格)。SS-M7 行的 `removal` 补「the fragment rule loses its SS-M7 clause」。
+- **迁移指路句的目录占位统一为 `<config.d directory>`**(此前拒句里是 `<dir>`,命令行 USAGE 与文档是 `<config.d>` / `<config.d directory>` 三种拼法)。
+
+### `migrate <目录>` 填错目录不再静默 noop
+
+命令行扫完目录没找到任何域文档(`<域>.json`)时,此前对零个域文档照常跑迁移:零收据 ⇒ `outcome=noop` 退出 0,stdout 两行、stderr 空 —— 填成 `config.d` 的上一层、
+只有 `remote-exec.json` 之类非域文件的目录,都报「无事可做」,运维读成「这个 scope 已迁完」。现在零域文档分两形:
+
+- **目录里有条目却没有一个是域文档**(任何不以 `.` 开头的条目:子目录、说明文件、`remote-exec.json`、不认识的名;填成 `config.d` 的上一层是最常见的)⇒ **退出 2、stdout 空**、
+  stderr 一句点名这个目录(要的是 `config.d` 目录本身;`<目录>/config.d` 在场就直接点它,给出该跑的命令)。`--check` 同判。
+- **目录真空**(零条目,或只有以 `.` 开头的条目)⇒ **noop 退出 0**,stdout 两行(`outcome=noop written=false` + JSON 报告)、stderr 零字节:新部署的空 `config.d` 是合法态,
+  「没有东西可迁」不是「指错了目录」。迁移把目录搬空(例如目录里只有一份空的或只剩被丢弃键的 `runtime.json`)之后再跑同一目录,也因此是 noop(幂等)。
+
+有域文档、只是没有要改的,仍是 noop 退出 0;只有退役域(`runtime.json`)文件仍照旧迁。
+
+- **谁需要**:本地 `config.d` 的运维、对一批 scope 目录循环跑迁移的脚本。
+- **谁受伤**:循环里夹着「里面有东西却没有域文档」的目录的脚本,此前这些目录静默过关,现在退出 2(真空目录照旧过关)。
+- **补偿**:脚本先判目录里有 `<域>.json` 再调;或接住退出 2 当「这个目录不是 config.d」。
+
+### 写盘处收成一只原子写器,文件模式由一张按文档类的表定
+
+此前包里三处各写各的:`writeDomainFile` 不带模式(umask 缺省,通常 0o644)、迁移命令的写器新建一律 0o600 且已有沿用、调度店 0o600 —— 同一个目录里「写出的域文档」是 644 还是 600
+取决于哪条路写的;`writeRemoteExec` 又是第四份同样的写法;命令行入口的头注还说自己是包里唯一写文件的地方。现在 `writeDomainFile` / `writeRemoteExec` / 迁移命令的写器 /
+`saveSchedulerStore` 全部调同一只(同目录隐藏临时文件 → rename;失败清残片),模式只在那一张表里:`config.d` 契约文档(域文档、`remote-exec.json`)新建 = 0o644(契约文件只带 env-NAME、
+不带秘密),**已有的文件沿用它原来的模式**;调度店耐久记录 = 0o600,每次保存都回到 0o600。入口脚本只注入真 I/O,不再自己写盘、不再自己判模式。
+
+- **谁需要**:想让同一目录里的契约文件模式一致的运维;读 `scheduled_tasks.json` 权限的审计。
+- **谁受伤**:(1) 迁移命令**新建**的域文档(例如从 `runtime.json` 搬出来的 `governance.json` / `limits.json`)此前是 0o600,现在是 0o644(经 umask),与 `writeDomainFile` 一致;
+  (2) `writeDomainFile` / `writeRemoteExec` 改写**已有**文件时此前按 umask 缺省重置模式,现在沿用原模式(运维 chmod 过的文件保留)。调度店的行为不变(新建 0o600、每次保存收回 0o600)。
+- **补偿**:要更严的权限,对 `config.d` 里的文件 `chmod`(现在写回不再冲掉它),或收紧进程 umask(新建文件仍经 umask)。
+
+#### 未闭环
+
+- `remote-exec.json` 里存量带 `#` 的端点:一次性迁移 SS-M7 只走**域文档**里的座位,迁移命令也只读 `<域>.json`,所以这类存量没有迁移可跑,只能手改(拒句是规则句,不指迁移)。
+
 ## 11.0.0 — 2026-10-10 — 依赖换 zod 4、三处死出口收回、持久面一次性迁移族、同一个问题一只判官、名与契约(major)
 
 > 本节四件:以下先是平台一件(zod 4 + 三处出口收窄 + 上游锚抬钉),再是持久面一件(「持久面」一节起),再是判官一件(「判官」一节起),再是名与契约一件(「名与契约」一节起)。每条硬破坏写三句:谁受影响 / 怎么改 / 不改会怎样。
@@ -1525,7 +1579,7 @@ sema-server 7.108.0(S-931)给模型目录条目加了 `headers`(部署 ↔ 供
 
 ## 6.1.0 — 2026-09-25 — 四件 additive:`entry-dropped` 身份(S-712)· 中心凭证信封 + 三态判别器(S-698)· `RestartSignal` 一处定义(S-741)· 中心凭证两键名 + 二选一判官(S-742);`redactSecrets` 私钥 PEM 串内任意位置且判在替换前(6.0.0 起三面既有盲点顺带关)
 
-> 本节四件全 additive(新可选键 / 新导出 / 新文件),零删零改名;版号与节标题由发版方写。判档口径见下方「发版纪律」:
+> 本节四件全 additive(新可选键 / 新导出 / 新文件),零删零改名;判档口径见下方「发版纪律」:
 > 新键 / 新导出 = minor。
 
 ### S-712 · `entry-dropped` 告警带被丢条目的身份(`identity?`,additive)

package/README.md

@@ -70,8 +70,10 @@ therefore shows only `zod`. Node built-ins only (`node:crypto`, `node:fs`).
   `docs` 里没改的文档是**同一引用**、被移除的(退役的 `runtime` 域)不在、迁出的新文档(`governance` / `limits`)在 —— 据此写回 / 删除。
   `receipts` 逐条说「对哪个坐标做了什么」(`moved` / `rewritten` / `dropped-shadowed` / `dropped-inert` / `refused`;不带值)。
   `refused` 的坐标原样留着,读侧照旧拒:要人改。再跑一次 = 零改动。
-- **目录形**:`npx @sema-agent/settings-schema migrate <config.d> [--check]`(同一只函数;目录当一个 scope;有 refused 一字不写、退出 1;
-  `--check` 有改动退出 3)。
+- **目录形**:`npx @sema-agent/settings-schema migrate <config.d directory> [--check]`(同一只函数;目录当一个 scope;有 refused 一字不写、退出 1;
+  `--check` 有改动退出 3)。参数是 `config.d` 目录**本身**(里面直接放 `<域>.json`):目录里有条目却没有一份域文档 —— 填成了它的上一层、只有
+  `remote-exec.json` 之类非域文件 —— 退出 2、stdout 空,stderr 点名这个目录(`<目录>/config.d` 在场就直接点它);目录真空(零条目,或只有以 `.` 开头的条目)是合法态
+  (新部署的空 `config.d`),和「有域文档、只是没有要改的」一样是 noop、退出 0。
 - **迁什么**(七条,`ONE_TIME_MIGRATIONS` 每行写着改写规则、删法、删后由谁接住):退役 `runtime` 域(治理三闸 → `governance`、五个限额键 → `limits`)·
   hosts 超界 · 调度店 durable 键(读时改写,下一个写者落盘)· workers 6.x 行 · 模型钥匙双设 · `atModelAllowlist` → `atMention` · URL fragment。
 - **什么时候删**:每条的窗 = 11.0.0 发布日 + 30 天,窗关之后的那个 major 整族删(删法与删后的响亮臂见登记表那一行);本包的到期门到点即红。
@@ -293,7 +295,7 @@ therefore shows only `zod`. Node built-ins only (`node:crypto`, `node:fs`).
   `WebAdminCredentialEnvelope` (strict JSON: `kind: "user-session"` = `WEB_ADMIN_CREDENTIAL_ENVELOPE_KIND`, a JWT
   `accessToken` and a `refreshToken` under the same token law as the bare line, RFC 3339
   `expiresAt` with seconds and a `Z` / `±hh:mm` offset in range, `issuer` = the issuing web-admin's base URL judged
-  by the same `NON_SECRET_URL` the `remoteExec` endpoints use — same-origin is the reader's comparison).
+  by the same judge the `remoteExec` endpoints use (`NON_SECRET_URL_NO_MIGRATION`) — same-origin is the reader's comparison).
   `parseWebAdminCredentialFile(text)` is the ONE discrimination law — trimmed text starting with `{` is read ONLY
   as an envelope (a failure is `unreadable`, never a fallback to a bare line); anything else is a bare line,
   and a first line that is not a token is `unreadable` too (never sent as a bearer); empty is `unreadable`. The `reason` names envelope fields / zod issue codes / an unknown-key COUNT, never file

package/bin/settings-schema.mjs

@@ -1,26 +1,17 @@
 #!/usr/bin/env node
-// `settings-schema` — this package's command line (11.0.0: `migrate <config.d directory> [--check]`, the one-time migrations).
-// The ONLY place the package writes files with node:fs; the logic is `runSettingsSchemaCli` (dist/cli.js), which never
-// touches the filesystem itself — this entry injects real file I/O into it.
-import { readdir, readFile, rename, stat, unlink, writeFile } from "node:fs/promises";
+// `settings-schema` — this package's command line (`migrate <config.d directory> [--check]`, the one-time migrations).
+// The real-I/O injection point: the logic is `runSettingsSchemaCli` (dist/cli.js), which never touches the filesystem itself — this
+// entry hands it directory / file reads and removal, and the one atomic writer (dist/atomic-write.js), which alone decides how a file
+// is written and with what mode.
+import { readdir, readFile, unlink } from "node:fs/promises";
 import { runSettingsSchemaCli } from "../dist/cli.js";
+import { writeFileAtomic } from "../dist/atomic-write.js";
 
 const io = {
   readDir: (path) => readdir(path),
   readFile: (path) => readFile(path, "utf8"),
-  // atomic: write a sibling temp file (same mode as the original when there is one), then rename over it — a half-written
-  // domain document is worse than the old one.
-  writeFileAtomic: async (path, text) => {
-    let mode = 0o600;
-    try {
-      mode = (await stat(path)).mode & 0o777;
-    } catch (e) {
-      if (e?.code !== "ENOENT") throw e;
-    }
-    const tmp = `${path}.migrate-${process.pid}.tmp`;
-    await writeFile(tmp, text, { encoding: "utf8", mode });
-    await rename(tmp, path);
-  },
+  // the files this command writes are config.d domain documents
+  writeFileAtomic: async (path, text) => writeFileAtomic(path, text, "config-document"),
   removeFile: (path) => unlink(path),
   stdout: (text) => process.stdout.write(text),
   stderr: (text) => process.stderr.write(text),

package/conformance/VERSION

@@ -1 +1 @@
-11.0.0
+11.1.0

package/conformance/cases/c06-legacy-governance-lift/expected.json

@@ -16,6 +16,6 @@
   "localRoot": {
     "outcome": "rejected",
     "stage": "parse",
-    "why": "拒:config.d/runtime.json 带事实 ⇒ FileConfigStore 由同一只墓碑拒(本地目录用 `npx @sema-agent/settings-schema migrate <dir>` 迁)。"
+    "why": "拒:config.d/runtime.json 带事实 ⇒ FileConfigStore 由同一只墓碑拒(本地目录用 `npx @sema-agent/settings-schema migrate <config.d directory>` 迁)。"
   }
 }

package/conformance/cases/c20-governance-absent-lifts/expected.json

@@ -16,6 +16,6 @@
   "localRoot": {
     "outcome": "rejected",
     "stage": "parse",
-    "why": "拒:config.d/runtime.json 带事实 ⇒ FileConfigStore 由同一只墓碑拒(本地目录用 `npx @sema-agent/settings-schema migrate <dir>` 迁)。"
+    "why": "拒:config.d/runtime.json 带事实 ⇒ FileConfigStore 由同一只墓碑拒(本地目录用 `npx @sema-agent/settings-schema migrate <config.d directory>` 迁)。"
   }
 }

package/conformance/cases/c67-s784-retired-field-loud/meta.json

@@ -1,5 +1,5 @@
 {
   "contributor": "contract",
-  "claim": "7.0.0 删除项读到即**响亮拒**(runtime.sessionBackend,哪怕是停用的 worker)—— 11.0.0 起由 WorkerSpec 里原位的墓碑字段拒,拒句点名一次性迁移 SS-M4(与 `npx @sema-agent/settings-schema migrate <dir>`);不被 zod 静默剥成「什么都没声明」。",
+  "claim": "7.0.0 删除项读到即**响亮拒**(runtime.sessionBackend,哪怕是停用的 worker)—— 11.0.0 起由 WorkerSpec 里原位的墓碑字段拒,拒句点名一次性迁移 SS-M4(与 `npx @sema-agent/settings-schema migrate <config.d directory>`);不被 zod 静默剥成「什么都没声明」。",
   "firstRedOn": []
 }

package/dist/atomic-write.d.ts

@@ -0,0 +1,14 @@
+/** 按文档类的模式表(闭集)。 */
+export declare const ATOMIC_FILE_CLASSES: {
+    readonly "config-document": {
+        readonly newMode: 420;
+        readonly existing: "keep";
+    };
+    readonly "scheduler-store": {
+        readonly newMode: 384;
+        readonly existing: "reset";
+    };
+};
+export type AtomicFileClass = keyof typeof ATOMIC_FILE_CLASSES;
+/** 原子写 `text`(UTF-8)到 `target`;模式按 `kind` 在 {@link ATOMIC_FILE_CLASSES} 里的行。父目录须已存在。 */
+export declare function writeFileAtomic(target: string, text: string, kind: AtomicFileClass): void;

package/dist/atomic-write.js

@@ -0,0 +1,60 @@
+/**
+ * **本包写盘的唯一一只原子写器**(Node 专用,不进主桶):`writeDomainFile` / `writeRemoteExec`(`config.d` 下的契约文件)、调度店
+ * `saveSchedulerStore`、命令行迁移经 `bin/settings-schema.mjs` 注入的写器 —— 全部调它。写法只有一种:在目标同目录写一个唯一命名的隐藏
+ * 临时文件,再 `rename` 盖过目标(POSIX 上原子,并发读者永远看不到半截文件);失败时临时文件被清掉,不留残片。
+ *
+ * 同步实现(几 KB 的配置文件,一次写不到一毫秒):调度店的写口本来就是同步 API(`saveSchedulerStore(path, records): void`,
+ * `mutateSchedulerStore` 的提交点),异步调用方(`writeDomainFile` 等)直接调它 —— 一只写器,没有第二份同样的写法。
+ *
+ * ## 文件模式:一张按文档类的表({@link ATOMIC_FILE_CLASSES}),不在任何调用点另写
+ *  · `config-document` —— `config.d` 下的契约 JSON(域文档、`remote-exec.json`):只带 env-NAME、不带秘密值(README 契约),新建 = 0o644;
+ *    **已有的文件沿用它原来的模式**(运维 chmod 过的文件不被一次写回覆盖)。
+ *  · `scheduler-store` —— 调度店耐久记录(可能带 principal / session 标识):新建 = 0o600,且**每次写都回到 0o600**(已有的更宽的文件被收回)。
+ * 新建的模式照常经进程 umask 遮一道(`writeFile` 的 `mode` 语义):比表更严的 umask 只会更严,不会被这里放宽;沿用的模式原样恢复(不再过 umask)。
+ */
+import { randomBytes } from "node:crypto";
+import { chmodSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import path from "node:path";
+/** 按文档类的模式表(闭集)。 */
+export const ATOMIC_FILE_CLASSES = {
+    "config-document": { newMode: 0o644, existing: "keep" },
+    "scheduler-store": { newMode: 0o600, existing: "reset" },
+};
+/** 原子写 `text`(UTF-8)到 `target`;模式按 `kind` 在 {@link ATOMIC_FILE_CLASSES} 里的行。父目录须已存在。 */
+export function writeFileAtomic(target, text, kind) {
+    const spec = ATOMIC_FILE_CLASSES[kind];
+    let kept; // the existing file's mode, when this class keeps it
+    switch (spec.existing) {
+        case "keep":
+            try {
+                kept = statSync(target).mode & 0o777;
+            }
+            catch (e) {
+                if (e.code !== "ENOENT")
+                    throw e;
+            }
+            break;
+        case "reset":
+            break;
+        default: {
+            const unhandled = spec.existing;
+            throw new Error(`writeFileAtomic: unhandled existing-file rule ${String(unhandled)}`);
+        }
+    }
+    const tmp = path.join(path.dirname(target), `.${path.basename(target)}.${process.pid}.${randomBytes(6).toString("hex")}.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)
+        renameSync(tmp, target);
+    }
+    catch (e) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch {
+            /* 临时文件没建成:没什么可清 */
+        }
+        throw e;
+    }
+}

package/dist/cli.d.ts

@@ -1,4 +1,4 @@
-/** 入口注入的 I/O(核心不碰 node:fs)。`writeFileAtomic` 必须原子(写临时文件再改名):半写的域文档比旧文档更糟。 */
+/** 入口注入的 I/O(核心不碰 node:fs)。`writeFileAtomic` 必须原子(写临时文件再改名):半写的域文档比旧文档更糟;入口注入的就是 `./atomic-write` 的那一只。 */
 export interface SettingsSchemaCliIo {
     readDir(path: string): Promise<string[]>;
     readFile(path: string): Promise<string>;

package/dist/cli.js

@@ -3,14 +3,18 @@
  * `migrateStoredDocuments`(`./one-time-migrations`)的目录形(本地 config.d / 离线文件用;web-admin 在它起服时直接调同一只函数)。
  * 目录被当作**一个 scope 的全集**(`coverage: "scope"`):目录里没有的域文件就是从未设过。
  *
- * 本模块不碰 `node:fs`:读写文件由入口 `bin/settings-schema.mjs` 注入(那是本包唯一用 fs 写文件的地方),所以测试可以直接驱动它。
+ * 本模块不碰 `node:fs`:读写文件由入口 `bin/settings-schema.mjs` 注入(写盘用的是 `./atomic-write` 那一只原子写器 —— 写法与文件模式在那里一处定),所以测试可以直接驱动它。
  * 不进主桶 —— 它是 bin 的实现,不是契约面。
  *
  * 读哪些文件:目录里 `<名>.json`,名是配置域或retired 域(`runtime`)—— 便携与否不论(离线的 `workers.json` 一样迁);别的文件
  * (`remote-exec.json`、隐藏文件、不认识的名)不读不动。
  *
- * 退出码:0 = 已写回 / 无事可做;1 = 有迁不了的坐标(收据 `refused`)**或**要写回的域文档整域读不进(整域终判,见 {@link verdictOf}),**一字不写**;
- * 2 = 用法 / 读目录 / 读文件错,或某个域文件是坏文件(空 / 纯空白 / 坏 JSON / 不是 JSON 对象 —— 与 `FileConfigStore` 同一只判、同一句)(此时 stdout 为空);3 = `--check` 且会有改动、整域判得过(不写)。`--check` 与真跑过同一只判定,只在
+ * 零域文档分两形:**有条目却没有域文档**(任何非 `.` 开头的条目 —— 子目录、说明文件、不认识的名)⇒ 退出 2;**目录真空**(零条目,或只有以 `.` 开头的条目)⇒ 照常走判定,
+ * 零收据 = noop 退出 0 —— 新部署的空 `config.d` 是合法态,「没有东西可迁」不是「指错目录」(搬空之后再跑同一目录也因此幂等)。
+ *
+ * 退出码:0 = 已写回 / 无事可做(目录里有域文档只是没有要改的,或目录真空);1 = 有迁不了的坐标(收据 `refused`)**或**要写回的域文档整域读不进(整域终判,见 {@link verdictOf}),**一字不写**;
+ * 2 = 用法 / 读目录 / 读文件错,或某个域文件是坏文件(空 / 纯空白 / 坏 JSON / 不是 JSON 对象 —— 与 `FileConfigStore` 同一只判、同一句),**或目录里有条目却没有一个是域文档**
+ * (多半是填错了目录:要的是 `config.d` 目录本身;`<目录>/config.d` 在场时句子直接点它)(此时 stdout 为空);3 = `--check` 且会有改动、整域判得过(不写)。`--check` 与真跑过同一只判定,只在
  * 「有改动、且整域判得过」那一支上分开(pending vs applied)—— 整域会被拒的目录 `--check` 也报 refused / rc 1。
  *
  * ## 报告形(让「没写」在机读上不可能被读成「写了」)
@@ -31,7 +35,8 @@ const USAGE = [
     "  Runs the one-time migrations (@sema-agent/settings-schema/one-time-migrations) over every <domain>.json in the directory, read as one",
     "  scope (a missing domain file = never set): writes the rewritten files in place and removes retired-domain files (runtime.json) only when",
     "  nothing is refused and every document it would write reads as a whole domain; --check runs the same verdict and only reports (exit 3",
-    "  if something would change).",
+    "  if something would change). The argument is the config.d directory itself; a directory that has entries but no <domain>.json among them is",
+    "  refused (exit 2); an empty directory has nothing to migrate (exit 0).",
     "  stdout (exit 0 / 1 / 3): line 1 = outcome=<refused|applied|noop|pending> written=<true|false>, line 2 = the JSON report",
     "  (applied only when written=true; otherwise wouldApply).",
 ].join("\n");
@@ -119,6 +124,13 @@ function reportOf(outcome, dir, applied, refused) {
     return `outcome=${outcome} written=${written}\n${json}\n`;
 }
 const join = (dir, name) => `${dir.replace(/[\\/]+$/, "")}/${name}`;
+/** 「有条目却没有域文档」的拒句:点名这个目录、说要的是 `config.d` 目录本身;`<dir>/config.d` 在场(探一次)就直接点它 —— 最常见的错是填了它的上一层。 */
+async function noDomainDocumentsSentence(dir, io) {
+    const nested = join(dir, "config.d");
+    const nestedExists = await io.readDir(nested).then(() => true, () => false);
+    const base = `settings-schema: no domain documents in ${dir} (a domain document is <domain>.json, e.g. models.json) — the argument is the config.d directory itself`;
+    return nestedExists ? `${base}; ${nested} exists — run: ${MIGRATE_COMMAND} ${nested}` : base;
+}
 export async function runSettingsSchemaCli(argv, io) {
     const [command, ...rest] = argv;
     const check = rest.includes("--check");
@@ -159,6 +171,12 @@ export async function runSettingsSchemaCli(argv, io) {
             return 2;
         }
     }
+    if (Object.keys(docs).length === 0 && names.some((name) => !name.startsWith("."))) {
+        // The directory has entries and none of them is a domain document: a no-op report (rc 0) would read as "this scope is migrated" for a
+        // directory the command never looked into. A directory with nothing visible in it (empty, or only dot entries) is a legitimate scope.
+        io.stderr(`${await noDomainDocumentsSentence(dir, io)}\n`);
+        return 2;
+    }
     const m = migrateStoredDocuments(docs, { coverage: "scope" });
     const applied = m.receipts.filter((r) => r.appliedAs !== "refused");
     const verdict = verdictOf(docs, m.docs, m.receipts);

package/dist/file-edit.d.ts

@@ -17,9 +17,9 @@ export declare function validateRemoteExec(raw: unknown): ValidateResult<RemoteE
 /** Absolute path to a domain's JSON file under a config root (mirrors FileConfigStore.domainPath). Guards the
  *  name (no `../../secret` traversal even if a caller bypasses the DomainName type). */
 export declare function domainFilePath(root: string, domain: DomainName): string;
-/** WRITE a domain file ATOMICALLY (write a tmp in the same dir → rename) so a crash never leaves a half-written
- *  config.d/<domain>.json. VALIDATES first (throws on invalid — never persists garbage); persists the parsed +
- *  defaulted value so the file is canonical. */
+/** WRITE a domain file ATOMICALLY (the package's one atomic writer, `./atomic-write`: tmp in the same dir → rename) so a crash never
+ *  leaves a half-written config.d/<domain>.json; a new file takes the contract-document mode (0o644), an existing one keeps its own.
+ *  VALIDATES first (throws on invalid — never persists garbage); persists the parsed + defaulted value so the file is canonical. */
 export declare function writeDomainFile<K extends DomainName>(root: string, domain: K, value: unknown): Promise<DomainConfig[K]>;
 export interface RequiredEnvName {
     envName: string;

package/dist/file-edit.js

@@ -5,8 +5,9 @@
  *
  * Validation uses the SAME zod schemas as the server's parseDomain → identical rules on both sides.
  */
-import { mkdir, rename, unlink, writeFile } from "node:fs/promises";
+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 { RetiredDomainError, parseDomain, sanitizeZodError } from "./config-fns.js";
@@ -25,8 +26,6 @@ function assertDomainName(domain) {
     }
 }
 const DOMAINS_LIST = Object.keys(DOMAIN_SCHEMAS).join(", ");
-// Monotonic suffix so concurrent same-domain atomic writes in one process+ms can't collide on the tmp name.
-let tmpSeq = 0;
 /** VALIDATE a domain payload against its zod schema WITHOUT writing — the editor's "is this form valid?" check.
  *  Returns the parsed+defaulted value or the zod issues. Identical rules to the server's parseDomain. Throws
  *  (clear message) if `domain` is not a real domain name (a misuse, not invalid user data). */
@@ -61,24 +60,15 @@ export function domainFilePath(root, domain) {
     assertDomainName(domain);
     return path.join(root, "config.d", `${domain}.json`);
 }
-/** WRITE a domain file ATOMICALLY (write a tmp in the same dir → rename) so a crash never leaves a half-written
- *  config.d/<domain>.json. VALIDATES first (throws on invalid — never persists garbage); persists the parsed +
- *  defaulted value so the file is canonical. */
+/** WRITE a domain file ATOMICALLY (the package's one atomic writer, `./atomic-write`: tmp in the same dir → rename) so a crash never
+ *  leaves a half-written config.d/<domain>.json; a new file takes the contract-document mode (0o644), an existing one keeps its own.
+ *  VALIDATES first (throws on invalid — never persists garbage); persists the parsed + defaulted value so the file is canonical. */
 export async function writeDomainFile(root, domain, value) {
     assertDomainName(domain); // a stray non-domain key (e.g. "remote-exec" from a config.d scan) fails LOUD + clear
     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 });
-    const dest = path.join(dir, `${domain}.json`);
-    const tmp = path.join(dir, `.${domain}.json.${process.pid}.${Date.now()}.${tmpSeq++}.tmp`);
-    try {
-        await writeFile(tmp, JSON.stringify(parsed, null, 2) + "\n", "utf8");
-        await rename(tmp, dest);
-    }
-    catch (e) {
-        await unlink(tmp).catch(() => { }); // never leave a half-written tmp behind on a write/rename failure
-        throw e;
-    }
+    writeFileAtomic(path.join(dir, `${domain}.json`), JSON.stringify(parsed, null, 2) + "\n", "config-document");
     return parsed;
 }
 /** LIST every env-NAME the current local config requires (across models/workers/mcp + the

package/dist/file-store.js

@@ -18,7 +18,7 @@
  *    etc.) — no stubbing needed. 逐域为什么被排除见 {@link NON_PORTABLE_DOMAIN_REASONS}(禁裸排除)。
  *  - A RETIRED domain's file (`config.d/runtime.json`, see `RETIRED_DOMAINS`) is read only for its tombstone: carrying facts ⇒
  *    every read entry (`getDomain`, `getEffective` — and so `exportBundle`) throws `RetiredDomainError` (`refuseRetiredDomainFiles`, shared with `readBundle`) (the sentence names the one-time migration — `npx @sema-agent/settings-schema migrate
- *    <dir>` rewrites the directory); `{}` carries nothing and is left alone. It is never an "unread file".
+ *    <config.d directory>` rewrites the directory); `{}` carries nothing and is left alone. It is never an "unread file".
  *  - The JSON files only ever carry env-NAMEs (the ENV_NAME boundary holds locally too); `.env` holds values.
  *  - `getVersion()` = a stable content hash of all portable files → a u53 number, so a consumer's
  *    "skip re-apply if version unchanged" works locally. `getEffective().updatedAt` = the max file mtime,

package/dist/local-load.d.ts

@@ -7,7 +7,7 @@ export declare function remoteExecPath(root: string): string;
 /** 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 declare function loadRemoteExec(root: string): Promise<RemoteExecSpec | undefined>;
-/** Validate + ATOMICALLY write `<root>/config.d/remote-exec.json` (tmp → rename; never a half file). The
+/** 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 declare function writeRemoteExec(root: string, spec: unknown): Promise<RemoteExecSpec>;
 /** Parse `<root>/.env` (KEY=VALUE, `#` comments, optional surrounding quotes) MERGED OVER process.env (the

package/dist/local-load.js

@@ -7,9 +7,10 @@
  * `<root>/config.d/remote-exec.json` (service vote), loaded/validated by loadRemoteExec — distinct from
  * the per-domain `config.d/<domain>.json` the resolver reads. getEffective never reads it (not a DomainName).
  */
-import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { mkdir, readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 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";
@@ -28,9 +29,6 @@ function parseRemoteExec(raw) {
         return r.data;
     throw sanitizeZodError(r.error);
 }
-// Monotonic suffix so two atomic writes in the SAME process+millisecond can't collide on the tmp name (which
-// would make one rename hit ENOENT / lose a write). pid+Date.now() alone isn't unique under concurrency.
-let tmpSeq = 0;
 /** 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");
@@ -62,21 +60,13 @@ export async function loadRemoteExec(root) {
     }
     return parseRemoteExec(json);
 }
-/** Validate + ATOMICALLY write `<root>/config.d/remote-exec.json` (tmp → rename; never a half file). The
+/** 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 dir = path.join(root, "config.d");
     await mkdir(dir, { recursive: true });
-    const tmp = path.join(dir, `.remote-exec.json.${process.pid}.${Date.now()}.${tmpSeq++}.tmp`);
-    try {
-        await writeFile(tmp, JSON.stringify(parsed, null, 2) + "\n", "utf8");
-        await rename(tmp, remoteExecPath(root));
-    }
-    catch (e) {
-        await unlink(tmp).catch(() => { }); // never leave a half-written tmp behind
-        throw e;
-    }
+    writeFileAtomic(remoteExecPath(root), JSON.stringify(parsed, null, 2) + "\n", "config-document");
     return parsed;
 }
 /** Resolve a `file:<path>` .env VALUE → the file's trimmed content (the file-NAME secret ref, config-research

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

@@ -9,6 +9,12 @@ export type WireRetirementId = (typeof WIRE_RETIREMENT_IDS)[number];
 export interface OneTimeMigrationWindow {
     /** 数据迁移 id(闭集 `ONE_TIME_MIGRATION_IDS`)或 wire 删码位 id(闭集 {@link WIRE_RETIREMENT_IDS});两集合起来每个 id 恰一行。 */
     readonly id: OneTimeMigrationId | WireRetirementId;
+    /** 旧形在读侧的待遇(闭集,每词一义;「读写两面遇旧形一律响亮拒,拒句点名迁移 id」这条律的例外只在这一格里写):
+     *   · `refused`           — 读写两面拒,拒句点名本行 id(经 `migrationSignpost` 铸;钉:每个 `refused` 行的 id 在 `src/` 至少一处铸点,
+     *                           且非 `refused` 行零铸点);
+     *   · `rewritten-on-read` — 读时改写、不拒(SS-M3:调度店的下一个写者落盘),没有拒句可点名;
+     *   · `not-stored`        — 没有存储形(wire 删码位),谈不上拒。 */
+    readonly oldForm: "refused" | "rewritten-on-read" | "not-stored";
     /** 引入这条迁移的版本。 */
     readonly introducedIn: string;
     /** 该版本在 npm 上的发布日(UTC 日历日 YYYY-MM-DD)。`null` = 未发布形,由抬 `package.json` 到 `introducedIn` 的发布准备提交回填。 */

package/dist/one-time-migrations.js

@@ -45,6 +45,7 @@ export const WIRE_RETIREMENT_IDS = ["SS-W1"];
 export const ONE_TIME_MIGRATIONS = [
     {
         id: "SS-M1",
+        oldForm: "refused",
         introducedIn: "11.0.0",
         releasedOn: "2026-10-10",
         removableAfter: "2026-11-09",
@@ -60,6 +61,7 @@ export const ONE_TIME_MIGRATIONS = [
     },
     {
         id: "SS-M2",
+        oldForm: "refused",
         introducedIn: "11.0.0",
         releasedOn: "2026-10-10",
         removableAfter: "2026-11-09",
@@ -71,6 +73,7 @@ export const ONE_TIME_MIGRATIONS = [
     },
     {
         id: "SS-M3",
+        oldForm: "rewritten-on-read",
         introducedIn: "11.0.0",
         releasedOn: "2026-10-10",
         removableAfter: "2026-11-09",
@@ -83,6 +86,7 @@ export const ONE_TIME_MIGRATIONS = [
     },
     {
         id: "SS-M4",
+        oldForm: "refused",
         introducedIn: "11.0.0",
         releasedOn: "2026-10-10",
         removableAfter: "2026-11-09",
@@ -95,6 +99,7 @@ export const ONE_TIME_MIGRATIONS = [
     },
     {
         id: "SS-M5",
+        oldForm: "refused",
         introducedIn: "11.0.0",
         releasedOn: "2026-10-10",
         removableAfter: "2026-11-09",
@@ -104,6 +109,7 @@ export const ONE_TIME_MIGRATIONS = [
     },
     {
         id: "SS-M6",
+        oldForm: "refused",
         introducedIn: "11.0.0",
         releasedOn: "2026-10-10",
         removableAfter: "2026-11-09",
@@ -115,17 +121,19 @@ export const ONE_TIME_MIGRATIONS = [
     },
     {
         id: "SS-M7",
+        oldForm: "refused",
         introducedIn: "11.0.0",
         releasedOn: "2026-10-10",
         removableAfter: "2026-11-09",
         rewrites: "every NON_SECRET_URL seat in a domain document (derived from the domain schemas, not listed by hand — today models.models[].baseUrl, " +
             "mcp.servers[].transport.url, execution.sessionMirror.engineUrl, workers.workers[].coords.gitApiBaseUrl): `#` and everything after it are removed " +
             "(a fragment never goes on the wire)",
-        removal: "the next major after the window: delete the SS-M7 step and its schema walk",
+        removal: "the next major after the window: delete the SS-M7 step and its schema walk; the NON_SECRET_URL fragment rule loses its SS-M7 clause",
         afterRemoval: "the NON_SECRET_URL shape judge, which refuses a fragment (`#` included) on read and write",
     },
     {
         id: "SS-M9",
+        oldForm: "refused",
         introducedIn: "11.0.0",
         releasedOn: "2026-10-10",
         removableAfter: "2026-11-09",
@@ -139,6 +147,7 @@ export const ONE_TIME_MIGRATIONS = [
     {
         // 一条 wire 位的删码登记,不是数据迁移(id 在 WIRE_RETIREMENT_IDS,不在收据闭集)。
         id: "SS-W1",
+        oldForm: "not-stored",
         introducedIn: "11.0.0",
         releasedOn: "2026-10-10",
         removableAfter: "2026-11-09",

package/dist/remote-exec.js

@@ -28,7 +28,7 @@
  */
 import { z } from "zod";
 import { INTEGER } from "./integer.js";
-import { ENV_NAME, K8S_QUANTITY, NON_SECRET_URL, TCP_PORT, containsSecretToken, hasNul } from "./types.js";
+import { ENV_NAME, K8S_QUANTITY, NON_SECRET_URL_NO_MIGRATION, TCP_PORT, containsSecretToken, hasNul } from "./types.js";
 import { retiredLaneWordRefusal } from "./execution-lanes.js";
 /** A non-empty exec-bound string (an image / path / shell / arg the adapter feeds to spawn()/fs). Rejects a NUL
  *  byte uniformly — a NUL validates here but makes Node throw at spawn/boot (fail-OPEN → runtime crash). R20. */
@@ -84,7 +84,7 @@ export const RemoteExecSpec = z.discriminatedUnion("provider", [
         /** Sandbox container image (service: K8S_SANDBOX_IMAGE). Required so a run is reproducible. */
         image: execStr,
         /** Kube API URL (service: K8S_API_URL); absent → in-cluster service account. NO embedded credentials. */
-        apiUrl: NON_SECRET_URL.optional(),
+        apiUrl: NON_SECRET_URL_NO_MIGRATION.optional(),
         /** env-NAME holding the kube bearer token (service: K8S_TOKEN). NEVER the token. */
         tokenEnv: ENV_NAME.optional(),
         /** env-NAME holding the base64 CA cert (service: K8S_CA_CERT_B64). NEVER the cert bytes. */
@@ -102,7 +102,7 @@ export const RemoteExecSpec = z.discriminatedUnion("provider", [
          *  "all three of endpoint/access/secret required" gate). */
         s3Snapshot: z
             .object({
-            endpoint: NON_SECRET_URL, // S3/MinIO endpoint — creds go in accessKeyEnv/secretKeyEnv, never the URL
+            endpoint: NON_SECRET_URL_NO_MIGRATION, // S3/MinIO endpoint — creds go in accessKeyEnv/secretKeyEnv, never the URL
             bucket: execStr.optional(),
             accessKeyEnv: ENV_NAME,
             secretKeyEnv: ENV_NAME,

package/dist/retired-form.d.ts

@@ -11,7 +11,7 @@
 import { z } from "zod";
 /** 迁移命令行的唯一拼写:`npx` 全名形 —— 没装本包的运维粘贴即可跑(裸 bin 名在没装本包的机器上是 `command not found`)。参数是一个 `config.d` 目录。 */
 export declare const MIGRATE_COMMAND: "npx @sema-agent/settings-schema migrate";
-/** 拒句尾的迁移指路:存量由哪一条一次性迁移改写、两种跑法(子路径的函数 / 目录命令)。`before` = 旧形不再合法的那一版。
+/** 拒句尾的迁移指路:存量由哪一条一次性迁移改写、两种跑法(子路径的函数 / 目录命令;目录是 `config.d` 目录本身,不是它的上一层)。`before` = 旧形不再合法的那一版。
  *  刻意短:它挂在 zod issue 句尾,读侧逐条容错时每一条被丢的条目都要过一遍出门脱敏。 */
 export declare function migrationSignpost(migration: string, before: string): string;
 /** 一个retired 形的整句:`<form> was retired in <版本> — now <今天住哪>; <指路>`。 */

package/dist/retired-form.js

@@ -11,10 +11,10 @@
 import { z } from "zod";
 /** 迁移命令行的唯一拼写:`npx` 全名形 —— 没装本包的运维粘贴即可跑(裸 bin 名在没装本包的机器上是 `command not found`)。参数是一个 `config.d` 目录。 */
 export const MIGRATE_COMMAND = "npx @sema-agent/settings-schema migrate";
-/** 拒句尾的迁移指路:存量由哪一条一次性迁移改写、两种跑法(子路径的函数 / 目录命令)。`before` = 旧形不再合法的那一版。
+/** 拒句尾的迁移指路:存量由哪一条一次性迁移改写、两种跑法(子路径的函数 / 目录命令;目录是 `config.d` 目录本身,不是它的上一层)。`before` = 旧形不再合法的那一版。
  *  刻意短:它挂在 zod issue 句尾,读侧逐条容错时每一条被丢的条目都要过一遍出门脱敏。 */
 export function migrationSignpost(migration, before) {
-    return `data stored before ${before}: run the one-time migration ${migration} (@sema-agent/settings-schema/one-time-migrations, or ${MIGRATE_COMMAND} <dir>)`;
+    return `data stored before ${before}: run the one-time migration ${migration} (@sema-agent/settings-schema/one-time-migrations, or ${MIGRATE_COMMAND} <config.d directory>)`;
 }
 export function retiredFormSentence(form, t) {
     return `${form} was retired in ${t.retiredIn} — now ${t.now}; ${migrationSignpost(t.migration, t.retiredIn)}`;

package/dist/scheduler-store-node.d.ts

@@ -9,9 +9,10 @@ import { type SchedulerParseWarning, type SchedulerReadOptions, type SchedulerRe
  */
 export declare function loadSchedulerStore(path: string, opts: SchedulerReadOptions): SchedulerStoreRead;
 /**
- * Persist ATOMICALLY: `mkdir -p` the parent, write a uniquely-named `.tmp` sibling (mode 0o600 — owner-only, the
- * records may carry principal/session identifiers), then `rename` over the target (atomic on POSIX, so a
- * concurrent reader never sees a partial file). Throws on IO failure (caller maps to a domain error).
+ * Persist ATOMICALLY: `mkdir -p` the parent, then the package's one atomic writer (`./atomic-write`: a uniquely-named `.tmp`
+ * sibling, then `rename` over the target — atomic on POSIX, so a concurrent reader never sees a partial file). The file mode
+ * is the `scheduler-store` class's (0o600 — owner-only, the records may carry principal/session identifiers; every save
+ * restores it). Throws on IO failure (caller maps to a domain error).
  */
 export declare function saveSchedulerStore(path: string, records: SchedulerRecord[]): void;
 /** A filesystem-backed {@link SchedulerStore} bound to a path (convenience for the daemon/backend constructors).

package/dist/scheduler-store-node.js

@@ -6,9 +6,9 @@
  *
  * Store path = caller-supplied; both sides agree on `SEMA_CONFIG_DIR` → `~/.sema/scheduled_tasks.json`.
  */
-import { mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
+import { mkdirSync, readFileSync } from 'node:fs';
 import { dirname } from 'node:path';
-import { randomBytes } from 'node:crypto';
+import { writeFileAtomic } from './atomic-write.js';
 import { parseSchedulerStore, serializeSchedulerStore } from './scheduler-store.js';
 /**
  * Load the durable store. A MISSING file (ENOENT) ⇒ no records, no warnings (first-run/never-written case); any OTHER
@@ -31,15 +31,14 @@ export function loadSchedulerStore(path, opts) {
     return parseSchedulerStore(text, opts);
 }
 /**
- * Persist ATOMICALLY: `mkdir -p` the parent, write a uniquely-named `.tmp` sibling (mode 0o600 — owner-only, the
- * records may carry principal/session identifiers), then `rename` over the target (atomic on POSIX, so a
- * concurrent reader never sees a partial file). Throws on IO failure (caller maps to a domain error).
+ * Persist ATOMICALLY: `mkdir -p` the parent, then the package's one atomic writer (`./atomic-write`: a uniquely-named `.tmp`
+ * sibling, then `rename` over the target — atomic on POSIX, so a concurrent reader never sees a partial file). The file mode
+ * is the `scheduler-store` class's (0o600 — owner-only, the records may carry principal/session identifiers; every save
+ * restores it). Throws on IO failure (caller maps to a domain error).
  */
 export function saveSchedulerStore(path, records) {
     mkdirSync(dirname(path), { recursive: true });
-    const tmp = `${path}.${randomBytes(6).toString('hex')}.tmp`;
-    writeFileSync(tmp, serializeSchedulerStore(records), { mode: 0o600 });
-    renameSync(tmp, path); // atomic over the target
+    writeFileAtomic(path, serializeSchedulerStore(records), 'scheduler-store');
 }
 /** A filesystem-backed {@link SchedulerStore} bound to a path (convenience for the daemon/backend constructors).
  *

package/dist/types.d.ts

@@ -62,10 +62,18 @@ export declare function urlQueryFragmentHasSecret(u: URL): boolean;
 /** A URL handed to `fetch` that carries no credential: judged by THE URL shape judge ({@link httpUrlFlaws}, `./url-shape`) — a
  *  hierarchical http(s) URL with neither userinfo nor a fragment (an empty `#` included, 11.0.0) — and with no secret-shaped value
  *  in its path or query ({@link urlQueryFragmentHasSecret}). One issue per flaw, its message the judge's rule sentence (no value
- *  echoed); `params.flaw` carries the rule word.
+ *  echoed; a fragment's also names its migration, {@link nonSecretUrlSentence}); `params.flaw` carries the rule word.
+ *
+ *  This is the seat of every URL in a stored DOMAIN document (models `baseUrl`, mcp `url`, `sessionMirror.engineUrl`, workers
+ *  `gitApiBaseUrl`). A URL outside the domain documents — `remote-exec.json`'s endpoints, the web-admin credential envelope's
+ *  `issuer` — uses {@link NON_SECRET_URL_NO_MIGRATION}.
  *
  *  The value is kept EXACTLY as written: nothing here trims or normalizes it (zod's own `.url()` would hand back a rewritten string). */
 export declare const NON_SECRET_URL: z.ZodString;
+/** {@link NON_SECRET_URL}'s judge for a seat no one-time migration reaches (not a domain document): identical rules and rule
+ *  sentences, but a fragment's refusal carries no migration signpost — pointing at a migration that cannot rewrite the value would
+ *  send the operator to a command that does nothing for it. */
+export declare const NON_SECRET_URL_NO_MIGRATION: z.ZodString;
 /** Validate a free-form `extraBody`: returns true = UNSAFE (reject). A GETTER-FREE, descriptor-based, bounded
  *  walk that rejects — WITHOUT ever invoking a getter (a malicious getter could throw a secret-bearing message,
  *  or return different values across the validate vs persist JSON.stringify calls) — anything that isn't plain

package/dist/types.js

@@ -168,20 +168,52 @@ export function urlQueryFragmentHasSecret(u) {
  *  after it is dropped with it — the engine and server refuse a model route root that carries one, so a stored one only fails
  *  later, on the worker). A query is a legitimate request parameter (`?api-version=…`) and stays. */
 const NON_SECRET_URL_FORBIDS = ["userinfo", "fragment"];
+/** The refusal sentence of one flaw at a {@link NON_SECRET_URL} seat: the judge's rule sentence, and — for the one flaw that stored data
+ *  can carry from before 11.0.0 (a fragment) at a seat the one-time migration reaches — the signpost to the migration that strips
+ *  it, joined the way the other signposted refusals join it (`<rule>; <signpost>`). Closed over the judge's flaw words: a new word is
+ *  a compile error here. */
+function nonSecretUrlSentence(flaw, reachedByMigration) {
+    switch (flaw) {
+        case "fragment":
+            return reachedByMigration ? `${httpUrlRule(flaw)}; ${migrationSignpost("SS-M7", "11.0.0")}` : httpUrlRule(flaw);
+        case "not-http-url":
+        case "userinfo":
+        case "query":
+            return httpUrlRule(flaw);
+        default: {
+            const unhandled = flaw;
+            throw new Error("nonSecretUrlSentence: unhandled flaw word", { cause: unhandled });
+        }
+    }
+}
+/** One judge, two seat kinds — the only difference is the fragment refusal's migration signpost. `reachedByMigration` = the seat sits in a
+ *  stored domain document, which the one-time migration SS-M7 rewrites (it finds its seats by this schema's identity, so "carries the
+ *  signpost" and "is rewritten by SS-M7" cannot drift apart). */
+function createNonSecretUrl(reachedByMigration) {
+    return z.string().superRefine((s, ctx) => {
+        const flaws = httpUrlFlaws(s, NON_SECRET_URL_FORBIDS);
+        for (const flaw of flaws)
+            ctx.addIssue({ code: "custom", message: nonSecretUrlSentence(flaw, reachedByMigration), params: { flaw } });
+        if (flaws.length === 0 && urlQueryFragmentHasSecret(new URL(s))) {
+            ctx.addIssue({ code: "custom", message: "must not carry a secret-shaped value in its path or query — secrets go in the *Env (env-NAME) fields" });
+        }
+    });
+}
 /** A URL handed to `fetch` that carries no credential: judged by THE URL shape judge ({@link httpUrlFlaws}, `./url-shape`) — a
  *  hierarchical http(s) URL with neither userinfo nor a fragment (an empty `#` included, 11.0.0) — and with no secret-shaped value
  *  in its path or query ({@link urlQueryFragmentHasSecret}). One issue per flaw, its message the judge's rule sentence (no value
- *  echoed); `params.flaw` carries the rule word.
+ *  echoed; a fragment's also names its migration, {@link nonSecretUrlSentence}); `params.flaw` carries the rule word.
+ *
+ *  This is the seat of every URL in a stored DOMAIN document (models `baseUrl`, mcp `url`, `sessionMirror.engineUrl`, workers
+ *  `gitApiBaseUrl`). A URL outside the domain documents — `remote-exec.json`'s endpoints, the web-admin credential envelope's
+ *  `issuer` — uses {@link NON_SECRET_URL_NO_MIGRATION}.
  *
  *  The value is kept EXACTLY as written: nothing here trims or normalizes it (zod's own `.url()` would hand back a rewritten string). */
-export const NON_SECRET_URL = z.string().superRefine((s, ctx) => {
-    const flaws = httpUrlFlaws(s, NON_SECRET_URL_FORBIDS);
-    for (const flaw of flaws)
-        ctx.addIssue({ code: "custom", message: httpUrlRule(flaw), params: { flaw } });
-    if (flaws.length === 0 && urlQueryFragmentHasSecret(new URL(s))) {
-        ctx.addIssue({ code: "custom", message: "must not carry a secret-shaped value in its path or query — secrets go in the *Env (env-NAME) fields" });
-    }
-});
+export const NON_SECRET_URL = createNonSecretUrl(true);
+/** {@link NON_SECRET_URL}'s judge for a seat no one-time migration reaches (not a domain document): identical rules and rule
+ *  sentences, but a fragment's refusal carries no migration signpost — pointing at a migration that cannot rewrite the value would
+ *  send the operator to a command that does nothing for it. */
+export const NON_SECRET_URL_NO_MIGRATION = createNonSecretUrl(false);
 /** Validate a free-form `extraBody`: returns true = UNSAFE (reject). A GETTER-FREE, descriptor-based, bounded
  *  walk that rejects — WITHOUT ever invoking a getter (a malicious getter could throw a secret-bearing message,
  *  or return different values across the validate vs persist JSON.stringify calls) — anything that isn't plain

package/dist/web-admin-credential.d.ts

@@ -32,7 +32,7 @@ export declare const WEB_ADMIN_CREDENTIAL_ENVELOPE_KIND: "user-session";
  *    文件**取当前值,不用内存旧值(另一个写者可能刚轮换过)。
  *  · `expiresAt` —— 访问令牌到期时刻(RFC 3339)。
  *  · `issuer` —— 签发它的 web-admin 的**基础 URL**(与读方连 web-admin 的根 URL 同形,可带路径前缀):续签只向同源的 web-admin 发,
- *    同不同源由读方比。URL 形判据与 `remoteExec` 的端点同一只 {@link NON_SECRET_URL}(http(s)、有 host、userinfo 与
+ *    同不同源由读方比。URL 形判据与 `remoteExec` 的端点同一只 {@link NON_SECRET_URL_NO_MIGRATION}(http(s)、有 host、userinfo 与
  *    query / fragment 里不许夹带凭据)—— 本包不另写一份更窄的 URL 律。
  */
 export declare const WebAdminCredentialEnvelope: z.ZodObject<{

package/dist/web-admin-credential.js

@@ -21,7 +21,7 @@
  */
 import { z } from "zod";
 import { looksLikeJwt } from "./api/auth-bridge.js";
-import { NON_SECRET_URL } from "./types.js";
+import { NON_SECRET_URL_NO_MIGRATION } from "./types.js";
 import { WEB_ADMIN_ENV } from "./web-admin-env.js";
 /** 信封 `kind` 的闭集今只有一员(`SEALED_BOX_ALG` 同式的字面常量:schema 的字面与读方的比较都引它)。 */
 export const WEB_ADMIN_CREDENTIAL_ENVELOPE_KIND = "user-session";
@@ -50,7 +50,7 @@ const TokenString = z.string().regex(TOKEN_CHARS, "must be a token: printable AS
  *    文件**取当前值,不用内存旧值(另一个写者可能刚轮换过)。
  *  · `expiresAt` —— 访问令牌到期时刻(RFC 3339)。
  *  · `issuer` —— 签发它的 web-admin 的**基础 URL**(与读方连 web-admin 的根 URL 同形,可带路径前缀):续签只向同源的 web-admin 发,
- *    同不同源由读方比。URL 形判据与 `remoteExec` 的端点同一只 {@link NON_SECRET_URL}(http(s)、有 host、userinfo 与
+ *    同不同源由读方比。URL 形判据与 `remoteExec` 的端点同一只 {@link NON_SECRET_URL_NO_MIGRATION}(http(s)、有 host、userinfo 与
  *    query / fragment 里不许夹带凭据)—— 本包不另写一份更窄的 URL 律。
  */
 export const WebAdminCredentialEnvelope = z
@@ -59,7 +59,7 @@ export const WebAdminCredentialEnvelope = z
     accessToken: TokenString.refine(looksLikeJwt, "must be a JWT (three dot-separated segments) — a worker pull token never goes into an envelope"),
     refreshToken: TokenString,
     expiresAt: RFC3339_DATE_TIME,
-    issuer: NON_SECRET_URL,
+    issuer: NON_SECRET_URL_NO_MIGRATION,
 })
     .strict();
 /** 信封自己的字段名(schema 的键 —— reason 里只许出现这几个名字,不许出现用户写的键)。 */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/settings-schema",
-  "version": "11.0.0",
+  "version": "11.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",