@carljia/omd-dsh 0.1.2 → 0.1.4

package/README.md

@@ -15,7 +15,14 @@ OMD 理念的 DSH 插件：两个 cordis 行 + 7 个模式 preset + 同步 CLI
 
 机制：监听 system-prompt/assemble（注入 {{provider}}/{{model}} 提示词变量）与 agent/request（next() 后覆盖路由），两处均 prepend，保证覆盖入口的会话级选择。
 
-模型体验：persona 文本每次请求固定携带该模式模型声明；模式模型路由在 agent 生命周期内稳定（KV 前缀稳定）。
+**与 UI 模型切换的优先级**：矩阵模型是模式的默认路由，但用户在 UI 显式切换模型后，本次任务的顶层路由（与 persona 展示）跟随用户选择。判定规则（依据请求瀑布流解析出的入口选择）：
+
+1. 入口选择 == 矩阵模型 → 钉住矩阵模型（无操作）；
+2. 会话尚无任何请求（blank）且入口选择 == 挂载时的部署默认模型 → 视为未选择，钉住矩阵模型；
+3. 会话已跑过请求且刚发生 preset 切换（/mode 或 UI 选择，日志中 agent-preset/selected 在最后一次 request/header 之后）且入口选择 == 切换前的路由 → 新模式认领矩阵模型；
+4. 其余情况 → 入口选择与矩阵模型不同 = 用户显式切换：请求与 persona 变量均保持用户选择，本行在作用域 ctx 上记录 `omdModeOverride`（provider/model），omd-task 行据此把 deep tier 路由到用户选择的模型。
+
+模型体验：persona 文本每次请求固定携带实际路由模型的声明；模式模型路由在 agent 生命周期内稳定（KV 前缀稳定）。
 
 ## 行：omd-task
 
@@ -32,21 +39,23 @@ tier 差异化子代理委派（等价 OMD 的 task(category=…)）。仅限 pr
 
 模型可见参数：description（展示名）、prompt、tier（枚举见工具描述）、run_in_background（仅 continuable 模式）。工具描述枚举各 tier 的 hint 与模型，模型据此选型。
 
+**deep tier 与用户模型覆盖**：用户在 UI 显式切换模型后（omd-mode 让路并记录 `ctx.omdModeOverride`），名为 `deep` 的 tier 改用用户选择的模型（provider/model 整体替换），其余 tier 保持矩阵配置。
+
 ## CLI：omd-dsh
 
 ```
 omd-dsh <command> [--harness <路径>] [--dry-run]
 ```
 
-- `omd-dsh sync` — 把 presets/ 与 vendored 行模块同步到 `<DSH_HOME>/.agent-presets/`（hash 保护、orphan 报告、非管理目录零操作）。每个 preset 的 omd-mode / omd-task 行由 `omd-matrix.json` 渲染。
-- `omd-dsh setup` — 交互式向导：先读取 DSH 已有模型，再引导逐模式/逐 tier 选择模型，写回 `omd-matrix.json` 并可选立即同步。
+- `omd-dsh sync` — 把 presets/ 与 vendored 行模块同步到 `<DSH_HOME>/.agent-presets/`（hash 保护、orphan 报告、非管理目录零操作）。每个 preset 的 omd-mode / omd-task 行由用户矩阵 `<DSH_HOME>/omd-matrix.json` 渲染。
+- `omd-dsh setup` — 交互式向导：先读取 DSH 已有模型，再引导逐模式/逐 tier 选择模型，写回 `<DSH_HOME>/omd-matrix.json` 并可选立即同步。
 - `omd-dsh models` — 打印发现的 DSH 模型目录（非交互）。
 
 细节见 docs/ARCHITECTURE.md 的「vendored 分发与跨树符号风险」。
 
-## 集中配置：omd-matrix.json
+## 集中配置：<DSH_HOME>/omd-matrix.json
 
