dsh-deeptutor 0.1.10 → 0.2.0

package/lib/index.js

@@ -1,9 +1,8 @@
 import { defineTool } from "@deepseek-ai/dsh-tools";
 import { CAPABILITIES, configGuide, configHint, SSH_HOST, truncate } from "./config.js";
 import { cliNoteLocal, cliNoteRemote, runCli } from "./cli-exec.js";
-import { apiJson, ensureApi, killTunnel } from "./http-api.js";
 import { renderHtml } from "./html-render.js";
-import { cliRunTurn, fmtTurnResult, wsRunTurn } from "./turn.js";
+import { cliRunTurn, fmtTurnResult } from "./turn.js";
 import { HTML_DOC_SCRIPT } from "./html-render.js";
 export const name = "dsh-deeptutor";
 export const inject = ["tools"];
@@ -16,10 +15,6 @@ function json(o) {
 }
 export function apply(ctx) {
     console.log(`[dsh-deeptutor] plugin loaded (html script: ${HTML_DOC_SCRIPT})`);
-    // Kill the SSH tunnel process when the plugin unloads.
-    ctx.effect(() => {
-        return () => killTunnel();
-    });
     // ---------- Tool 1: run a DeepTutor learning capability ----------
     ctx.tools.register(defineTool({
         name: "deeptutor_run",
@@ -94,27 +89,6 @@ export function apply(ctx) {
         async execute(args, exec) {
             const timeoutMs = (args.timeout ?? 600) * 1000;
             const maxChars = args.max_chars ?? 30000;
-            try {
-                if (await ensureApi()) {
-                    const r = await wsRunTurn(args, timeoutMs, exec.signal);
-                    const htmlNote = await renderHtml(args, r.answer);
-                    return json({
-                        mode: "http",
-                        sessionId: r.sessionId,
-                        toolCalls: r.toolCalls,
-                        errors: r.errors,
-                        text: configHint() + fmtTurnResult(args.capability, r, maxChars) + htmlNote,
-                    });
-                }
-            }
-            catch (err) {
-                if (exec.signal.aborted) {
-                    // user cancelled mid-flight: don't start a fresh CLI run behind their back
-                    throw new Error("[deeptutor_run cancelled]");
-                }
-                console.log(`[deeptutor] HTTP/WS failed, falling back to CLI: ${err?.message}`);
-            }
-            // fallback: local/SSH CLI
             try {
                 const r = await cliRunTurn(args, timeoutMs, exec.signal);
                 const htmlNote = await renderHtml(args, r.answer);
@@ -132,7 +106,7 @@ export function apply(ctx) {
                     throw new Error("[deeptutor_run cancelled]");
                 }
                 throw new Error(configGuide() +
-                    `[deeptutor_run failed (HTTP and CLI both unavailable)] ${err?.message ?? String(err)}`);
+                    `[deeptutor_run failed] ${err?.message ?? String(err)}`);
             }
         },
     }));
@@ -185,41 +159,7 @@ export function apply(ctx) {
         },
         async execute(args, exec) {
             const maxChars = args.max_chars ?? 30000;
-            // search goes through the CLI (REST has no dedicated search route);
-            // list/info prefer HTTP, fall back to CLI
-            if (args.action !== "search") {
-                try {
-                    if (await ensureApi()) {
-                        if (args.action === "list") {
-                            const arr = await apiJson("/api/v1/knowledge/list", undefined, {
-                                signal: exec.signal,
-                            });
-                            const body = Array.isArray(arr)
-                                ? arr
-                                    .map((kb) => `- ${kb.name} (status=${kb.status ?? "?"}, ${kb.statistics ? JSON.stringify(kb.statistics) : "no stats"}${kb.is_default ? ", default" : ""})`)
-                                    .join("\n")
-                                : JSON.stringify(arr);
-                            return json({
-                                action: "list",
-                                mode: "http",
-                                text: configHint() +
-                                    `Knowledge bases (${Array.isArray(arr) ? arr.length : "?"}):\n${body}`,
-                            });
-                        }
-                        const kb = await apiJson(`/api/v1/knowledge/${encodeURIComponent(args.kb ?? "")}`, undefined, { signal: exec.signal });
-                        return json({
-                            action: "info",
-                            mode: "http",
-                            kb: args.kb,
-                            text: truncate(JSON.stringify(kb, null, 2), maxChars),
-                        });
-                    }
-                }
-                catch (err) {
-                    console.log(`[deeptutor] kb ${args.action} HTTP failed, falling back to CLI: ${err?.message}`);
-                }
-            }
-            // CLI fallback (local or SSH). NOTE: `kb search` has no --top-k flag
+            // Local or SSH CLI. NOTE: `kb search` has no --top-k flag
             // (verified on deeptutor CLI 1.5.x); top_k is applied locally below.
             let argv;
             if (args.action === "list") {
@@ -337,53 +277,7 @@ export function apply(ctx) {
         async execute(args, exec) {
             const recordType = (args.type ?? "chat");
             const nbName = args.notebook.trim();
-            // HTTP first
-            try {
-                if (await ensureApi()) {
-                    const list = await apiJson("/api/v1/notebook/list", undefined, {
-                        signal: exec.signal,
-                    });
-                    const notebooks = list?.notebooks ?? [];
-                    let nb = notebooks.find((n) => n.name?.trim() === nbName);
-                    if (!nb) {
-                        const created = await apiJson("/api/v1/notebook/create", {
-                            method: "POST",
-                            headers: { "Content-Type": "application/json" },
-                            body: JSON.stringify({
-                                name: nbName,
-                                description: `Archived by dsh agent (${new Date().toISOString().slice(0, 10)})`,
-                            }),
-                        }, { signal: exec.signal });
-                        nb = created?.notebook ?? created;
-                    }
-                    const nbId = nb?.id ?? (typeof nb === "string" ? nb : undefined);
-                    if (!nbId)
-                        throw new Error("cannot resolve notebook id");
-                    const added = await apiJson("/api/v1/notebook/add_record", {
-                        method: "POST",
-                        headers: { "Content-Type": "application/json" },
-                        body: JSON.stringify({
-                            notebook_ids: [nbId],
-                            record_type: recordType,
-                            title: args.title,
-                            user_query: args.title,
-                            output: args.content,
-                        }),
-                    }, { signal: exec.signal });
-                    return json({
-                        notebook: nbName,
-                        nbId: String(nbId),
-                        title: args.title,
-                        mode: "http",
-                        text: configHint() +
-                            `[note archived (HTTP)] notebook=${nbName} (${nbId}), title=${args.title}, type=${recordType}\n${truncate(JSON.stringify(added ?? {}), 800)}`,
-                    });
-                }
-            }
-            catch (err) {
-                console.log(`[deeptutor] note HTTP failed, falling back to CLI: ${err?.message}`);
-            }
-            // CLI fallback: remote deployment uses the remote PY_NOTE script; local deployment runs locally
+            // Remote deployment runs the PY_NOTE script on the server; local deployment runs locally
             const { stdout, stderr, code } = SSH_HOST
                 ? await cliNoteRemote(nbName, args.title, recordType, args.content, exec.signal)
                 : await cliNoteLocal(nbName, args.title, recordType, args.content, exec.signal);
@@ -396,7 +290,7 @@ export function apply(ctx) {
                 title: args.title,
                 mode: "cli",
                 text: configHint() +
-                    `[note archived (CLI)] notebook=${nbName}, title=${args.title}, type=${recordType}\n${truncate((stdout ?? "").trim(), 2000)}`,
+                    `[note archived] notebook=${nbName}, title=${args.title}, type=${recordType}\n${truncate((stdout ?? "").trim(), 2000)}`,
             });
         },
     }));

