@zhushanwen/pi-subagent-workflow 8.5.0 → 8.6.0

package/src/shared/__tests__/model-ref.test.ts

@@ -0,0 +1,306 @@
+// src/shared/__tests__/model-ref.test.ts
+//
+// [U1 ModelRef 全等裁决] assertCanonicalModelRef / modelRefFromVerified 单测族。
+// 设计权威：docs/design/subagent-dispatch-reliability.md §3.3 D1（规则①~⑤含孪生守卫）、D2（继承路径豁免口径）。
+//
+// P-A2（实施期门）：孪生守卫行为验证——含孪生的 registry 快照实测拒单路径 +
+// 无孪生快照实测放行路径。「有孪生仍放行」= 守卫失效，阻断合入。
+
+import { describe, expect, it } from "vitest";
+
+import {
+  type ModelRefSource,
+  assertCanonicalModelRef,
+  assertThinkingLevel,
+  modelRefFromVerified,
+  stripThinkingSuffix,
+  THINKING_ORDER,
+} from "../model-ref.ts";
+
+// ============================================================
+// helpers
+// ============================================================
+
+/** registry 快照构造（getAvailable 顺序即判定顺序）。 */
+function makeSource(entries: ReadonlyArray<{ provider: string; id: string }>): ModelRefSource {
+  return { getAvailable: () => entries };
+}
+
+/** 基线快照：模拟真实 registry 形态（大小写混合 id + 无关条目）。 */
+const BASELINE: ReadonlyArray<{ provider: string; id: string }> = [
+  { provider: "zai-coding-cn", id: "GLM-5.3-Flash" },
+  { provider: "zai-coding-cn", id: "GLM-5.3" },
+  { provider: "xiaomi-token-plan-cn", id: "mimo-v2.5-pro" },
+  { provider: "deepseek", id: "deepseek-v4-pro" },
+];
+
+// ============================================================
+// 全等放行（规则③）+ 无孪生快照（P-A2 放行路径）
+// ============================================================
+
+describe("assertCanonicalModelRef — exact match passes (rule ③)", () => {
+  it("全等命中 → 返回 {provider, id}，与 registry 条目逐字段全等", () => {
+    const ref = assertCanonicalModelRef("zai-coding-cn/GLM-5.3-Flash", makeSource(BASELINE));
+    expect(ref).toEqual({ provider: "zai-coding-cn", id: "GLM-5.3-Flash" });
+  });
+
+  it("P-A2 放行路径：无孪生快照下全等写法放行（含大小写差异的 id 原样保留）", () => {
+    // 快照中该 id 仅一种大小写形态（GLM-5.3-Flash ≠ glm-5.3，后者是不同 id 而非孪生）
+    const ref = assertCanonicalModelRef("zai-coding-cn/GLM-5.3-Flash", makeSource(BASELINE));
+    expect(ref.id).toBe("GLM-5.3-Flash");
+    expect(ref.provider).toBe("zai-coding-cn");
+  });
+
+  it("无关大小写的不同 id（GLM-5.3 vs GLM-5.3-Flash）不构成孪生，全等命中各自放行", () => {
+    const source = makeSource(BASELINE);
+    expect(assertCanonicalModelRef("zai-coding-cn/GLM-5.3", source)).toEqual({
+      provider: "zai-coding-cn",
+      id: "GLM-5.3",
+    });
+  });
+});
+
+// ============================================================
+// 非全等同步拒单（规则②⑤）+ case variant 首位建议
+// ============================================================
+
+describe("assertCanonicalModelRef — non-exact rejected synchronously (rule ⑤)", () => {
+  it("小写变体输入 → 同步抛错（不采纳、不改写），错误含原始输入", () => {
+    expect(() =>
+      assertCanonicalModelRef("zai-coding-cn/glm-5.3-flash", makeSource(BASELINE)),
+    ).toThrow(/is not a registry entry/);
+  });
+
+  it("case variant 是首个建议且标注 ← case variant（S2 负面路径）", () => {
+    let msg = "";
+    try {
+      assertCanonicalModelRef("zai-coding-cn/glm-5.3-flash", makeSource(BASELINE), { source: "paramOverride" });
+    } catch (e) {
+      msg = (e as Error).message;
+    }
+    expect(msg).toMatch(/is not a registry entry/);
+    expect(msg).toContain('Model "zai-coding-cn/glm-5.3-flash" (paramOverride)');
+    expect(msg).toMatch(/Registry match is case-sensitive/);
+    expect(msg).toMatch(/Did you mean one of these\?/);
+    // case variant 排首位并标注
+    const didYouMeanIdx = msg.indexOf("Did you mean one of these?");
+    const variantLine = msg.indexOf("zai-coding-cn/GLM-5.3-Flash   ← case variant of \"glm-5.3-flash\"");
+    expect(variantLine).toBeGreaterThan(didYouMeanIdx);
+    // 其他模糊候选在 case variant 之后
+    const otherIdx = msg.indexOf("Other models you may have meant");
+    expect(otherIdx).toBeGreaterThan(variantLine);
+    expect(msg).toContain("zai-coding-cn/GLM-5.3");
+  });
+
+  it("错误末尾附「省略 model 继承主 agent」指引", () => {
+    let msg = "";
+    try {
+      assertCanonicalModelRef("zai-coding-cn/glm-5.3-flash", makeSource(BASELINE));
+    } catch (e) {
+      msg = (e as Error).message;
+    }
+    expect(msg).toMatch(/Or omit the `model` param to inherit the main agent model\./);
+  });
+
+  it("provider 大小写不同（Zai-Coding-CN）→ 不命中（provider 精确匹配，规则②）", () => {
+    let msg = "";
+    try {
+      assertCanonicalModelRef("Zai-Coding-CN/GLM-5.3-Flash", makeSource(BASELINE));
+    } catch (e) {
+      msg = (e as Error).message;
+    }
+    expect(msg).toMatch(/is not a registry entry/);
+    // provider 拼写相近 → general 候选命中
+    expect(msg).toMatch(/Other models you may have meant/);
+  });
+
+  it("同 provider 但 id 不存在 → provider 相似度候选（同 provider 下其他条目）", () => {
+    let msg = "";
+    try {
+      assertCanonicalModelRef("zai-coding-cn/nonexistent-probe", makeSource(BASELINE), { source: "agentConfig" });
+    } catch (e) {
+      msg = (e as Error).message;
+    }
+    expect(msg).toMatch(/is not a registry entry/);
+    expect(msg).not.toMatch(/Did you mean/);
+    expect(msg).toMatch(/Other models you may have meant/);
+    expect(msg).toContain("zai-coding-cn/GLM-5.3-Flash");
+    expect(msg).toContain("(agentConfig)");
+  });
+
+  it("provider 与 id 均无相似物 → 列合法串全集 + 继承指引（S2 前者路径）", () => {
+    let msg = "";
+    try {
+      assertCanonicalModelRef("ghost-provider/zzz-unknown", makeSource(BASELINE));
+    } catch (e) {
+      msg = (e as Error).message;
+    }
+    expect(msg).toMatch(/is not a registry entry/);
+    expect(msg).not.toMatch(/Did you mean/);
+    expect(msg).toMatch(/No similar models found\./);
+    expect(msg).toMatch(/Available models:/);
+    // 合法串全集（canonical 形态，可复制）
+    expect(msg).toContain("zai-coding-cn/GLM-5.3-Flash");
+    expect(msg).toContain("xiaomi-token-plan-cn/mimo-v2.5-pro");
+    expect(msg).toMatch(/Or omit the `model` param to inherit the main agent model\./);
+  });
+
+  it("无 slash / 空 id → 同步拒单（结构非法）", () => {
+    const source = makeSource(BASELINE);
+    expect(() => assertCanonicalModelRef("no-slash", source)).toThrow(/is not a registry entry/);
+    expect(() => assertCanonicalModelRef("only-provider/", source)).toThrow(/is not a registry entry/);
+  });
+
+  it("空 registry → 明确提示 + 继承指引", () => {
+    let msg = "";
+    try {
+      assertCanonicalModelRef("p/m", makeSource([]));
+    } catch (e) {
+      msg = (e as Error).message;
+    }
+    expect(msg).toMatch(/Registry has no available models\./);
+    expect(msg).toMatch(/Or omit the `model` param/);
+  });
+});
+
+// ============================================================
+// strip thinking 后缀（规则①）
+// ============================================================
+
+describe("assertCanonicalModelRef — strips legal thinking suffix (rule ①)", () => {
+  it('":xhigh" 后缀剥离后全等命中', () => {
+    const ref = assertCanonicalModelRef("deepseek/deepseek-v4-pro:xhigh", makeSource(BASELINE));
+    expect(ref).toEqual({ provider: "deepseek", id: "deepseek-v4-pro" });
+  });
+
+  it('":max" 后缀剥离后全等命中（THINKING_ORDER 含 max）', () => {
+    const ref = assertCanonicalModelRef("zai-coding-cn/GLM-5.3-Flash:max", makeSource(BASELINE));
+    expect(ref.id).toBe("GLM-5.3-Flash");
+  });
+
+  it('非白名单后缀（":foo"）不剥离 → 未命中拒单', () => {
+    expect(() =>
+      assertCanonicalModelRef("zai-coding-cn/GLM-5.3-Flash:foo", makeSource(BASELINE)),
+    ).toThrow(/is not a registry entry/);
+  });
+});
+
+// ============================================================
+// 孪生守卫（规则④）—— P-A2 拒单路径
+// ============================================================
+
+describe("assertCanonicalModelRef — twin guard (rule ④, P-A2)", () => {
+  /** 含大小写孪生的 registry 快照（模拟 models-store 刷新后 GLM-5.3-Flash 与 glm-5.3-flash 并存）。 */
+  const TWIN_SNAPSHOT: ReadonlyArray<{ provider: string; id: string }> = [
+    { provider: "zai-coding-cn", id: "GLM-5.3-Flash" },
+    { provider: "zai-coding-cn", id: "glm-5.3-flash" },
+    { provider: "deepseek", id: "deepseek-v4-pro" },
+  ];
+
+  it("P-A2 拒单路径：有孪生仍放行 = 守卫失效——全等命中（大写形态）也必须拒绝", () => {
+    let msg = "";
+    try {
+      // 输入与快照条目逐字符全等，但 registry 存在 case-insensitive 相等的另一条目
+      assertCanonicalModelRef("zai-coding-cn/GLM-5.3-Flash", makeSource(TWIN_SNAPSHOT));
+    } catch (e) {
+      msg = (e as Error).message;
+    }
+    expect(msg).toContain('Model "zai-coding-cn/GLM-5.3-Flash" matches a registry entry exactly');
+    expect(msg).toMatch(
+      /registry contains ambiguous case variants for zai-coding-cn\/GLM-5\.3-Flash: \[zai-coding-cn\/GLM-5\.3-Flash, zai-coding-cn\/glm-5\.3-flash\]/,
+    );
+    // 恢复指引：清理重复条目后重试
+    expect(msg).toMatch(/Recovery: remove the duplicate case variant from models\.json/);
+    expect(msg).toMatch(/then retry with the exact registry string\./);
+  });
+
+  it("P-A2 拒单路径：孪生快照下小写全等形态同样拒绝（两个方向都不放行）", () => {
+    expect(() =>
+      assertCanonicalModelRef("zai-coding-cn/glm-5.3-flash", makeSource(TWIN_SNAPSHOT)),
+    ).toThrow(/ambiguous case variants/);
+  });
+
+  it("无孪生快照下同串放行（守卫零误伤）", () => {
+    const ref = assertCanonicalModelRef("zai-coding-cn/GLM-5.3-Flash", makeSource(BASELINE));
+    expect(ref.id).toBe("GLM-5.3-Flash");
+  });
+
+  it("不同 provider 下的同形 id 不构成孪生（provider 精确作用域）", () => {
+    const snapshot = [
+      { provider: "zai-coding-cn", id: "GLM-5.3-Flash" },
+      { provider: "other-cn", id: "glm-5.3-flash" },
+    ];
+    const ref = assertCanonicalModelRef("zai-coding-cn/GLM-5.3-Flash", makeSource(snapshot));
+    expect(ref.id).toBe("GLM-5.3-Flash");
+  });
+});
+
+// ============================================================
+// 继承路径包装（D2 豁免口径）：modelRefFromVerified
+// ============================================================
+
+describe("modelRefFromVerified — ctxModel inheritance path (D2)", () => {
+  it("无孪生 → 包装为 ModelRef（{provider, id} 形态，供 ${provider}/${id} 拼接）", () => {
+    const ref = modelRefFromVerified(
+      { provider: "zai-coding-cn", id: "GLM-5.3-Flash" },
+      makeSource(BASELINE),
+    );
+    expect(ref).toEqual({ provider: "zai-coding-cn", id: "GLM-5.3-Flash" });
+  });
+
+  it("豁免存在性复查：ctxModel 不在 registry 快照中仍放行（运行时已验证）", () => {
+    // registry 为空（快照过期等）不阻塞继承——缺省继承是输入缺省而非变体放行
+    const ref = modelRefFromVerified(
+      { provider: "runtime-only", id: "live-model" },
+      makeSource([]),
+    );
+    expect(ref).toEqual({ provider: "runtime-only", id: "live-model" });
+  });
+
+  it("P-A2 双路径生效：含孪生快照下继承路径同样拒绝（豁免的只是存在性复查，不是孪生守卫）", () => {
+    const TWIN_SNAPSHOT = [
+      { provider: "zai-coding-cn", id: "GLM-5.3-Flash" },
+      { provider: "zai-coding-cn", id: "glm-5.3-flash" },
+    ];
+    expect(() =>
+      modelRefFromVerified({ provider: "zai-coding-cn", id: "GLM-5.3-Flash" }, makeSource(TWIN_SNAPSHOT)),
+    ).toThrow(/ambiguous case variants/);
+  });
+});
+
+// ============================================================
+// stripThinkingSuffix / assertThinkingLevel
+// ============================================================
+
+describe("stripThinkingSuffix", () => {
+  it("剥白名单后缀", () => {
+    expect(stripThinkingSuffix("p/m:high")).toBe("p/m");
+    expect(stripThinkingSuffix("p/m:off")).toBe("p/m");
+    expect(stripThinkingSuffix("p/m")).toBe("p/m");
+  });
+
+  it("非白名单冒号后缀不剥", () => {
+    expect(stripThinkingSuffix("p/m:foo")).toBe("p/m:foo");
+  });
+});
+
+describe("assertThinkingLevel", () => {
+  it("undefined 透传", () => {
+    expect(assertThinkingLevel(undefined)).toBeUndefined();
+  });
+
+  it("白名单值放行并窄化为字面量联合", () => {
+    expect(assertThinkingLevel("high")).toBe("high");
+    expect(assertThinkingLevel("max")).toBe("max");
+  });
+
+  it("非白名单值同步抛错（可操作文案：列出合法值）", () => {
+    expect(() => assertThinkingLevel("ultra")).toThrow(
+      /Invalid thinkingLevel "ultra"\. Allowed values: off, minimal, low, medium, high, xhigh, max\./,
+    );
+  });
+
+  it("THINKING_ORDER SSOT：白名单全集顺序稳定（低→高，含 max）", () => {
+    expect(THINKING_ORDER).toEqual(["off", "minimal", "low", "medium", "high", "xhigh", "max"]);
+  });
+});