-所有模式的模型路由（provider/model/reasoningEffort）与 omd_task 各 tier 的模型集中在一个 `omd-matrix.json` 里：`omd-dsh setup` 生成/更新它，`omd-dsh sync` 读取它并渲染进各 preset。preset 里 `# [omd-dsh:mode:start] / [omd-dsh:mode:end]` 与 `# [omd-dsh:task:start] / [omd-dsh:task:end]` 之间的区域是自动生成的——改模型请改矩阵后跑 sync，不要手改 fence 之间的内容。
+所有模式的模型路由（provider/model/reasoningEffort）与 omd_task 各 tier 的模型集中在用户矩阵 `<DSH_HOME>/omd-matrix.json`（默认 `~/.dsh/omd-matrix.json`）：`omd-dsh sync` 首次运行把随包的 deepseek 默认矩阵 `omd-matrix.default.json` 复制为默认配置（或从旧版本包内位置迁移一次），`omd-dsh setup` 更新它，`omd-dsh sync` 读取它并渲染进各 preset。仓库与 npm 包只携带默认矩阵文件，**不含任何个人模型配置**——个人模型配置只留在本机。preset 里 `# [omd-dsh:mode:start] / [omd-dsh:mode:end]` 与 `# [omd-dsh:task:start] / [omd-dsh:task:end]` 之间的区域是自动生成的——改模型请改矩阵后跑 sync，不要手改 fence 之间的内容。
 
 ## 开发
 
@@ -62,7 +71,8 @@ npm pack        # prepack 自动重建，产出 tgz
 ### 子代理透传语义
 
 omd-mode 对 subagentDepth > 0 的子代理一律透传（不覆盖 provider/model/变量）：
-omd-task 的 tier 模型通过显式 agentOptions 生效；顶层 agent 才被钉到模式模型。
+omd-task 的 tier 模型通过显式 agentOptions 生效；顶层 agent 才被钉到模式模型
+（除非用户显式切换模型——此时顶层跟随用户选择，deep tier 通过 `ctx.omdModeOverride` 同步）。
 这保证「强模型顶层 + tier 差异化子代理」的优先级正确。
 
 ### toolFilter 注意

