@carljia/omd-dsh 0.1.1 → 0.1.3

package/README.md

@@ -38,15 +38,15 @@ tier 差异化子代理委派（等价 OMD 的 task(category=…)）。仅限 pr
 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 之间的内容。
 
 ## 开发
 

package/lib/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { promises as fs, existsSync, realpathSync, readFileSync, 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]",
@@ -37,7 +46,7 @@ function usage() {
         "    setup    interactive: discover DSH models, then guide per-mode/tier model selection",
         "    models   print the discovered DSH model catalog",
         "  options:",
-        "    --harness <path>  node_modules dir of the DSH harness install (auto-detected via the dsh executable)",
+        "    --harness <path>  node_modules dir of the DSH harness install (saved locally after first use; otherwise auto-detected)",
         "    --dry-run         (sync) print planned writes without touching the filesystem",
         "    --verbose         (sync) print per-file detail",
     ].join("\n");
@@ -55,6 +64,60 @@ function findNodeModules(start) {
         current = parent;
     }
 }
+function harnessCachePath() { return join(dshHome(), "omd-dsh-harness.json"); }
+/** Read the cached harness node_modules, ignoring a stale/missing entry. */
+function readCachedHarness() {
+    try {
+        const p = harnessCachePath();
+        if (!existsSync(p))
+            return undefined;
+        const parsed = JSON.parse(readFileSync(p, "utf8"));
+        const nm = parsed && typeof parsed === "object" ? parsed.harnessNodeModules : undefined;
+        if (typeof nm !== "string" || nm === "")
+            return undefined;
+        if (!existsSync(join(nm, "@deepseek-ai", "dsh-scope", "package.json")))
+            return undefined;
+        return nm;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Persist the resolved harness node_modules for later runs (best-effort). */
+function writeCachedHarness(harnessNodeModules) {
+    try {
+        writeFileSync(harnessCachePath(), JSON.stringify({ harnessNodeModules }, null, 2) + "\n", "utf8");
+    }
+    catch { /* best-effort */ }
+}
+/**
+ * Resolve the DSH harness node_modules:
+ *   1. --harness flag (and cache it for later);
+ *   2. auto-detect via the dsh executable on PATH;
+ *   3. fall back to the locally cached value.
+ */
+function resolveHarness(flags) {
+    let nm;
+    if (flags.harness !== undefined) {
+        nm = findNodeModules(flags.harness);
+        if (nm !== undefined) {
+            try {
+                nm = realpathSync(nm);
+                writeCachedHarness(nm);
+            }
+            catch { /* keep nm as-is */ }
+        }
+        return nm;
+    }
+    nm = locateHarnessViaDsh() ?? locateHarnessViaNpxCache() ?? readCachedHarness();
+    if (nm !== undefined) {
+        try {
+            nm = realpathSync(nm);
+        }
+        catch { /* keep */ }
+    }
+    return nm;
+}
 function locateHarnessViaDsh() {
     const candidates = [];
     try {
@@ -79,6 +142,51 @@ function locateHarnessViaDsh() {
     }
     return undefined;
 }
+/** Candidate npx cache roots where a non-global DSH install may live. */
+function npxCacheRoots() {
+    const roots = [];
+    if (process.platform === "win32") {
+        const localAppData = process.env.LOCALAPPDATA;
+        if (localAppData)
+            roots.push(join(localAppData, "npm-cache", "_npx"));
+        const appData = process.env.APPDATA;
+        if (appData)
+            roots.push(join(appData, "npm-cache", "_npx"));
+    }
+    else {
+        roots.push(join(homedir(), ".npm", "_npx"));
+    }
+    return roots;
+}
+/**
+ * Best-effort scan of the npx cache for a DSH install whose node_modules
+ * carries @deepseek-ai/dsh-scope. Picks the most recently touched one.
+ */
+function locateHarnessViaNpxCache() {
+    const matches = [];
+    for (const root of npxCacheRoots()) {
+        let entries;
+        try {
+            entries = readdirSync(root);
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const nm = join(root, entry, "node_modules");
+            if (!existsSync(join(nm, "@deepseek-ai", "dsh-scope", "package.json")))
+                continue;
+            let mtime = 0;
+            try {
+                mtime = statSync(join(root, entry)).mtimeMs;
+            }
+            catch { /* keep 0 */ }
+            matches.push({ nm, mtime });
+        }
+    }
+    matches.sort((a, b) => b.mtime - a.mtime);
+    return matches.length > 0 ? matches[0].nm : undefined;
+}
 function resolveHarnessModule(harnessNodeModules, specifier) {
     const segments = specifier.split("/");
     const scope = segments[0].startsWith("@") ? segments[0] + "/" + segments[1] : segments[0];
@@ -152,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) {
@@ -271,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-/, "");
@@ -389,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();
@@ -412,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)
@@ -422,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 : "";
@@ -451,7 +658,7 @@ async function runSetup(flags, harnessNodeModules) {
     rl.close();
     if (syncNow === "" || /^y/i.test(syncNow)) {
         if (harnessNodeModules === undefined) {
-            console.error("omd-dsh setup: 无法定位 DSH harness node_modules，跳过同步。稍后运行 `omd-dsh sync --harness <路径>`。");
+            console.error("omd-dsh setup: 无法定位 DSH harness node_modules，跳过同步。首次请运行 `omd-dsh sync --harness <路径>`（之后会自动缓存，无需重复指定）。");
         }
         else {
             await runSync(flags, harnessNodeModules);
@@ -501,19 +708,15 @@ async function main() {
         return;
     }
     if (command === "setup") {
-        let harnessNodeModules = flags.harness !== undefined ? findNodeModules(flags.harness) : locateHarnessViaDsh();
-        if (harnessNodeModules !== undefined)
-            harnessNodeModules = realpathSync(harnessNodeModules);
-        await runSetup(flags, harnessNodeModules);
+        await runSetup(flags, resolveHarness(flags));
         return;
     }
-    let harnessNodeModules = flags.harness !== undefined ? findNodeModules(flags.harness) : locateHarnessViaDsh();
+    const harnessNodeModules = resolveHarness(flags);
     if (harnessNodeModules === undefined || !existsSync(join(harnessNodeModules, "@deepseek-ai", "dsh-scope", "package.json"))) {
-        console.error("omd-dsh sync: cannot locate the DSH harness node_modules.\n  - ensure the dsh executable is on PATH, or\n  - pass --harness <path to the harness node_modules directory>.\n\n" + usage());
+        console.error("omd-dsh sync: cannot locate the DSH harness node_modules.\n  - ensure the dsh executable is on PATH, or\n  - pass --harness <path to the harness node_modules directory> (saved for later runs).\n\n" + usage());
         process.exitCode = 2;
         return;
     }
-    harnessNodeModules = realpathSync(harnessNodeModules);
     await runSync(flags, harnessNodeModules);
 }
 main().catch((error) => {

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 };

package/lib/mode.js

@@ -0,0 +1,145 @@
+import { createUserMessage } from "@deepseek-ai/dsh-llm";
+import { scopeOf } from "@deepseek-ai/dsh-scope";
+/**
+ * @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. */
+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.
+ */
+const inject = [];
+/** The OMD presets /mode may switch to. */
+const OMD_PRESET_IDS = [
+    "omd-executor",
+    "omd-ultraworker",
+    "omd-planner",
+    "omd-reviewer",
+    "omd-explorer",
+    "omd-librarian",
+    "omd-chat",
+];
+/** Normalize the command input to a valid omd preset id, or undefined. */
+function normalizeTarget(rawInput) {
+    const trimmed = String(rawInput).trim().toLowerCase();
+    if (trimmed === "")
+        return undefined;
+    const candidate = trimmed.startsWith("omd-") ? trimmed : "omd-" + trimmed;
+    return OMD_PRESET_IDS.includes(candidate) ? candidate : undefined;
+}
+/** Fold the session's plan/mode events (last one wins). */
+function planModeActive(events) {
+    let active = false;
+    for (const event of events ?? []) {
+        if (event !== undefined && event.type === "plan/mode") {
+            active = event.data !== undefined && event.data !== null && event.data.active === true;
+        }
+    }
+    return active;
+}
+/** Execute one /mode invocation through the roster service. */
+async function executeSwitch(ctx, invocation) {
+    const agent = invocation.agent;
+    const target = normalizeTarget(invocation.rawInput);
+    if (target === undefined) {
+        return {
+            kind: "error",
+            text: "Usage: /mode <preset> — valid: " + OMD_PRESET_IDS.join(", "),
+        };
+    }
+    let presets;
+    try {
+        presets = ctx.get("agentPresets");
+    }
+    catch {
+        presets = undefined;
+    }
+    if (presets === undefined || presets === null) {
+        return {
+            kind: "error",
+            text: "/mode is unavailable: this deployment composes no agent presets.",
+        };
+    }
+    let current;
+    try {
+        current = presets.composedPreset(agent.ctx);
+    }
+    catch {
+        current = undefined;
+    }
+    if (current === target) {
+        return { kind: "success", text: "Already running " + target + "." };
+    }
+    try {
+        const preset = await presets.recompose(agent.ctx, target);
+        agent.session.append("agent-preset/selected", { agentPreset: preset.id });
+        if (planModeActive(agent.session.events)) {
+            agent.session.append("plan/mode", { active: false });
+        }
+        agent.steer(createUserMessage({
+            content: [
+                {
+                    type: "text",
+                    text: "The session switched to the " +
+                        preset.id +
+                        " agent preset. Continue in this mode with its tool set, persona, and model routing.",
+                },
+            ],
+            source: {
+                kind: "plugin",
+                plugin: "omd-mode-switch",
+                form: "notice",
+                summary: "Session mode switched to " + preset.id,
+            },
+        }));
+        return {
+            kind: "success",
+            text: "Session preset switched to " + preset.id + " — the next turn runs with that mode's tools and model.",
+        };
+    }
+    catch (error) {
+        return {
+            kind: "error",
+            text: "/mode failed: " + (error instanceof Error ? error.message : String(error)),
+        };
+    }
+}
+function apply(ctx) {
+    if (scopeOf(ctx) === undefined) {
+        throw new Error("omd-mode-switch: refusing to mount outside a scoped context; mount this row inside an agent preset");
+    }
+    ctx.inject(["commands"], (commandCtx) => {
+        commandCtx.commands.register({
+            name: "mode",
+            description: "switch this session to another omd agent preset (tool set + model)",
+            input: {
+                hint: "<omd-* preset id>",
+                images: false,
+            },
+            handler: (invocation) => executeSwitch(ctx, invocation),
+        });
+    });
+}
+export { apply, inject, name };

package/lib/plan.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @module @carljia/omd-dsh/plan
+ *
+ * omd-plan: plan persistence for the OMD planner mode. It wraps the
+ * `tools/post-execute` waterfall and intercepts a successful
+ * `exit_plan_mode` approval: the approved plan text is written into the
+ * workspace's plan directory (a fixed, code-level convention -- never
+ * mentioned in any persona/prompt text), and the tool result content is
+ * enriched with the saved file name so the planner's fixed Start Work
+ * final step can hand it to the user.
+ *
+ * Plan directory convention (hardcoded here and in omd-start-work only):
+ *   <session cwd>/.omd/plans/<slug>-<timestamp>.md
+ * The slug derives from the plan's first markdown heading; a timestamp
+ * suffix keeps repeated interviews from overwriting each other.
+ */
+/** Cordis plugin name. */
+declare const name = "omd-plan";
+/** No service injection: this row only registers a scoped event listener. */
+declare const inject: never[];
+declare function apply(ctx: any): void;
+export { apply, inject, name };