package/src/shared/__tests__/schema-jsonify.test.ts

@@ -58,7 +58,7 @@ describe("stringifySchemaCached — WeakMap 引用级缓存", () => {
     }
   });
 
-  it("pretty 缩进锚定：indent=2 与 formatSchemaInstruction 渲染同源", () => {
+  it("pretty 缩进锚定：indent=2 与 resolver formatSchemaInstruction 渲染同源", () => {
     const out = stringifySchemaCached({ type: "object" }, "pretty");
     expect(out).toBe('{\n  "type": "object"\n}');
   });

package/src/shared/__tests__/timer-delay.test.ts

@@ -0,0 +1,61 @@
+// src/shared/__tests__/timer-delay.test.ts
+//
+// assertSafeTimerDelay 纯函数契约——三个 timer 挂载入口（budgetTimeMs /
+// XYZ_SUBAGENT_SPAWN_WATCHDOG_MS / idleTimeoutMs）统一在值流入 setTimeout 前调
+// 用本函数 fail-fast，契约由本文件锁定。
+//
+// [F-3 NaN 穿透修复] 旧实现只挡 `> MAX`：NaN 的 `NaN > MAX` 为 false 静默放行，
+// setTimeout(fn, NaN) 被 Node 塌缩为 1ms 立即触发（watchdog 刚启动就误杀）。
+// 非有限数（NaN/±Infinity）现在同样 fail-fast，且错误消息区分两种情况。
+import { describe, expect, it } from "vitest";
+
+import { MAX_TIMER_DELAY_MS, assertSafeTimerDelay } from "../timer-delay.ts";
+
+describe("assertSafeTimerDelay", () => {
+  it("安全域内的有限值放行（0 与上限值不抛）", () => {
+    expect(() => assertSafeTimerDelay(0, "t")).not.toThrow();
+    expect(() => assertSafeTimerDelay(1000, "t")).not.toThrow();
+    expect(() => assertSafeTimerDelay(MAX_TIMER_DELAY_MS, "t")).not.toThrow();
+  });
+
+  it("[F-3] NaN → fail-fast throw（旧实现 NaN > MAX 为 false 静默放行）", () => {
+    expect(() => assertSafeTimerDelay(Number.NaN, "budgetTimeMs")).toThrowError(/NaN/);
+    expect(() => assertSafeTimerDelay(Number.NaN, "budgetTimeMs")).toThrowError(/not a finite number/);
+  });
+
+  it("[F-3] ±Infinity → fail-fast throw", () => {
+    expect(() => assertSafeTimerDelay(Number.POSITIVE_INFINITY, "t")).toThrowError(/not a finite number/);
+    expect(() => assertSafeTimerDelay(Number.NEGATIVE_INFINITY, "t")).toThrowError(/not a finite number/);
+  });
+
+  it("非有限值错误消息含来源标识与上游修复指引（非 clamp 指引）", () => {
+    expect(() => assertSafeTimerDelay(Number.NaN, "idleTimeoutMs")).toThrowError(/idleTimeoutMs/);
+    expect(() => assertSafeTimerDelay(Number.NaN, "idleTimeoutMs")).toThrowError(/fix the upstream computation/);
+  });
+
+  it("超出上限 → fail-fast throw，消息含上限值与 clamp 恢复指引（原语义不变）", () => {
+    expect(() => assertSafeTimerDelay(MAX_TIMER_DELAY_MS + 1, "budgetTimeMs")).toThrowError(/2147483647/);
+    expect(() => assertSafeTimerDelay(3_000_000_000, "budgetTimeMs")).toThrowError(/Recovery: clamp/);
+  });
+
+  it("两种错误可区分：非有限值消息不含 clamp 指引，溢出消息不含 upstream 指引", () => {
+    const nonFiniteMsg = (() => {
+      try {
+        assertSafeTimerDelay(Number.NaN, "t");
+        return "";
+      } catch (err) {
+        return (err as Error).message;
+      }
+    })();
+    const overflowMsg = (() => {
+      try {
+        assertSafeTimerDelay(MAX_TIMER_DELAY_MS + 1, "t");
+        return "";
+      } catch (err) {
+        return (err as Error).message;
+      }
+    })();
+    expect(nonFiniteMsg).not.toContain("clamp");
+    expect(overflowMsg).not.toContain("fix the upstream computation");
+  });
+});

package/src/shared/model-ref.ts

@@ -0,0 +1,286 @@
+// src/shared/model-ref.ts
+//
+// [U1 ModelRef 全等裁决] 模型身份的唯一裁决入口（设计 docs/design/subagent-dispatch-reliability.md D1/D2）。
+//
+// 零宽容原则：除「缺省继承主 agent 模型」外，只有与 registry 条目**全等精确匹配（含大小写）**
+// 的模型串可放行；模糊匹配（case variant / 包含关系 / provider 相似度）只用于生成报错里的
+// 纠错候选，永不参与采纳。系统绝不代改输入——恢复动作始终是「重发修正后的参数」。
+//
+// 裁决发生在 start 工具调用的同步期（spawn 之前）：放行返回 {provider, id} 供
+// `${provider}/${id}` 拼接，未命中/孪生歧义同步抛错。
+//
+// 背景（D1 证据）：pi CLI 的 tryMatchModel 是 pattern 模糊引擎（id 匹配用 toLowerCase()），
+// registry 存在大小写孪生时 canonical 串亦被判歧义作废、落入模糊分支 localeCompare 取最大——
+// 因此「扩展侧全等放行」不能独立保证「子进程按此名执行」，孪生守卫必须内建（规则④）。
+
+// ============================================================
+// 类型
+// ============================================================
+
+/** 裁决产物：registry 全等条目的 (provider, id)，供 `${provider}/${id}` 拼接。 */
+export interface ModelRef {
+  provider: string;
+  id: string;
+}
+
+/**
+ * 模型清单源的最小 duck 接口（只读 getAvailable）。
+ * execution/model-resolver.ts 的 ModelRegistryLike 结构兼容（getAvailable 返回 ModelInfo 超集）。
+ */
+export interface ModelRefSource {
+  getAvailable(): ReadonlyArray<{ provider: string; id: string }>;
+}
+
+// ============================================================
+// thinking level 白名单（SSOT：原 execution/model-resolver.ts 常量迁入，
+// model-resolver re-export 保持既有 import 路径不变）
+// ============================================================
+
+/** thinking level 支持顺序（低→高）。spawn 侧 `:level` 后缀仅接受本白名单值。 */
+export const THINKING_ORDER = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+
+/** 合法 thinking level 字面量联合（类型层面收窄，裸字符串不可达 spawn 拼接）。 */
+export type ThinkingLevel = (typeof THINKING_ORDER)[number];
+
+/** 报错信息中列出的候选/全集模型上限（防超长错误信息）。 */
+const MODEL_LIST_LIMIT = 20;
+
+/**
+ * 校验 thinkingLevel 属于 THINKING_ORDER 白名单，返回窄化类型。
+ *
+ * buildSpawnArgs 的 thinkingLevel 参数类型为 ThinkingLevel（白名单联合）——TS 调用方
+ * 传非法值编译期即报错；本断言是运行时防线（防 JS 调用方/动态数据绕过类型）。
+ * undefined 透传（无显式 level 语义）。
+ */
+export function assertThinkingLevel(level: string | undefined): ThinkingLevel | undefined {
+  if (level === undefined) return undefined;
+  const hit = THINKING_ORDER.find((l) => l === level);
+  if (hit === undefined) {
+    throw new Error(
+      `Invalid thinkingLevel "${level}". Allowed values: ${THINKING_ORDER.join(", ")}. ` +
+        `Retry with one of the allowed values, or omit the param.`,
+    );
+  }
+  return hit;
+}
+
+// ============================================================
+// 规则①：strip 合法 thinking 后缀
+// ============================================================
+
+/**
+ * 剥离模型字符串尾部 ":thinkingLevel" 后缀（如 "ds-pro:xhigh" → "ds-pro"）。
+ * 仅匹配合法 thinking level（THINKING_ORDER 白名单），避免误剥 "foo:bar" 这类无关冒号。
+ */
+export function stripThinkingSuffix(modelStr: string): string {
+  // 按长度降序拼正则避免短串误匹配（如 "off" 先于 "o"——白名单无单字符，防御性保留）
+  const alt = THINKING_ORDER.slice().sort((a, b) => b.length - a.length).join("|");
+  return modelStr.replace(new RegExp(`:(${alt})$`), "");
+}
+
+// ============================================================
+// 规则④：孪生守卫（两条路径共用）
+// ============================================================
+
+/**
+ * 收集 registry 中与 (provider, id) case-insensitive 相等但非全等的其他条目
+ * （大小写孪生）。判定粒度对齐 pi findExactModelReferenceMatch：provider 精确相等 +
+ * id toLowerCase 相等。返回孪生条目的 "provider/id" 全串列表。
+ */
+function collectCaseVariants(
+  provider: string,
+  id: string,
+  source: ModelRefSource,
+): string[] {
+  const lowerId = id.toLowerCase();
+  return source
+    .getAvailable()
+    .filter((m) => m.provider === provider && m.id !== id && m.id.toLowerCase() === lowerId)
+    .map((m) => `${m.provider}/${m.id}`);
+}
+
+/**
+ * 规则④孪生守卫错误（D1 文案）。命中全等但 registry 自身含大小写歧义 → 拒绝放行，
+ * 恢复动作 = 清理重复条目后重试（输入侧不可控维度，系统不代改 registry）。
+ */
+function ambiguousVariantError(ref: string, variants: string[]): Error {
+  return new Error(
+    `Model "${ref}" matches a registry entry exactly, but registry contains ambiguous case variants ` +
+      `for ${ref}: [${variants.join(", ")}].\n` +
+      `Recovery: remove the duplicate case variant from models.json (or the models-store cache) ` +
+      `so exactly one case form remains, then retry with the exact registry string.`,
+  );
+}
+
+// ============================================================
+// 继承路径（D2 豁免口径）：已验证 ModelInfo → ModelRef 包装
+// ============================================================
+
+/**
+ * ctxModel 继承路径的 ModelRef 包装（D2 豁免口径）。
+ *
+ * ctxModel 是运行时已验证的 ModelInfo 对象（主 agent 在用），豁免 registry 存在性复查
+ * 与 auth 校验——「缺省继承」是输入缺省而非变体放行；但继承产出的 canonical 串与显式
+ * 入参走同一个 pi pattern 引擎，**孪生守卫同等适用**（registry 含大小写孪生时拒绝放行）。
+ *
+ * @throws 孪生歧义时同步抛错（ambiguousVariantError 文案）
+ */
+export function modelRefFromVerified(
+  info: { provider: string; id: string },
+  source: ModelRefSource,
+): ModelRef {
+  const twins = collectCaseVariants(info.provider, info.id, source);
+  if (twins.length > 0) {
+    throw ambiguousVariantError(`${info.provider}/${info.id}`, [`${info.provider}/${info.id}`, ...twins]);
+  }
+  return { provider: info.provider, id: info.id };
+}
+
+// ============================================================
+// 规则⑤：未命中错误（模糊匹配只做建议，绝不采纳）
+// ============================================================
+
+/**
+ * case variant 候选：provider 精确相等 + id case-insensitive 相等（含跨 registry 的
+ * 显式大小写差异）。这是最高置信建议，排首位并标注。
+ */
+function findCaseVariantSuggestions(
+  provider: string,
+  id: string,
+  source: ModelRefSource,
+): string[] {
+  const lowerId = id.toLowerCase();
+  return source
+    .getAvailable()
+    .filter((m) => m.provider === provider && m.id.toLowerCase() === lowerId)
+    .map((m) => `${m.provider}/${m.id}`);
+}
+
+/**
+ * 一般模糊候选：id 双向包含 或 provider case-insensitive 双向包含（provider 相似度）。
+ * 排除已列入 case variant 的条目。
+ */
+function findSimilarSuggestions(
+  provider: string,
+  id: string,
+  source: ModelRefSource,
+  exclude: ReadonlySet<string>,
+): string[] {
+  const lowerId = id.toLowerCase();
+  const lowerProvider = provider.toLowerCase();
+  return source
+    .getAvailable()
+    .map((m) => `${m.provider}/${m.id}`)
+    .filter((full) => {
+      if (exclude.has(full)) return false;
+      const slashIdx = full.indexOf("/");
+      const mProvider = full.slice(0, slashIdx);
+      const mId = full.slice(slashIdx + 1);
+      const lowerMId = mId.toLowerCase();
+      const lowerMProvider = mProvider.toLowerCase();
+      return (
+        lowerMId.includes(lowerId) ||
+        lowerId.includes(lowerMId) ||
+        lowerMProvider.includes(lowerProvider) ||
+        lowerProvider.includes(lowerMProvider)
+      );
+    })
+    .slice(0, MODEL_LIST_LIMIT);
+}
+
+/** 规则⑤未命中错误：问句候选 + 合法串全集（无候选时）+ 继承指引。 */
+function notFoundError(
+  input: string,
+  prefix: string,
+  provider: string,
+  id: string,
+  source: ModelRefSource,
+): Error {
+  const lines = [
+    `Model "${input}"${prefix} is not a registry entry. ` +
+      `Registry match is case-sensitive — the string must equal a registry entry exactly, including letter case.`,
+  ];
+
+  const caseVariants = id.length > 0 ? findCaseVariantSuggestions(provider, id, source) : [];
+  if (caseVariants.length > 0) {
+    lines.push(`Did you mean one of these?`);
+    for (const full of caseVariants) {
+      lines.push(`  ${full}   ← case variant of "${id}"`);
+    }
+    const similar = findSimilarSuggestions(provider, id, source, new Set(caseVariants));
+    if (similar.length > 0) {
+      lines.push(`Other models you may have meant (similar id/provider):`);
+      for (const full of similar) lines.push(`  ${full}`);
+    }
+  } else {
+    const available = source.getAvailable().map((m) => `${m.provider}/${m.id}`);
+    if (available.length === 0) {
+      lines.push(`Registry has no available models.`);
+    } else {
+      const similar = findSimilarSuggestions(provider, id, source, new Set());
+      if (similar.length > 0) {
+        lines.push(`Other models you may have meant (similar id/provider):`);
+        for (const full of similar) lines.push(`  ${full}`);
+      } else {
+        lines.push(`No similar models found.`);
+        lines.push(`Available models:`);
+        for (const full of available.slice(0, MODEL_LIST_LIMIT)) lines.push(`  ${full}`);
+      }
+    }
+  }
+
+  lines.push(`Or omit the \`model\` param to inherit the main agent model.`);
+  return new Error(lines.join("\n"));
+}
+
+// ============================================================
+// 单一裁决入口（规则①→⑤）
+// ============================================================
+
+/**
+ * 模型串 → ModelRef 的唯一裁决入口（D1）。
+ *
+ * ① strip 合法 thinking 后缀（THINKING_ORDER 白名单）；
+ * ② provider 精确匹配（区分大小写）；
+ * ③ modelId 与 registry 条目全等精确匹配（含大小写）；
+ * ④ 孪生守卫——全等命中后 case-insensitive 复扫 registry，存在孪生条目即拒绝放行；
+ * ⑤ 未命中 → 同步抛错，错误含 "Did you mean" 问句候选（case variant 排首位并标注）+
+ *    合法串全集（无候选时）+ 「省略 model 继承主 agent」指引。
+ *
+ * 系统绝不代改输入：不自动纠正、不放行变体、不重试。
+ *
+ * @param input  调用方原始模型串（"provider/modelId[:thinkingLevel]"）
+ * @param source 模型清单源（registry 快照）
+ * @param opts.source 可选来源标签（"paramOverride" / "agentConfig"），进错误首行辅助定位
+ * @returns 全等 ModelRef（放行即与 registry 条目全等，`${provider}/${id}` 可直接拼接）
+ * @throws 未命中 / 孪生歧义时同步抛错（start 工具调用同步期完成裁决）
+ */
+export function assertCanonicalModelRef(
+  input: string,
+  source: ModelRefSource,
+  opts: { source?: string } = {},
+): ModelRef {
+  const prefix = opts.source ? ` (${opts.source})` : "";
+  const clean = stripThinkingSuffix(input);
+  const slashIdx = clean.indexOf("/");
+  const provider = slashIdx > 0 ? clean.slice(0, slashIdx) : "";
+  const id = slashIdx > 0 ? clean.slice(slashIdx + 1) : "";
+
+  if (provider.length > 0 && id.length > 0) {
+    const exact = source
+      .getAvailable()
+      .find((m) => m.provider === provider && m.id === id);
+    if (exact) {
+      const twins = collectCaseVariants(exact.provider, exact.id, source);
+      if (twins.length > 0) {
+        throw ambiguousVariantError(`${exact.provider}/${exact.id}`, [
+          `${exact.provider}/${exact.id}`,
+          ...twins,
+        ]);
+      }
+      return { provider: exact.provider, id: exact.id };
+    }
+  }
+
+  throw notFoundError(input, prefix, provider, id, source);
+}