package/lib/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { promises as fs, existsSync, realpathSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { promises as fs, existsSync, mkdirSync, realpathSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { dirname, join, relative, resolve, basename } from "node:path";
 import { homedir } from "node:os";
@@ -10,25 +10,34 @@ import { createInterface } from "node:readline/promises";
  * omd-dsh CLI
  *
  *   omd-dsh sync    materialize presets into <DSH_HOME>/.agent-presets,
- *                   rendering each preset's omd-mode / omd-task rows from
- *                   omd-matrix.json (the single source for model routing and
- *                   tier delegation).
+ *                   rendering each preset's omd-mode / omd-task rows from the
+ *                   user's model matrix at <DSH_HOME>/omd-matrix.json. On
+ *                   first run the shipped deepseek default matrix
+ *                   (omd-matrix.default.json) is copied there; personal
+ *                   model settings stay on the user's machine and are never
+ *                   shipped or uploaded.
  *   omd-dsh setup   interactive wizard: discover the models DSH already has,
  *                   then guide per-mode and per-tier model selection.
  *   omd-dsh models  print the discovered model catalog (non-interactive).
  *
  * Distribution model (vendored + harness-anchored imports) is unchanged from
  * the original omd-dsh sync: presets/omd-* are copied into .agent-presets/;
- * their omd-mode/omd-task rows reference ../.omd-vendor/omd-mode.mjs /
- * omd-task.mjs by relative path; the vendored modules are copied into
- * .agent-presets/.omd-vendor/ with bare @deepseek-ai/* imports rewritten to
- * absolute file:// URLs into the harness node_modules tree.
+ * their omd-mode / omd-task / omd-plan / omd-start-work / omd-mode-switch
+ * rows reference ../.omd-vendor/*.mjs by relative path; the vendored modules
+ * are copied into .agent-presets/.omd-vendor/ with bare @deepseek-ai/*
+ * imports rewritten to absolute file:// URLs into the harness node_modules
+ * tree.
  */
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-const VENDOR_SOURCES = ["omd-mode.mjs", "omd-task.mjs", "omd-ulw.mjs"];
-const MATRIX_PATH = join(PACKAGE_ROOT, "omd-matrix.json");
+const VENDOR_SOURCES = ["omd-mode.mjs", "omd-task.mjs", "omd-ulw.mjs", "omd-plan.mjs", "omd-start-work.mjs", "omd-mode-switch.mjs"];
+/** User-owned model matrix: lives under DSH_HOME, never inside the package or the repo. */
+const MATRIX_PATH = join(dshHome(), "omd-matrix.json");
+/** Pre-migration location (package root) — migrated to MATRIX_PATH once when present. */
+const LEGACY_MATRIX_PATH = join(PACKAGE_ROOT, "omd-matrix.json");
 const MODE_FENCE = { start: "# [omd-dsh:mode:start]", end: "# [omd-dsh:mode:end]" };
 const TASK_FENCE = { start: "# [omd-dsh:task:start]", end: "# [omd-dsh:task:end]" };
+/** Presets that were renamed: old directory name -> new preset name. */
+const RENAMED_FROM = { "omd-architect": "omd-ultraworker" };
 function usage() {
     return [
         "omd-dsh <command> [options]",
@@ -251,15 +260,66 @@ async function collectSourceFiles(rootDir) {
     return out;
 }
 // ── matrix ──
-function loadMatrix() {
-    if (!existsSync(MATRIX_PATH))
-        throw new Error("omd-dsh: missing " + MATRIX_PATH + " (run `omd-dsh setup` to create it, or restore it from source control)");
-    const parsed = JSON.parse(readFileSync(MATRIX_PATH, "utf8"));
-    if (parsed === null || typeof parsed !== "object" || parsed.modes === null || typeof parsed.modes !== "object")
-        throw new Error("omd-dsh: malformed " + MATRIX_PATH);
+/**
+ * The shipped default matrix (deepseek models) copied to
+ * <DSH_HOME>/omd-matrix.json on first run. The repo and the npm package
+ * ship ONLY this defaults file — personal model settings live exclusively
+ * in the user's <DSH_HOME>/omd-matrix.json and are never uploaded.
+ */
+const DEFAULT_MATRIX_PATH = join(PACKAGE_ROOT, "omd-matrix.default.json");
+/** Parse matrix text; undefined when it is not a usable matrix document. */
+function parseMatrix(text) {
+    try {
+        const parsed = JSON.parse(text);
+        if (parsed !== null && typeof parsed === "object" && parsed.modes !== null && typeof parsed.modes === "object")
+            return parsed;
+    }
+    catch { /* fall through */ }
+    return undefined;
+}
+/** Read the shipped default matrix, failing loud when the package is broken. */
+function readDefaultMatrix() {
+    if (!existsSync(DEFAULT_MATRIX_PATH))
+        throw new Error("omd-dsh: missing default matrix file " + DEFAULT_MATRIX_PATH + " (broken package — reinstall @carljia/omd-dsh)");
+    const parsed = parseMatrix(readFileSync(DEFAULT_MATRIX_PATH, "utf8"));
+    if (parsed === undefined)
+        throw new Error("omd-dsh: malformed default matrix file " + DEFAULT_MATRIX_PATH + " (broken package — reinstall @carljia/omd-dsh)");
+    return parsed;
+}
+/** Write a matrix file, creating its parent directory when needed. */
+function writeMatrixFile(path, text) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, text, "utf8");
+}
+/**
+ * Load the user's model matrix from <DSH_HOME>/omd-matrix.json, creating it
+ * on first run: a still-valid package-root matrix (previous versions) is
+ * migrated over, otherwise the shipped deepseek default matrix is written.
+ * Dry runs never touch the filesystem and use the shipped defaults in memory.
+ */
+function loadMatrix(flags) {
+    if (!existsSync(MATRIX_PATH)) {
+        if (flags.dryRun)
+            return JSON.parse(JSON.stringify(readDefaultMatrix()));
+        const legacyText = existsSync(LEGACY_MATRIX_PATH) ? readFileSync(LEGACY_MATRIX_PATH, "utf8") : undefined;
+        if (legacyText !== undefined && parseMatrix(legacyText) !== undefined) {
+            writeMatrixFile(MATRIX_PATH, legacyText);
+            console.log("omd-dsh: migrated omd-matrix.json: " + LEGACY_MATRIX_PATH + " -> " + MATRIX_PATH);
+            console.log("omd-dsh: customize the model matrix any time with `omd-dsh setup`.");
+        }
+        else {
+            const defaults = readDefaultMatrix();
+            writeMatrixFile(MATRIX_PATH, JSON.stringify(defaults, null, 2) + "\n");
+            console.log("omd-dsh: generated " + MATRIX_PATH + " from the shipped deepseek default matrix; customize it any time with `omd-dsh setup`.");
+        }
+    }
+    const text = readFileSync(MATRIX_PATH, "utf8");
+    const parsed = parseMatrix(text);
+    if (parsed === undefined)
+        throw new Error("omd-dsh: malformed " + MATRIX_PATH + " (restore it, or delete it and run omd-dsh setup)");
     return parsed;
 }
-function saveMatrix(m) { writeFileSync(MATRIX_PATH, JSON.stringify(m, null, 2) + "\n", "utf8"); }
+function saveMatrix(m) { writeMatrixFile(MATRIX_PATH, JSON.stringify(m, null, 2) + "\n"); }
 // ── row rendering (relative indents; the splice prepends the fence indent) ──
 function q(s) { return JSON.stringify(s); }
 function renderModeRow(modeId, cfg) {
@@ -370,14 +430,14 @@ function discoverModels() {
 }
 // ── sync ──
 async function runSync(flags, harnessNodeModules) {
-    const matrix = loadMatrix();
+    const matrix = loadMatrix(flags);
     const manifest = JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.json"), "utf8"));
     const sourceVersion = manifest.version;
     const presetsSourceDir = join(PACKAGE_ROOT, "presets");
     const vendorSourceDir = join(PACKAGE_ROOT, "lib", "vendor");
     const agentPresetsRoot = join(dshHome(), ".agent-presets");
     const presetNames = (await fs.readdir(presetsSourceDir, { withFileTypes: true })).filter((e) => e.isDirectory()).map((e) => e.name);
-    const report = { synced: [], updated: [], conflicts: [], skipped: [], orphan: [] };
+    const report = { synced: [], updated: [], conflicts: [], skipped: [], orphan: [], removed: [] };
     const log = (kind, text) => report[kind].push(text);
     for (const presetName of presetNames) {
         const modeId = presetName.replace(/^omd-/, "");
@@ -488,19 +548,67 @@ async function runSync(flags, harnessNodeModules) {
                 continue;
             if (presetNames.includes(entry.name))
                 continue;
-            if (readMeta(join(agentPresetsRoot, entry.name)) !== undefined)
+            const orphanDir = join(agentPresetsRoot, entry.name);
+            const meta = readMeta(orphanDir);
+            if (meta === undefined)
+                continue;
+            const renamedTo = RENAMED_FROM[entry.name];
+            if (renamedTo !== undefined && presetNames.includes(renamedTo)) {
+                const dirty = await locallyModified(orphanDir, meta);
+                if (dirty === undefined) {
+                    if (!flags.dryRun)
+                        await fs.rm(orphanDir, { recursive: true, force: true });
+                    log("removed", entry.name + "/ (renamed to " + renamedTo + " and unmodified -- removed" + (flags.dryRun ? ", dry-run" : "") + ")");
+                }
+                else {
+                    log("conflicts", entry.name + "/ (renamed to " + renamedTo + " but locally modified -- keeping your version: " + dirty + ")");
+                }
+            }
+            else {
                 log("orphan", entry.name + "/ (was installed by omd-dsh but no longer ships with v" + sourceVersion + " -- left untouched)");
+            }
         }
     }
     console.log("omd-dsh sync: DSH_HOME=" + dshHome());
+    console.log("omd-dsh sync: matrix=" + MATRIX_PATH + " (customize the model matrix any time with `omd-dsh setup`)");
     console.log("omd-dsh sync: harness node_modules=" + harnessNodeModules);
     console.log("omd-dsh sync: source version=" + sourceVersion + (flags.dryRun ? " (dry-run)" : ""));
-    for (const key of ["synced", "updated", "skipped", "conflicts", "orphan"])
+    for (const key of ["synced", "updated", "skipped", "conflicts", "orphan", "removed"])
         for (const line of report[key])
             console.log("  [" + key + "] " + line);
-    const summary = ["synced", "updated", "conflicts", "orphan"].map((key) => report[key].length + " " + key).join(", ");
+    const summary = ["synced", "updated", "conflicts", "orphan", "removed"].map((key) => report[key].length + " " + key).join(", ");
     console.log("omd-dsh sync: " + summary + (flags.dryRun ? " (dry-run)" : ""));
 }
+/**
+ * Whether one omd-dsh-managed preset directory differs from the hashes its
+ * .omd-meta.json recorded. Returns a description of the first discrepancy,
+ * or undefined when every recorded file is present and unmodified and no
+ * extra files exist.
+ */
+async function locallyModified(dir, meta) {
+    const recorded = meta.files ?? {};
+    const current = {};
+    const walk = async (d) => {
+        for (const entry of await fs.readdir(d, { withFileTypes: true })) {
+            const full = join(d, entry.name);
+            if (entry.isDirectory())
+                await walk(full);
+            else if (entry.name !== ".omd-meta.json") {
+                const rel = relative(dir, full).split("\\").join("/");
+                current[rel] = sha256(await fs.readFile(full, "utf8"));
+            }
+        }
+    };
+    await walk(dir);
+    for (const rel of new Set([...Object.keys(recorded), ...Object.keys(current)])) {
+        if (current[rel] === undefined)
+            return "missing file " + rel;
+        const recordedHash = recorded[rel] !== undefined && typeof recorded[rel] === "object" && recorded[rel] !== null ? recorded[rel].sha256 : undefined;
+        if (typeof recordedHash !== "string" || recordedHash !== current[rel])
+            return "modified file " + rel;
+    }
+    return undefined;
+}
 // ── setup (interactive) ──
 function splitModel(answer) {
     const a = answer.trim();
@@ -511,7 +619,7 @@ function splitModel(answer) {
     return { provider: "deepseek-official", model: a };
 }
 async function runSetup(flags, harnessNodeModules) {
-    const matrix = loadMatrix();
+    const matrix = loadMatrix(flags);
     const { models, currentDefault } = discoverModels();
     console.log("omd-dsh setup: 发现 DSH 已有模型：");
     for (const m of models)
@@ -521,7 +629,7 @@ async function runSetup(flags, harnessNodeModules) {
     console.log("");
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     const ask = async (question) => (await rl.question(question)).trim();
-    const modeOrder = ["executor", "architect", "planner", "reviewer", "explorer", "librarian", "chat"];
+    const modeOrder = ["executor", "ultraworker", "planner", "reviewer", "explorer", "librarian", "chat"];
     for (const modeId of modeOrder) {
         const cfg = matrix.modes[modeId] ?? {};
         const cur = cfg.provider && cfg.model ? cfg.provider + "/" + cfg.model : "";

package/lib/index.d.ts

@@ -9,9 +9,28 @@
  * model and provider template variables), and overrides provider/model
  * on the agent/request waterfall after next(), dropping any inherited
  * reasoningEffort. Both listeners register with prepend: true so this
- * row sits OUTSIDE the entry point per-session selection listener and
- * its override wins deterministically -- that is the mechanism behind
- * "each mode pins its own model".
+ * row sits OUTSIDE the entry point per-session selection listener.
+ *
+ * Precedence vs. the UI model switch: the matrix model is the preset's
+ * DEFAULT route, but an explicit user selection wins for the task.
+ * The entry selection (installModelSelection) is invisible to this row
+ * (it is owned by the host entry point), so the decision is derived
+ * from what the waterfall actually resolved:
+ *
+ *   - entry selection == matrix model            -> pin (no-op);
+ *   - entry selection missing                    -> pin (claim the mode);
+ *   - session still blank (no request/header)
+ *     and entry selection == the deployment
+ *     default captured at mount                  -> pin (fallback, no pick);
+ *   - a preset switch (agent-preset/selected)
+ *     happened after the last request/header and
+ *     entry selection == the route the session
+ *     was running before the switch              -> pin (new mode claims);
+ *   - otherwise the user explicitly picked a
+ *     different model                            -> yield: the request and
+ *       the persona variables keep the user's selection, and the row
+ *       records it on the scoped context as `omdModeOverride` so the
+ *       omd-task row can route the "deep" tier to the user's model.
  *
  * When provider/model are not configured the row passes everything
  * through and only serves the persona banner variables (inheriting the

package/lib/index.js

@@ -11,9 +11,28 @@ import { scopeOf } from "@deepseek-ai/dsh-scope";
  * model and provider template variables), and overrides provider/model
  * on the agent/request waterfall after next(), dropping any inherited
  * reasoningEffort. Both listeners register with prepend: true so this
- * row sits OUTSIDE the entry point per-session selection listener and
- * its override wins deterministically -- that is the mechanism behind
- * "each mode pins its own model".
+ * row sits OUTSIDE the entry point per-session selection listener.
+ *
+ * Precedence vs. the UI model switch: the matrix model is the preset's
+ * DEFAULT route, but an explicit user selection wins for the task.
+ * The entry selection (installModelSelection) is invisible to this row
+ * (it is owned by the host entry point), so the decision is derived
+ * from what the waterfall actually resolved:
+ *
+ *   - entry selection == matrix model            -> pin (no-op);
+ *   - entry selection missing                    -> pin (claim the mode);
+ *   - session still blank (no request/header)
+ *     and entry selection == the deployment
+ *     default captured at mount                  -> pin (fallback, no pick);
+ *   - a preset switch (agent-preset/selected)
+ *     happened after the last request/header and
+ *     entry selection == the route the session
+ *     was running before the switch              -> pin (new mode claims);
+ *   - otherwise the user explicitly picked a
+ *     different model                            -> yield: the request and
+ *       the persona variables keep the user's selection, and the row
+ *       records it on the scoped context as `omdModeOverride` so the
+ *       omd-task row can route the "deep" tier to the user's model.
  *
  * When provider/model are not configured the row passes everything
  * through and only serves the persona banner variables (inheriting the
@@ -30,6 +49,36 @@ const Config = z.object({
     model: z.string(),
     reasoningEffort: z.string(),
 });
+/**
+ * 子代理（subagentDepth > 0）透传：omd-task 的 tier 模型通过显式 agentOptions
+ * 落到子代理的 AgentOptions 上，本行若再覆盖会压回模式模型、破坏差异化委派。
+ * 无显式 agentOptions 的子代理按 DSH 原生语义继承父级入口选择。
+ */
+function isSubagent(agent) {
+    return agent !== undefined && agent !== null && agent.options !== undefined && agent.options !== null
+        && typeof agent.options.subagentDepth === "number" && agent.options.subagentDepth > 0;
+}
+/**
+ * 最近一次 request/header 之后是否发生过 agent-preset/selected（UI 预设选择或 /mode 切换）。
+ * 切换事件由 api-proxy 与 omd-mode-switch 在 recompose 完成之后追加，因此必须每次实时计算——
+ * 本行挂载时事件尚未入日志，挂载时快照会漏判。
+ */
+function presetSwitchedAfterLastRequest(session) {
+    const events = session === undefined || session === null ? undefined : session.events;
+    if (events === undefined)
+        return false;
+    let lastHeader = -1;
+    let lastSwitch = -1;
+    for (const event of events) {
+        if (event === undefined || event === null || typeof event.seq !== "number")
+            continue;
+        if (event.type === "request/header")
+            lastHeader = event.seq;
+        else if (event.type === "agent-preset/selected")
+            lastSwitch = event.seq;
+    }
+    return lastSwitch > lastHeader;
+}
 function apply(ctx, config) {
     if (scopeOf(ctx) === undefined) {
         throw new Error("omd-mode: refusing to mount outside a scoped context (mode '" + config.mode + "'). " +
@@ -41,42 +90,94 @@ function apply(ctx, config) {
             model: config.model,
         }
         : undefined;
-    // 子代理（subagentDepth > 0）透传：omd-task 的 tier 模型通过显式 agentOptions
-    // 落到子代理的 AgentOptions 上，本行若再覆盖会压回模式模型、破坏差异化委派。
-    // 无显式 agentOptions 的子代理按 DSH 原生语义继承父级入口选择。
-    const isSubagent = (agent) => agent !== undefined && agent !== null && agent.options !== undefined && agent.options !== null
-        && typeof agent.options.subagentDepth === "number" && agent.options.subagentDepth > 0;
     if (config.reasoningEffort !== undefined && pinned !== undefined) {
         pinned.reasoningEffort = config.reasoningEffort;
     }
+    // 挂载时快照部署默认模型（d0）。blank 会话的入口选择 == d0 视为「未显式选择」。
+    // 必须静态快照：session.selectModel 每次都会把用户选择写回全局默认，动态读取会把
+    // 用户选择误判为默认值。
+    let d0;
+    try {
+        const def = ctx.get("agentDefaultModel");
+        const current = def !== undefined && def !== null ? def.currentSelection() : undefined;
+        if (current !== undefined && current !== null && typeof current.provider === "string" && typeof current.model === "string") {
+            d0 = { provider: current.provider, model: current.model };
+        }
+    }
+    catch { /* 读不到默认时退化为仅 entry == pinned 判定 */ }
+    // 供同 preset 内的 omd-task 行读取：用户显式切换模型后（本行让路），deep tier 沿用用户选择。
+    ctx.omdModeOverride = undefined;
+    /**
+     * 判定一次入口选择是否应钉到模式模型（true），还是让路给用户选择（false）。
+     * @param agent - 顶层 agent（子代理已由调用方过滤）。
+     * @param entry - 入口选择 { provider, model }；provider/model 缺失 = 无入口选择。
+     */
+    function shouldPin(agent, entry) {
+        if (pinned === undefined)
+            return false;
+        if (entry === undefined || entry.provider === undefined || entry.model === undefined)
+            return true;
+        if (entry.provider === pinned.provider && entry.model === pinned.model)
+            return true;
+        const session = agent !== undefined && agent !== null ? agent.session : undefined;
+        const logged = session === undefined ? undefined : session.requestHeader();
+        if (logged === undefined) {
+            // 会话尚无任何请求：入口选择要么是部署默认（未选择），要么是首请求前的显式选择。
+            // 只有默认值视为「未选择」；其余一律视为用户选择。
+            if (d0 !== undefined && entry.provider === d0.provider && entry.model === d0.model)
+                return true;
+            return false;
+        }
+        // 会话已跑过请求：刚切换 preset（/mode 或 UI 选择）时，切换前的路由（logged）是
+        // 新模式认领矩阵模型的基线；否则入口选择与模式模型不同 = 用户显式切换，让路。
+        if (presetSwitchedAfterLastRequest(session)
+            && logged.config !== undefined && logged.config !== null
+            && entry.provider === logged.config.provider && entry.model === logged.config.model) {
+            return true;
+        }
+        return false;
+    }
     ctx.on("system-prompt/assemble", async (assembly, _context, next) => {
         const assembled = await next();
-        if (pinned === undefined || isSubagent(_context && _context.agent))
+        const agent = _context && _context.agent;
+        if (pinned === undefined || isSubagent(agent))
             return assembled;
-        return {
-            ...assembled,
-            variables: {
-                ...assembled.variables,
-                provider: pinned.provider,
-                model: pinned.model,
-            },
-        };
+        const variables = assembled.variables ?? {};
+        if (shouldPin(agent, { provider: variables.provider, model: variables.model })) {
+            return {
+                ...assembled,
+                variables: {
+                    ...variables,
+                    provider: pinned.provider,
+                    model: pinned.model,
+                },
+            };
+        }
+        // 让路：保留入口（用户）选择注入的变量，persona 展示实际路由的模型。
+        return assembled;
     }, { prepend: true });
     ctx.on("agent/request", async (_payload, next) => {
         const resolved = await next();
-        if (pinned === undefined || isSubagent(_payload && _payload.agent))
+        const agent = _payload && _payload.agent;
+        if (pinned === undefined || isSubagent(agent))
             return resolved;
-        const stripped = { ...resolved };
-        delete stripped.reasoningEffort;
-        const out = {
-            ...stripped,
-            provider: pinned.provider,
-            model: pinned.model,
-        };
-        if (pinned.reasoningEffort !== undefined) {
-            out.reasoningEffort = pinned.reasoningEffort;
+        if (shouldPin(agent, { provider: resolved.provider, model: resolved.model })) {
+            ctx.omdModeOverride = undefined;
+            const stripped = { ...resolved };
+            delete stripped.reasoningEffort;
+            const out = {
+                ...stripped,
+                provider: pinned.provider,
+                model: pinned.model,
+            };
+            if (pinned.reasoningEffort !== undefined) {
+                out.reasoningEffort = pinned.reasoningEffort;
+            }
+            return out;
         }
-        return out;
+        // 用户显式选择了别的模型：本次任务顶层路由用用户选择；deep tier 同步（omd-task 读取）。
+        ctx.omdModeOverride = { provider: resolved.provider, model: resolved.model };
+        return resolved;
     }, { prepend: true });
 }
 export { Config, apply, inject, name };

package/lib/mode.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @module @carljia/omd-dsh/mode
+ *
+ * omd-mode-switch: human-facing `/mode` command -- switch the CURRENT
+ * session to another OMD agent preset, including mid-conversation.
+ *
+ * DSH's native `agentPreset.select` host API refuses to recompose a
+ * session that has already started (its preset is fixed at the UI level),
+ * and the AgentPresets.recompose method itself performs no history check
+ * ("the CALLER owns that check"). This row deliberately performs the
+ * in-session recompose, then keeps the log honest:
+ *   - appends `agent-preset/selected`, so resume/fork rebuild the same
+ *     composition ("model-visible <-> logged" rule);
+ *   - appends `plan/mode { active: false }` when plan mode is still
+ *     active, since the switch itself is a mode decision;
+ *   - steers a notice message so the model knows the tool set changed.
+ *
+ * Mitigations for the swapped tool catalog: the omd-planner catalog is a
+ * subset of omd-executor's (the executor preset also mounts the plan-mode
+ * row), so logged planner tool calls stay renderable under the executor
+ * composition. Switching between other omd presets follows the same rule
+ * and the model simply receives the new catalog on the next request.
+ */
+/** Cordis plugin name. */
+declare const name = "omd-mode-switch";
+/**
+ * No mount-time injection: the roster service is resolved at runtime so a
+ * rosterless deployment fails only the /mode command, never the preset
+ * mount itself.
+ */
+declare const inject: never[];
+declare function apply(ctx: any): void;
+export { apply, inject, name };