package/lib/turn.d.ts

@@ -6,7 +6,7 @@ export interface TurnResult {
     sessionId?: string;
     title?: string;
 }
-/** Fields both wsRunTurn and cliRunTurn read off the deeptutor_run tool params. */
+/** Fields cliRunTurn reads off the deeptutor_run tool params. */
 export interface RunParams {
     prompt: string;
     capability: string;
@@ -16,10 +16,8 @@ export interface RunParams {
     language?: string;
     config?: Record<string, unknown>;
 }
-/** Fold one event (WS or CLI JSONL) into the running turn state. Exported for unit tests. */
+/** Fold one CLI JSONL event into the running turn state. Exported for unit tests. */
 export declare function collectEvent(state: TurnResult, e: any): void;
-/** Execute one turn over WebSocket (streaming). */
-export declare function wsRunTurn(params: RunParams, timeoutMs: number, signal?: AbortSignal): Promise<TurnResult>;
 /**
  * Build the `deeptutor run` argv for a capability turn (pure, unit-tested).
  * Scalar config values go as repeatable --config k=v; object/array values are

package/lib/turn.js

@@ -1,10 +1,10 @@
 /**
- * DeepTutor bridge: one learning "turn" — running a capability over WebSocket (HTTP mode)
- * or the CLI (fallback), and shared JSONL/WS event parsing + result formatting.
+ * DeepTutor bridge: one learning "turn" — running a capability through the deeptutor CLI
+ * (local or over SSH), JSONL event parsing and result formatting.
  */
-import { API_BASE, truncate } from "./config.js";
+import { truncate } from "./config.js";
 import { runCli } from "./cli-exec.js";
-/** Fold one event (WS or CLI JSONL) into the running turn state. Exported for unit tests. */
+/** Fold one CLI JSONL event into the running turn state. Exported for unit tests. */
 export function collectEvent(state, e) {
     if (e.type === "content" && typeof e.content === "string")
         state.answer += e.content;
@@ -19,97 +19,6 @@ export function collectEvent(state, e) {
     if (!state.sessionId && typeof e.session_id === "string")
         state.sessionId = e.session_id;
 }
-/** Execute one turn over WebSocket (streaming). */
-export function wsRunTurn(params, timeoutMs, signal) {
-    return new Promise((resolve, reject) => {
-        if (signal?.aborted)
-            return reject(new Error("Aborted"));
-        const WSImpl = globalThis.WebSocket;
-        if (!WSImpl)
-            return reject(new Error("WebSocket is not available in this environment"));
-        const ws = new WSImpl(`${API_BASE.replace(/^http/, "ws")}/api/v1/ws`);
-        let settled = false;
-        const state = { answer: "", errors: [], toolCalls: [] };
-        let timer;
-        const finish = (fn) => {
-            if (settled)
-                return;
-            settled = true;
-            if (timer)
-                clearTimeout(timer);
-            signal?.removeEventListener("abort", onAbort);
-            fn();
-        };
-        timer = setTimeout(() => {
-            finish(() => {
-                try {
-                    ws.close();
-                }
-                catch { }
-                reject(new Error(`WebSocket timeout (${Math.round(timeoutMs / 1000)}s)`));
-            });
-        }, timeoutMs);
-        const onAbort = () => {
-            finish(() => {
-                try {
-                    ws.close();
-                }
-                catch { }
-                reject(new Error("Aborted"));
-            });
-        };
-        signal?.addEventListener("abort", onAbort, { once: true });
-        ws.onopen = () => {
-            ws.send(JSON.stringify({
-                type: "start_turn",
-                content: params.prompt,
-                capability: params.capability,
-                session_id: params.session_id ?? null,
-                tools: params.tools ?? [],
-                knowledge_bases: params.kbs ?? [],
-                language: params.language ?? "en",
-                config: params.config ?? {},
-                notebook_references: [],
-                history_references: [],
-                attachments: [],
-                skills: [],
-            }));
-        };
-        ws.onmessage = (ev) => {
-            let e;
-            try {
-                e = JSON.parse(ev.data);
-            }
-            catch {
-                return;
-            }
-            collectEvent(state, e);
-            if (e.type === "done") {
-                finish(() => {
-                    try {
-                        ws.close();
-                    }
-                    catch { }
-                    resolve(state);
-                });
-            }
-        };
-        ws.onerror = () => {
-            finish(() => {
-                try {
-                    ws.close();
-                }
-                catch { }
-                reject(new Error("WebSocket connection error (server not running or tunnel down)"));
-            });
-        };
-        ws.onclose = () => {
-            finish(() => {
-                reject(new Error("WebSocket closed unexpectedly"));
-            });
-        };
-    });
-}
 /**
  * Build the `deeptutor run` argv for a capability turn (pure, unit-tested).
  * Scalar config values go as repeatable --config k=v; object/array values are

package/lib/win-cmd.d.ts

@@ -0,0 +1,27 @@
+export interface LocalCommand {
+    file: string;
+    args: string[];
+    /** Pass the args to CreateProcess unchanged (needed for the cmd.exe command line). */
+    windowsVerbatimArguments?: boolean;
+    /** Set when the command cannot be run as requested; nothing should be spawned. */
+    error?: string;
+}
+/** Quote one argument for a cmd.exe command line (cross-spawn's escapeArgument). */
+export declare function escapeCmdArgument(arg: string, doubleEscapeMetaChars: boolean): string;
+/** Escape the command path itself for a cmd.exe command line. */
+export declare function escapeCmdCommand(command: string): string;
+/**
+ * Build the `cmd.exe /d /s /c "..."` invocation for a batch file. Arguments are escaped
+ * twice because a batch file that forwards `%*` makes cmd.exe parse them a second time.
+ */
+export declare function buildCmdInvocation(batchFile: string, args: string[], comSpec?: string): LocalCommand;
+/**
+ * If a .cmd/.bat wrapper does nothing but forward its arguments to an executable, return
+ * that executable's path. Accepts `@echo off`, `rem`/`::` comments and `setlocal`/`endlocal`
+ * around a single `["]<path>.exe["] %*` line; `%~dp0` is expanded to the wrapper's folder.
+ */
+export declare function parseCmdWrapper(text: string, wrapperPath: string): string | undefined;
+/** Find a bare command name on PATH, trying each PATHEXT extension (Windows search order). */
+export declare function findOnPath(name: string, env?: NodeJS.ProcessEnv, exists?: (p: string) => boolean): string | undefined;
+/** Turn a local CLI path plus argv into something execFile can start on this platform. */
+export declare function resolveLocalCommand(file: string, args: string[], platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv): LocalCommand;

package/lib/win-cmd.js

@@ -0,0 +1,108 @@
+/**
+ * DeepTutor bridge: launching the local deeptutor CLI on Windows.
+ *
+ * Node's execFile cannot start a .cmd/.bat file directly on Windows (spawn EINVAL, see
+ * issue #8), and it does not search PATHEXT for a bare command name. resolveLocalCommand
+ * turns DEEPTUTOR_LOCAL_BIN into something execFile can run:
+ *   1. a bare name is looked up on PATH using PATHEXT;
+ *   2. a .cmd/.bat that only forwards its arguments to an .exe (`"C:\...\deeptutor.exe" %*`)
+ *      is replaced by that .exe, so no shell is involved;
+ *   3. any other .cmd/.bat runs through `cmd.exe /d /s /c` with every argument quoted and
+ *      its metacharacters escaped (the same scheme as cross-spawn).
+ * cmd.exe ends a command line at a newline, so case 3 cannot pass multi-line arguments;
+ * resolveLocalCommand reports that instead of silently truncating the prompt.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { extname, win32 } from "node:path";
+const META_CHARS = /([()\][%!^"`<>&|;, *?])/g;
+/** Quote one argument for a cmd.exe command line (cross-spawn's escapeArgument). */
+export function escapeCmdArgument(arg, doubleEscapeMetaChars) {
+    let out = arg.replace(/(\\*)"/g, '$1$1\\"');
+    out = out.replace(/(\\*)$/, "$1$1");
+    out = `"${out}"`;
+    out = out.replace(META_CHARS, "^$1");
+    if (doubleEscapeMetaChars)
+        out = out.replace(META_CHARS, "^$1");
+    return out;
+}
+/** Escape the command path itself for a cmd.exe command line. */
+export function escapeCmdCommand(command) {
+    return command.replace(META_CHARS, "^$1");
+}
+/**
+ * Build the `cmd.exe /d /s /c "..."` invocation for a batch file. Arguments are escaped
+ * twice because a batch file that forwards `%*` makes cmd.exe parse them a second time.
+ */
+export function buildCmdInvocation(batchFile, args, comSpec = "cmd.exe") {
+    const line = [escapeCmdCommand(batchFile), ...args.map((a) => escapeCmdArgument(a, true))].join(" ");
+    return { file: comSpec, args: ["/d", "/s", "/c", `"${line}"`], windowsVerbatimArguments: true };
+}
+/**
+ * If a .cmd/.bat wrapper does nothing but forward its arguments to an executable, return
+ * that executable's path. Accepts `@echo off`, `rem`/`::` comments and `setlocal`/`endlocal`
+ * around a single `["]<path>.exe["] %*` line; `%~dp0` is expanded to the wrapper's folder.
+ */
+export function parseCmdWrapper(text, wrapperPath) {
+    const lines = text
+        .split(/\r?\n/)
+        .map((l) => l.trim())
+        .filter((l) => l !== "" &&
+        !/^@?echo\s+off$/i.test(l) &&
+        !/^@?(rem(\s|$)|::)/i.test(l) &&
+        !/^@?(setlocal|endlocal)(\s|$)/i.test(l));
+    if (lines.length !== 1)
+        return undefined;
+    const m = /^@?(?:"([^"]+\.(?:exe|com))"|([^\s"]+\.(?:exe|com)))\s+%\*$/i.exec(lines[0]);
+    if (!m)
+        return undefined;
+    // Windows path rules regardless of the host, so this also behaves the same in Linux CI.
+    const dir = win32.dirname(wrapperPath);
+    const target = (m[1] ?? m[2]).replace(/%~dp0/gi, dir + "\\");
+    if (/%/.test(target))
+        return undefined; // other variables: let cmd.exe expand them
+    return win32.resolve(dir, target);
+}
+/** Find a bare command name on PATH, trying each PATHEXT extension (Windows search order). */
+export function findOnPath(name, env = process.env, exists = existsSync) {
+    const exts = (env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean);
+    // Windows path rules regardless of the host, so this also behaves the same in Linux CI.
+    const dirs = (env.PATH ?? env.Path ?? "").split(win32.delimiter).filter(Boolean);
+    for (const dir of dirs) {
+        for (const ext of exts) {
+            const candidate = win32.join(dir.replace(/^"|"$/g, ""), name + ext.toLowerCase());
+            if (exists(candidate))
+                return candidate;
+        }
+    }
+    return undefined;
+}
+/** Turn a local CLI path plus argv into something execFile can start on this platform. */
+export function resolveLocalCommand(file, args, platform = process.platform, env = process.env) {
+    if (platform !== "win32")
+        return { file, args };
+    let target = file;
+    const isBareName = !/[\\/]/.test(target) && extname(target) === "";
+    if (isBareName)
+        target = findOnPath(target, env) ?? target;
+    if (!/\.(cmd|bat)$/i.test(target))
+        return { file: target, args };
+    let wrapped;
+    try {
+        wrapped = parseCmdWrapper(readFileSync(target, "utf8"), target);
+    }
+    catch {
+        wrapped = undefined;
+    }
+    if (wrapped && existsSync(wrapped))
+        return { file: wrapped, args };
+    if (args.some((a) => /[\r\n]/.test(a))) {
+        return {
+            file: target,
+            args,
+            error: `${target} is a batch file, and cmd.exe cannot pass arguments that contain line breaks. ` +
+                "Point DEEPTUTOR_LOCAL_BIN at deeptutor.exe instead (in a pip/venv install it is " +
+                "<venv>\\Scripts\\deeptutor.exe).",
+        };
+    }
+    return buildCmdInvocation(target, args, env.ComSpec ?? env.COMSPEC ?? "cmd.exe");
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-deeptutor",
-  "version": "0.1.10",
-  "description": "Learning assistant extension for DeepSeek Harness (dsh): DeepTutor tutoring for your agent — deep explanations, self-test questions, learning paths, personal knowledge-base search (RAG), and note archiving (HTTP/WS first, CLI fallback; auto-adapts local/remote deployment).",
+  "version": "0.2.0",
+  "description": "Learning assistant extension for DeepSeek Harness (dsh): DeepTutor tutoring for your agent — deep explanations, self-test questions, learning paths, personal knowledge-base search (RAG), and note archiving (drives the DeepTutor CLI locally or over SSH).",
   "keywords": [
     "dsh",
     "dsh-plugin",
@@ -22,7 +22,7 @@
   },
   "engines": {
     "node": ">=20.11",
-    "dsh": "^0.1.0-rc.6 || ^0.2.0-rc.1"
+    "dsh": ">=0.1.0-rc.6"
   },
   "type": "module",
   "main": "./lib/index.js",
@@ -65,7 +65,7 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6 || ^0.2.0-rc.1 || ^0.2.1-rc.1"
+    "@deepseek-ai/dsh-tools": ">=0.1.0-rc.6"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.5",

package/scripts/check-dsh-compat.mjs

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+/**
+ * Boot-verify dsh-deeptutor against the `dsh` on PATH.
+ *
+ * Why this exists: the manifest no longer caps the supported dsh line (that is
+ * what issue #5 was about), so the compatibility gate is replaced by this
+ * probe. The scheduled `dsh-compat` workflow runs it against the npm `latest`
+ * and `next` releases; run it by hand after a dsh upgrade as well.
+ *
+ * What it does, against a throwaway DSH_HOME:
+ *   1. packs this repository (prepack builds + typechecks) unless --spec is given;
+ *   2. installs the package into a fresh `compat` profile;
+ *   3. cold-boots that profile with a dead model endpoint;
+ *   4. asserts the plugin activated (no `did not activate` / import failure).
+ *
+ * Usage:
+ *   node scripts/check-dsh-compat.mjs [--spec <dir|tarball|npm-spec>] [--timeout 60]
+ *                                     [--dsh-bin dsh] [--json] [--keep-workspace]
+ *
+ * Exit codes: 0 = the plugin activated, 1 = it did not, 2 = inconclusive.
+ * The probe only reads and writes inside its own temporary DSH_HOME.
+ */
+import { spawnSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = resolve(fileURLToPath(new URL("..", import.meta.url)));
+const argv = process.argv.slice(2);
+
+function option(name, fallback) {
+  const index = argv.indexOf(name);
+  return index >= 0 && index + 1 < argv.length ? argv[index + 1] : fallback;
+}
+
+const dshBin = option("--dsh-bin", process.platform === "win32" ? "dsh.cmd" : "dsh");
+const npmBin = process.platform === "win32" ? "npm.cmd" : "npm";
+const timeoutSeconds = Number(option("--timeout", "60"));
+const jsonOutput = argv.includes("--json");
+const keepWorkspace = argv.includes("--keep-workspace");
+const specArgument = option("--spec", undefined);
+
+const PROFILE = "compat";
+const FAILURE = /did not activate|failed to import|plugin tree failed to load|Cannot find module|ERR_MODULE_NOT_FOUND/i;
+const ACTIVATED = /\[dsh-deeptutor\] plugin loaded/;
+
+function run(command, args, options = {}) {
+  return spawnSync(command, args, {
+    encoding: "utf8",
+    timeout: (options.timeoutSeconds ?? 180) * 1000,
+    killSignal: "SIGKILL",
+    input: "",
+    cwd: options.cwd ?? repoRoot,
+    env: { ...process.env, ...(options.env ?? {}) },
+  });
+}
+
+function tail(text, lines = 25) {
+  return String(text ?? "")
+    .trimEnd()
+    .split("\n")
+    .slice(-lines)
+    .join("\n");
+}
+
+/** The model/patch layer the boot probe needs: a real model name behind a dead port. */
+function writeProbePatch(profileDir) {
+  mkdirSync(profileDir, { recursive: true });
+  writeFileSync(
+    join(profileDir, "cordis.patch.yml"),
+    [
+      "# generated by scripts/check-dsh-compat.mjs — real model name behind a dead endpoint",
+      "- id: llm-compat",
+      "  config:",
+      "    models:",
+      "      - id: Qwen3.6-35B",
+      "        contextWindow: 262144",
+      "        maxTokens: 8192",
+      "- id: agent-default-model",
+      "  config:",
+      "    provider: deepseek-official",
+      "    model: Qwen3.6-35B",
+      "- id: \"@deepseek-ai/cordis-plugin-hmr\"",
+      "  disabled: true",
+      "",
+    ].join("\n"),
+  );
+}
+
+function main() {
+  const dshVersionProbe = run(dshBin, ["--version"], { timeoutSeconds: 30 });
+  if (dshVersionProbe.error !== undefined || dshVersionProbe.status !== 0) {
+    return {
+      verdict: "inconclusive",
+      stage: "dsh-version",
+      detail: `${dshBin} is not runnable: ${String(dshVersionProbe.error ?? dshVersionProbe.stderr)}`.trim(),
+      exitCode: 2,
+    };
+  }
+  const dshVersion = String(dshVersionProbe.stdout ?? "").trim().split("\n").pop() ?? "unknown";
+
+  const workspace = mkdtempSync(join(tmpdir(), "dsh-compat-"));
+  const dshHome = join(workspace, ".dsh");
+  const env = { DSH_HOME: dshHome };
+  const cleanup = () => {
+    if (!keepWorkspace) rmSync(workspace, { recursive: true, force: true });
+  };
+
+  try {
+    let spec = specArgument;
+    if (spec === undefined) {
+      // --cache: keep npm state inside the probe workspace, so a read-only or
+      // root-owned npm cache on the caller's machine cannot fail the probe.
+      const packed = run(npmBin, ["pack", "--pack-destination", workspace, "--cache", join(workspace, "npm-cache")], { timeoutSeconds: 300 });
+      if (packed.status !== 0) {
+        return { verdict: "inconclusive", stage: "pack", detail: tail(`${packed.stdout}\n${packed.stderr}`), exitCode: 2 };
+      }
+      const tarball = readdirSync(workspace).find((name) => name.endsWith(".tgz"));
+      if (tarball === undefined) {
+        return { verdict: "inconclusive", stage: "pack", detail: "npm pack produced no tarball", exitCode: 2 };
+      }
+      spec = join(workspace, tarball);
+    }
+
+    writeProbePatch(join(dshHome, "profiles", PROFILE));
+
+    // `-w`: dsh profiles are single-package pnpm workspaces and pnpm refuses
+    // to add to a workspace root without it (observed on pnpm 9 + dsh 0.2.1).
+    // Isolated pnpm store: a machine-wide store (store-dir in ~/.npmrc) can be
+    // read-only for this user, which would look like an install failure.
+    const install = run(
+      dshBin,
+      ["plugin", "--profile", PROFILE, "add", "-w", `--store-dir=${join(workspace, "pnpm-store")}`, spec],
+      { timeoutSeconds: 300, env },
+    );
+    if (install.status !== 0) {
+      return {
+        verdict: "fail",
+        stage: "install",
+        detail: tail(`${install.stdout}\n${install.stderr}`),
+        exitCode: 1,
+      };
+    }
+
+    const boot = run(dshBin, ["--profile", PROFILE, "ok"], {
+      timeoutSeconds,
+      env: {
+        ...env,
+        DEEPSEEK_BASE_URL: "http://127.0.0.1:9",
+        DEEPSEEK_API_KEY: "sk-compat-probe-000000000000000000000000",
+        DSH_PERMISSION_MODE: "danger-full-access",
+      },
+      cwd: dshHome,
+    });
+    const log = `${boot.stdout ?? ""}\n${boot.stderr ?? ""}`;
+    const timedOut = boot.error?.code === "ETIMEDOUT";
+    const failure = log.match(FAILURE);
+    if (failure !== null) {
+      return { verdict: "fail", stage: "boot", detail: tail(log), signature: failure[0], exitCode: 1 };
+    }
+    if (log.match(ACTIVATED) !== null) {
+      return { verdict: "pass", stage: "boot", detail: "plugin activation marker seen", exitCode: 0 };
+    }
+    if (timedOut) {
+      return { verdict: "pass", stage: "boot", detail: "boot stayed alive through the probe window without a failure signature", exitCode: 0 };
+    }
+    return { verdict: "inconclusive", stage: "boot", detail: tail(log), exitCode: 2 };
+  } finally {
+    cleanup();
+  }
+}
+
+const result = main();
+const versionProbe = run(dshBin, ["--version"], { timeoutSeconds: 30 });
+const report = {
+  dshBin,
+  dshVersion: String(versionProbe.stdout ?? "").trim().split("\n").pop() ?? "unavailable",
+  spec: specArgument ?? "(packed from the repository)",
+  ...result,
+};
+
+if (jsonOutput) {
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+} else {
+  const label = report.verdict === "pass" ? "PASS" : report.verdict === "fail" ? "FAIL" : "INCONCLUSIVE";
+  process.stdout.write(`[dsh-compat] ${label} · dsh ${report.dshVersion} · stage ${report.stage}\n`);
+  if (report.detail !== undefined && report.detail !== "") process.stdout.write(`${report.detail}\n`);
+  if (keepWorkspace) process.stdout.write(`[dsh-compat] workspace kept\n`);
+}
+process.exit(report.exitCode);