@zhushanwen/pi-subagent-workflow 8.5.0 → 8.6.0

package/src/execution/__tests__/tool-action.test.ts

@@ -103,7 +103,7 @@ describe("startHandler", () => {
     ).rejects.toThrow(/≤35 chars/);
   });
 
-  it("background 启动 → kind=bg + bgResponse.message 含 detached", async () => {
+  it("background 启动 → kind=bg + bgResponse.message 含 detached + notifyContract 恒值", async () => {
     const svc = makeService({
       execute: vi.fn(async (): Promise<ExecutionHandle> => ({
         mode: "background",
@@ -117,6 +117,50 @@ describe("startHandler", () => {
     if (r.kind !== "bg") return;
     expect(r.subagentId).toBe("bg-1-123");
     expect(r.response.message).toMatch(/detached/);
+    // [U1] 通知投递契约回显位（U2 账本兑现）
+    expect(r.response.notifyContract).toBe("ledger+at-least-once");
+  });
+
+  it("[U1] start 返回值 model 为 registry 全等回显（透传 handle.details.model）", async () => {
+    const svc = makeService({
+      execute: vi.fn(async (): Promise<ExecutionHandle> => ({
+        mode: "background",
+        subagentId: "bg-2-456",
+        sessionFile: undefined,
+        // record.model = resolved（裁决放行条目）拼接的 "provider/id"，保留 registry 大小写
+        details: makeDetails({ status: "running", mode: "background", model: "zai-coding-cn/GLM-5.3-Flash" }),
+      })),
+    });
+    const r = await startHandler(svc, { task: "t", slug: "s" }, undefined);
+    expect(r.model).toBe("zai-coding-cn/GLM-5.3-Flash");
+    // adapter 外层 result 同源回显
+    const toolResult = adapter({ action: "start", domain: r });
+    const result = toolResult.details;
+    if (result.action !== "start") throw new Error("expected start variant");
+    expect(result.model).toBe("zai-coding-cn/GLM-5.3-Flash");
+    // LLM content JSON 同源（与 details 一致）
+    const contentJson = JSON.parse(toolResult.content[0]!.type === "text" ? toolResult.content[0].text : "{}");
+    expect(contentJson.model).toBe("zai-coding-cn/GLM-5.3-Flash");
+    expect(contentJson.bgResponse.notifyContract).toBe("ledger+at-least-once");
+  });
+
+  it("[U1] model 非全等 → 裁决错误向上传播（无 bgResponse 产出，execute 不重试）", async () => {
+    // 裁决发生在 service.execute 内部步骤 1（IDENTITY 解析 → resolveModel），在 record
+    // 创建 / runSpawn 之前——错误直接向上传播为 tool isError。resolveModel 层的拒单
+    // 行为（含 P-A2 双路径）由 model-ref.test.ts + model-resolver.test.ts 锁定；本用例
+    // 锁定 handler 层传播语义：异常穿越 startHandler，不产出任何受理响应。
+    const svc = makeService({
+      execute: vi.fn(async () => {
+        throw new Error(
+          'Model "zai-coding-cn/glm-5.3-flash" (paramOverride) is not a registry entry. ' +
+            "Did you mean one of these?\n  zai-coding-cn/GLM-5.3-Flash",
+        );
+      }),
+    });
+    await expect(
+      startHandler(svc, { task: "t", slug: "s", model: "zai-coding-cn/glm-5.3-flash" }, undefined),
+    ).rejects.toThrow(/is not a registry entry.*Did you mean/s);
+    expect(svc.execute).toHaveBeenCalledTimes(1);
   });
 });
 
@@ -377,6 +421,53 @@ describe("adapter", () => {
     expect(r.details.listResponse).toEqual({ running: 0, items: [] });
   });
 
+  // [U3 C-outcome] 对外 JSON 契约：list items 携带 outcome 且旧字段保留（验收③）。
+  it("[U3] list JSON：items[].outcome 在位（failed 值）且 status/mode/state 旧字段保留", () => {
+    const r = adapter({
+      action: "list",
+      domain: {
+        response: {
+          running: 0,
+          items: [
+            {
+              subagentId: "bg-u3", agent: "w", slug: "s", state: "ended", status: "closed",
+              mode: "background", duration: 1, model: "m", totalTokens: 0,
+              outcome: "failed",
+            },
+          ],
+        },
+      },
+    });
+    const parsed = JSON.parse(r.content[0]!.text) as {
+      listResponse: { items: Array<Record<string, unknown>> };
+    };
+    const item = parsed.listResponse.items[0]!;
+    expect(item.outcome).toBe("failed");
+    // 旧字段保留（向后兼容）
+    expect(item.status).toBe("closed");
+    expect(item.state).toBe("ended");
+    expect(item.mode).toBe("background");
+    // closedReason 退出对外 JSON
+    expect("closedReason" in item).toBe(false);
+  });
+
+  // [U3 C-outcome] start bgResponse：旧字段保留；outcome 为契约完备位，start 时点
+  // record 未终态恒 undefined（JSON.stringify 落键省略），终态成败经 list items 披露。
+  it("[U3] start bgResponse JSON：status/mode/message 旧字段保留，outcome 起点为 undefined", () => {
+    const r = adapter({
+      action: "start",
+      domain: {
+        kind: "bg", subagentId: "bg-u3-2", sessionFile: undefined, slug: "s",
+        response: { status: "running", mode: "background", message: "detached" },
+      },
+    });
+    const parsed = JSON.parse(r.content[0]!.text) as { bgResponse: Record<string, unknown> };
+    expect(parsed.bgResponse.status).toBe("running");
+    expect(parsed.bgResponse.mode).toBe("background");
+    expect(parsed.bgResponse.message).toBe("detached");
+    expect(parsed.bgResponse.outcome).toBeUndefined();
+  });
+
   it("cancel → cancelResponse.cancelled:true 字面量", () => {
     const r = adapter({ action: "cancel", domain: { subagentId: "bg-1", response: { cancelled: true } } });
     expect(r.details.cancelResponse).toEqual({ cancelled: true });

package/src/execution/agent-registry.ts

@@ -152,7 +152,13 @@ export class AgentRegistry {
    * - ~/ 前缀展开；相对路径/非 .md 引用返回 undefined（引用唯一形态 = 绝对路径）
    * - 文件不可读/不存在 → 驱逐缓存 + 返回 undefined（调用方给错误指引）
    * - mtime 未变复用 config 缓存；cache-miss 时 W4 lint 一次
+   *
+   * require 语义：require:true 时上述两类失败改为 throw（错误文案含
+   * <available_subagents> 恢复指引），供「用户显式点名 agent」的调用点使用——
+   * 显式 ref 失败是配置错误，必须显式报错而非静默降级（三通道对称审查）。
    */
+  loadByPath(ref: string, require: true): AgentConfig;
+  loadByPath(ref: string, require?: boolean): AgentConfig | undefined;
   loadByPath(ref: string, require?: boolean): AgentConfig | undefined {
     const filePath = normalizeRef(ref, AGENT_REF_EXT);
     if (filePath === null) {

package/src/execution/argv-mirror.ts

@@ -86,9 +86,13 @@ export function mirrorMainProcessFlags(argv: readonly string[]): MirrorFlags {
       continue;
     }
     // 空格形式 --extension <path> / -e <path>：值在下一个 token
+    // [MF-7a] flag 判定收窄为 startsWith("--")：守卫原为 !startsWith("-")，把以单个
+    // - 开头的合法路径（如相对路径 -weird-dir/x.md）误判为 flag 跳过——extension 路径
+    // 静默丢失。pi CLI 的多字符长 flag 一律 -- 前缀，单 - 只接单字符短 flag（-e 本身），
+    // 故「-- 开头才算 flag」不误吃真 flag 且放行 - 开头路径。
     if (tok === "--extension" || tok === "-e") {
       const next = flagArgs[i + 1];
-      if (next !== undefined && !next.startsWith("-") && next.length > 0) {
+      if (next !== undefined && !next.startsWith("--") && next.length > 0) {
         extensionPaths.push(next);
         i++; // 跳过值
       }

package/src/execution/concurrency-pool.ts

@@ -63,7 +63,7 @@ export class DefaultConcurrencyPool implements ConcurrencyPool {
       // H2: abort 时 reject 排队条目并从 queue 移除，防止永久挂起
       if (signal) {
         if (signal.aborted) {
-          // S1: abort reject 需带 name="AbortError"，对齐 concurrency-gate.ts 的 AbortError 语义
+          // S1: abort reject 需带 name="AbortError"，对齐包内 AbortError 错误语义约定（消费方按 err.name 判别）
           const err = new Error("acquire aborted");
           err.name = "AbortError";
           reject(err);

package/src/execution/engine/engines/zcode/__tests__/zcode-engine.test.ts

@@ -200,6 +200,19 @@ describe("run ① prepare 期错误：进程创建前 reject、不产生 handle"
       /engine_capability_unsupported/,
     );
   });
+
+  it("maxTurns（pi 专属）→ engine_capability_unsupported，不调 launch（U4：静默丢弃会造成假上限）", async () => {
+    const fake = makeFakeLaunch({ stdout: ZCODE_GOLDEN_STDOUT });
+    const engine = makeEngine({ launch: fake.launch });
+    await expect(engine.run(makeTask({ maxTurns: 10 }), makeCtx())).rejects.toThrowError(
+      /engine_capability_unsupported/,
+    );
+    // 恢复指引：去掉 maxTurns 或改用 pi 引擎
+    await expect(engine.run(makeTask({ maxTurns: 10 }), makeCtx())).rejects.toThrowError(
+      /maxTurns|engine: 'pi'/,
+    );
+    expect(fake.calls).toHaveLength(0);
+  });
 });
 
 describe("run ② 成功路径：golden stdout → outcome/handle/事件合成", () => {

package/src/execution/engine/engines/zcode/zcode-engine.ts

@@ -535,7 +535,10 @@ export class ZcodeEngine implements EnginePort {
   /**
    * prepare 期的能力拒绝（进程创建前）：fork 是 pi 专属（AgentTaskSpec.fork 契约：
    * 其他引擎按 capabilities 拒绝）；conversation 是 interact 控制面的 task 标志，
-   * zcode 无此面（A11：同步拒绝 + 可操作建议，无进程创建）。
+   * zcode 无此面（A11：同步拒绝 + 可操作建议，无进程创建）；maxTurns 是 pi 引擎
+   * 专属（turn limiter + spawn watchdog 估算依赖 pi 的 turn_end 事件流）——zcode
+   * 无 turn_end 语义，静默丢弃会造成「传了上限却失控」的假象，显式拒绝（U4，
+   * 同 fork 模式）。
    */
   private rejectUnsupportedTaskShapes(task: AgentTaskSpec): void {
     if (task.fork === true) {
@@ -551,6 +554,13 @@ export class ZcodeEngine implements EnginePort {
           "恢复指引：改用单次调用（去掉 conversation），或使用 engine: 'pi'。",
       );
     }
+    if (task.maxTurns !== undefined) {
+      throw new ZcodeTaskShapeError(
+        "engine_capability_unsupported",
+        "zcode 引擎不支持 maxTurns（pi 引擎专属 turn limiter；zcode 无 turn_end 语义，无法兑现轮数上限）。" +
+          "恢复指引：去掉 maxTurns 参数重派，或使用 engine: 'pi'。",
+      );
+    }
   }
 
   /**

package/src/execution/engine/types.ts

@@ -89,7 +89,12 @@ export interface AgentTaskSpec {
    * PI_WORKFLOW_SCHEMA env 注入链路按 native 直传，公共仿真层只服务 emulated 引擎。
    */
   schema?: Record<string, unknown>;
-  /** 原样（ExecuteOptions.maxTurns）。 */
+  /**
+   * 原样（ExecuteOptions.maxTurns）。pi 引擎专属（turn limiter + spawn watchdog
+   * 估算依赖 pi 的 turn_end 事件流）；其他引擎 prepare 期显式拒绝（U4，同 fork 模式）。
+   * 显式 0 压过 SPAWN_WATCHDOG_ENV 兑底（SP-6 参数 > env，U5）；undefined 未传才由
+   * env 兑底。
+   */
   maxTurns?: number;
   /** 原样（ExecuteOptions.graceTurns）。 */
   graceTurns?: number;

package/src/execution/execute-options-mapper.ts

@@ -10,13 +10,12 @@ import { HOST_TIMEOUT_ABORT_REASON } from "./engine/common/kill-chain.ts";
 import type { ModelInfo } from "./model-resolver.ts";
 import type { ExecuteOptions } from "./types.ts";
 
-/**
- * slug 最大长度（字符）。subagent/workflow 创建时 slug 超过此值会被截断。
- * subagent/workflow tool schema 的 maxLength 引用此常量（单一真相，勿再硬编码）。
- * 历史值 20 偏紧——描述性 slug 如 "audit-structured-output"（23）/"fix-subagent-wf-tools"（21）
- * 会撞上限，放宽到 35 兼顾「短到能塞进 TUI 标题行」与「容纳合理描述性 kebab-case 名」。
- */
-export const SLUG_MAX_LENGTH = 35;
+// SLUG_MAX_LENGTH 定义已迁至 interface/subagent-tool-schema.ts（与 tool schema 的
+// maxLength 同址，跨包契约测试经该零依赖叶子 import）。此处 re-export 保持既有
+// import 路径（tool-workflow / subagent-actions / error-recovery 等）不变。
+import { SLUG_MAX_LENGTH } from "../interface/subagent-tool-schema.ts";
+
+export { SLUG_MAX_LENGTH };
 
 /**
  * D-A2: AgentCallOpts → ExecuteOptions 映射。
@@ -36,6 +35,7 @@ export const SLUG_MAX_LENGTH = 35;
  *   skillPath       → skillPath
  *   thinkingLevel   → thinkingLevel（M1: 否则下游 subagent-service 读到 undefined）
  *   appendSystemPrompt → appendSystemPrompt（内容数组，同名同义透传）
+ *   maxTurns        → maxTurns（turn limiter 上限；undefined = 不限，不挂 turns 估算 watchdog）
  *
  * 忽略字段（委托后由 executeAndAwait 内部机制替代）：
  *   timeoutMs         —— mergeTimeoutSignal 单独处理
@@ -63,6 +63,7 @@ export function mapToExecuteOptions(
     skillPath: opts.skillPath,
     thinkingLevel: opts.thinkingLevel,
     appendSystemPrompt: opts.appendSystemPrompt,
+    maxTurns: opts.maxTurns,
   };
 }
 

package/src/execution/execution-record.ts

@@ -23,9 +23,11 @@ import type {
   ClosedReason,
   DisplayItem,
   ExecutionMode,
+  ExecutionOutcome,
   ExecutionRecord,
   ExecutionStatus,
   InternalToolCall,
+  ProjectedOutcome,
   RecordSnapshot,
   SubagentToolDetails,
   ToolCall,
@@ -690,7 +692,7 @@ export function markReconstructedStatus(
 }
 
 /**
- * 唯一完成入口。冻结状态（写 endedAt/agentResult/result/error）。
+ * 唯一完成入口。冻结状态（写 endedAt/agentResult/result/error/outcome）。
  * 不修改 turns/totalTokens——已由 updateFromEvent 累积，completeRecord 只读不重置。
  *
  * ⚠ 前置条件：调用方必须先通过 tryTransition 抢到锁（status 已被 CAS 设为 target）。
@@ -706,12 +708,68 @@ export function completeRecord(
 ): void {
   record.status = status;
   record.closedReason = closedReason ?? "gc";
+  // U3 C-outcome：outcome 唯一写入点——终态语义在此一次定形（D6），下游消费方
+  // （project/list/notify 文案/渲染器）只读 record.outcome，不再各自推导。
+  record.outcome = deriveOutcome(record.closedReason, result.error);
   record.endedAt = Date.now();
   record.agentResult = result;
   record.result = result.text;
   record.error = result.error;
 }
 
+// ============================================================
+// 终态 outcome（U3 C-outcome：单一权威派生）
+// ============================================================
+
+/**
+ * closed 终态 → 三态 outcome 的唯一权威派生（D6 收敛：原 notifier/bg-notify-render/
+ * shared deriveClosedDisplay 三处手写同构 switch 的单一实现）。
+ *
+ * 判定顺序（顺序敏感，勿回退成「error 有值即 failed」的无视取消规则）：
+ *   1. closedReason === "cancelled" → "cancelled"（取消优先，不参与 error——abort 合成
+ *      result 可能携带 error，但用户取消语义优先）
+ *   2. error 非空（truthy，与旧三处同构的 `record.error &&` 判定逐字对齐——空串 error
+ *      不构成失败）→ "failed"
+ *   3. 其余 → "completed"
+ *
+ * [D6 待核项保真] 「failed 优先于 patchFile 提示」：失败轮也会写 patchFile
+ * （doFinalizeRecord Step 0 对 worktreeHandle 无条件 collectPatch），消费方必须先按
+ * outcome 分流再渲染 patch 提示——failed 分支不展示 patch/result。历史 bug：notifier
+ * 的 patchFile 分支曾遮蔽 gc+error 判定，失败终态被 LLM 告知 completed（M1 修复存档）。
+ *
+ * [D6 显式取舍] parent-shutdown/parent-fork/parent-new 合成关闭（subagent-service
+ * disposeAllRecords 合成 result 恒写 error:"closed due to ${reason}"）在本映射下落
+ * "failed"——语义为「父进程关闭时子 agent 未完成即失败」，选定行为而非疏漏，
+ * 勿当 bug 改回 cancelled 造成派生矛盾。
+ *
+ * 唯一写点 completeRecord 调用本函数冻结 record.outcome；通知 payload（notifier 投影
+ * 边界）与无 outcome 字段的存量/重建 record 由 projectOutcome 兜底复用本函数。
+ */
+export function deriveOutcome(
+  closedReason: ClosedReason | undefined,
+  error: string | undefined | null,
+): ExecutionOutcome {
+  if (closedReason === "cancelled") return "cancelled";
+  if (error) return "failed";
+  return "completed";
+}
+
+/**
+ * 投影层 outcome 唯一出口：running → undefined（终态语义不适用活跃态）；closed →
+ * 一等 outcome 字段直读优先，字段缺失（存量/磁盘重建 record——outcome 持久化不在
+ * U3 领地内）时回退 deriveOutcome(closedReason, error) 兜底——单一权威函数，
+ * 消费方零手写推导。返回值联合含 "closed-legacy" 预留态，消费方必须处理。
+ */
+export function projectOutcome(record: {
+  status: ExecutionStatus;
+  outcome?: ExecutionOutcome;
+  closedReason?: ClosedReason;
+  error?: string;
+}): ProjectedOutcome | undefined {
+  if (record.status !== "closed") return undefined;
+  return record.outcome ?? deriveOutcome(record.closedReason, record.error);
+}
+
 // ============================================================
 // 投影（唯一 → Details / Snapshot / Persisted）
 // ============================================================
@@ -728,6 +786,7 @@ export function computeElapsedSeconds(record: { startedAt: number; endedAt?: num
 export function project(record: ExecutionRecord): SubagentToolDetails {
   return {
     status: record.status,
+    outcome: projectOutcome(record),
     mode: record.mode,
     agent: record.agent,
     model: record.model,

package/src/execution/lifecycle-manager.ts

@@ -24,6 +24,8 @@
 // 设计参考：session-runner 的 MF-3/MF-4 setTimeout→SIGTERM 骨架（复用 timer 形态，
 // 触发条件重构）；spawnedChildren Map 的模块级单例模式。
 
+import { assertSafeTimerDelay } from "../shared/timer-delay.ts";
+
 // ============================================================
 // 默认常量
 // ============================================================
@@ -97,18 +99,38 @@ const idleTimers = new Map<string, IdleTimerEntry>();
  *
  * 调用时机（接入时由 session-runner 编排）：`agent_settled`（支柱四，真空闲边界）→ arm。
  *
+ * [预算语义对齐] 显式禁用：timeoutMs 传 0/负数 → 不挂 timer 并 disarm 已有的
+ * （idle GC 可被显式关闭，旧实现 0 会落成 setTimeout(0) 立即 kill——危险 footgun）。
+ * 默认行为不变（资源回收性质，默认值保留）：不传 → env XYZ_SUBAGENT_IDLE_TIMEOUT_MS
+ * → DEFAULT_IDLE_TIMEOUT_MS（5min）。env 频道不认识禁用值：非法（<=0）回落默认。
+ *
  * @param recordId subagent record id（sa-<uuid>）
  * @param onTimeout 超时回调（调用方注入：SIGTERM 回收进程）
- * @param timeoutMs 可选。SP-6 优先级：参数 > env XYZ_SUBAGENT_IDLE_TIMEOUT_MS > DEFAULT_IDLE_TIMEOUT_MS。
+ * @param timeoutMs 可选。SP-6 优先级：参数 > env XYZ_SUBAGENT_IDLE_TIMEOUT_MS > DEFAULT_IDLE_TIMEOUT_MS；
+ *   显式 <=0 表示禁用（不挂 timer）。
+ * @throws 解析后的 delay（参数/env/默认任一层）超出 Node setTimeout 上限 2^31-1 ——
+ *   溢出值会被 Node 置 1ms 立即触发（「长空闲保活」变「立即回收」），fail-fast 不静默
+ *   clamp（U1）。
  */
 export function armIdleTimer(
   recordId: string,
   onTimeout: () => void,
   timeoutMs?: number,
 ): void {
+  // 显式禁用通道：参数明确传 0/负数 → 关闭该 record 的 idle GC（顺带清已有 timer，
+  // 否则早前默认 arm 的 timer 仍在跑，禁用形同虚设）。
+  if (timeoutMs !== undefined && timeoutMs <= 0) {
+    disarmIdleTimer(recordId);
+    return;
+  }
+
   // SP-6 优先级：参数 > env XYZ_SUBAGENT_IDLE_TIMEOUT_MS > 默认 300000ms (5min)。
   const resolved = timeoutMs ?? getEnvIdleTimeoutMs() ?? DEFAULT_IDLE_TIMEOUT_MS;
 
+  // [U1] arm 入口：值流入 setTimeout 前校验安全域（>2^31-1 会变 1ms 立即触发）。
+  // 显式 <=0 的禁用通道已在上方 return，不受影响。
+  assertSafeTimerDelay(resolved, "idleTimeoutMs");
+
   // 刷新：先清旧 timer，避免同一 record 叠加多个 armed timer。
   disarmIdleTimer(recordId);
 

package/src/execution/model-config-service.ts

@@ -132,11 +132,26 @@ export class ModelConfigService {
     return resolveModel(config, this.modelRegistry!, override, ctxModel ?? this._ctxModel);
   }
 
-  /** 查询 agent 配置（SubagentService 内部判定 defaultBackground 用）。 */
+  /** 查询 agent 配置（SubagentService 内部判定 defaultBackground 用）。
+   *  undefined = 合法缺省语义（未点名 / 默认 general-purpose 形态）。 */
   getAgentConfig(agentRef?: string): AgentConfig | undefined {
     return agentRef ? this.agentRegistry.loadByPath(agentRef) : undefined;
   }
 
+  /**
+   * 查询 agent 配置——显式 ref 失败即 throw（SubagentService.resolveIdentity 用）。
+   *
+   * 与 getAgentConfig 的语义分界（「用户显式点名」vs「默认 general-purpose」）：
+   * 用户显式点名的 agentRef（工具 agent 参数 / workflow agent({agent}) opts）解析
+   * 失败 = 配置错误，必须显式报错——错误文案含 <available_subagents> 恢复指引
+   * （对齐 workflow name not found 反馈风格），不允许静默降级为无配置
+   * general-purpose 形态（systemPrompt/工具白名单全丢且零反馈）。默认形态
+   * （不传 agent）走 getAgentConfig：undefined = 合法缺省，走 override → ctxModel 兑底。
+   */
+  getRequiredAgentConfig(agentRef: string): AgentConfig {
+    return this.agentRegistry.loadByPath(agentRef, true);
+  }
+
   // ── 配置读取（subagent-service 调）────────────────────────
 
   /** 全局配置深拷贝（调用方拿到副本，改不影响 Service 内部）。 */

package/src/execution/model-resolver.ts

@@ -8,6 +8,21 @@
 // 设计：默认与主 agent 同模型（零配置）。只有「有人显式指定 model」时才查
 // registry 做解析 + 鉴权校验。thinkingLevel 同链路，无指定时 undefined。
 
+// [U1 ModelRef 全等裁决] THINKING_ORDER / ThinkingLevel / strip / 裁决入口收拢到
+// shared/model-ref.ts（单一权威），此处 re-export 保持既有 import 路径不变
+//（subagent-tool / tool-workflow 的 schema 枚举从本模块派生）。
+import {
+  THINKING_ORDER,
+  assertCanonicalModelRef,
+  modelRefFromVerified,
+} from "../shared/model-ref";
+
+export { THINKING_ORDER };
+export type { ThinkingLevel } from "../shared/model-ref";
+
+/** 解析失败时错误信息列出的可用模型上限（防超长错误信息）。 */
+const MODEL_LIST_LIMIT = 20;
+
 /**
  * ModelRegistry 的最小接口（duck-typed，测试可 mock）。
  * 字段结构与 Pi SDK 的 ctx.modelRegistry 对齐。
@@ -66,13 +81,8 @@ export interface ResolvedModel {
 // 常量
 // ============================================================
 
-/** thinking level 支持顺序（低→高），用于 clamp 到 model 可用级别。
- *  SSOT（单一权威源）：新增 thinking 级别只改此处，subagent-tool 的 thinkingLevel 枚举
- *  从本常量派生，避免两处硬编码不同步。 */
-export const THINKING_ORDER = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
-
-/** 解析失败时错误信息列出的可用模型上限（防超长错误信息）。 */
-const MODEL_LIST_LIMIT = 20;
+// MODEL_LIST_LIMIT 与 THINKING_ORDER 随 suggestSimilarModels/lookupModel 一并迁入
+// shared/model-ref.ts（U1 裁决单一入口）。
 
 // ============================================================
 // 解析
@@ -129,7 +139,10 @@ export function resolveModel(
   }
 
   // 3. 主 agent model（直接透传）。无显式 thinking → 兜底最高可用档。
+  // [U1 D2 豁免口径] ctxModel 是运行时已验证的 ModelInfo 对象，豁免 registry 存在性
+  // 复查与 auth 校验；但孪生守卫同等适用（registry 含大小写孪生时拒绝放行，modelRefFromVerified）。
   if (ctxModel) {
+    modelRefFromVerified(ctxModel, modelRegistry);
     return {
       model: ctxModel,
       thinkingLevel: paramOverride?.thinkingLevel ?? agentConfig?.thinkingLevel
@@ -150,9 +163,12 @@ export function resolveModel(
 /**
  * lookup + auth 校验 + thinkingLevel clamp。显式指定但失败 → 抛错（不降级）。
  *
+ * [U1 D1] 模型串裁决经 assertCanonicalModelRef 单一入口（strip 后缀 → provider 精确 →
+ * 全等匹配 → 孪生守卫；未命中同步抛错并附问句式纠错候选）。放行即与 registry 条目全等。
+ *
  * 错误信息区分两种失败（避免误导排查方向）：
- *   - model 不存在 → 提示检查拼写 + 列出相近可用 model
- *   - model 存在但 auth 未配置 → 提示在 models.json 配置鉴权
+ *   - model 非全等（不存在/大小写不符/孪生歧义）→ assertCanonicalModelRef 的问句式报错
+ *   - model 全等命中但 auth 未配置 → 提示在 models.json 配置鉴权
  */
 function lookupAndResolve(
   modelStr: string,
@@ -160,11 +176,14 @@ function lookupAndResolve(
   registry: ModelRegistryLike,
   source: "paramOverride" | "agentConfig",
 ): ResolvedModel {
-  const model = lookupModel(modelStr, registry);
+  const ref = assertCanonicalModelRef(modelStr, registry, { source });
+  const model = registry.find(ref.provider, ref.id);
   if (!model) {
+    // 裁决已按 getAvailable 全等命中；find 独立实现（duck-typed mock 可能不同源）时的
+    // 类型收窄兜底，非预期路径。
     throw new Error(
-      `Model "${modelStr}" (${source}) not found in registry. ` +
-        suggestSimilarModels(modelStr, registry),
+      `Model "${modelStr}" (${source}) passed the canonical ref check but registry.find missed it ` +
+        `(registry snapshot inconsistent). Retry with an exact entry from the available models list.`,
     );
   }
   if (!registry.hasConfiguredAuth(model)) {
@@ -197,53 +216,6 @@ function maxThinkingForModel(
   return model.reasoning ? "xhigh" : undefined;
 }
 
-/**
- * 解析 "provider/modelId" 并查 registry。
- *
- * 容错：剥离尾部 ":thinkingLevel" 后缀（off/minimal/low/medium/high/xhigh）。
- * 原因：LLM 常把平台复合标识 "provider/modelId:thinkingLevel"（如
- * "deepseek-router/ds-pro:xhigh"）整体当 model 参数传入。registry 仅存
- * "provider/modelId"（无后缀），不剥离则 modelId="ds-pro:xhigh" 查不到。
- * 剥离后 thinkingLevel 仍由独立的 thinkingLevel 参数/resolveThinkingLevel 处理。
- *
- * modelId 可含 /，按第一个 / 分割 provider 与 modelId。
- */
-function lookupModel(modelStr: string, registry: ModelRegistryLike): ModelInfo | undefined {
-  const cleanStr = stripThinkingSuffix(modelStr);
-  const idx = cleanStr.indexOf("/");
-  if (idx <= 0) return undefined;
-  return registry.find(cleanStr.slice(0, idx), cleanStr.slice(idx + 1));
-}
-
-/**
- * 剥离模型字符串尾部 ":thinkingLevel" 后缀（如 "ds-pro:xhigh" → "ds-pro"）。
- * 仅匹配合法 thinking level，避免误剥 "foo:bar" 这类无关冒号。
- * 返回去除后缀的字符串；无后缀则原样返回。
- */
-function stripThinkingSuffix(modelStr: string): string {
-  // THINKING_ORDER 含 off/minimal/low/medium/high/xhigh，按长度降序拼正则避免短串误匹配
-  const alt = THINKING_ORDER.slice().sort((a, b) => b.length - a.length).join("|");
-  return modelStr.replace(new RegExp(`:(${alt})$`), "");
-}
-
-/**
- * 为 not-found 错误生成「相近可用 model」建议，辅助定位拼写错误。
- * 策略：取 provider/modelId 的末段，与每个可用 model 的末段做小写包含匹配，
- * 命中则列出。无命中则列出前 N 个全部可用 model（兜底）。空 registry 不列。
- */
-function suggestSimilarModels(modelStr: string, registry: ModelRegistryLike): string {
-  const available = registry.getAvailable();
-  if (available.length === 0) return "Registry has no available models.";
-  const target = modelStr.split("/").pop()?.toLowerCase() ?? "";
-  // ponytail: 末段子串包含足够定位拼写错误，无需编辑距离/相似度库
-  const similar = available
-    .filter((m) => m.id.toLowerCase().includes(target) || target.includes(m.id.toLowerCase()))
-    .map((m) => `${m.provider}/${m.id}`)
-    .slice(0, MODEL_LIST_LIMIT);
-  const list = similar.length > 0 ? similar : available.slice(0, MODEL_LIST_LIMIT).map((m) => `${m.provider}/${m.id}`);
-  return `Check the model string (maybe a typo, or a ":thinkingLevel" suffix that should be passed via the thinkingLevel param instead). Similar available models:\n  ${list.join("\n  ")}`;
-}
-
 /**
  * 从 model.thinkingLevelMap 提取可用级别，clamp 到最高可用。
  * model.reasoning === false → undefined（不支持 thinking）