cursor-route 0.1.7 → 0.1.8

package/src/adapters/deepseek.ts

@@ -1,24 +1,158 @@
+import { execSync } from "node:child_process";
+import { existsSync, writeFileSync, unlinkSync } from "node:fs";
 import type { Adapter, WorkerHealth } from "./types.ts";
+import { shellQuote } from "../util.ts";
+import {
+  DS_MODEL_IDS,
+  resolveDsModel,
+  type DsModelAlias,
+} from "../config.ts";
 
 /**
- * Reserved slot for the official DeepSeek coding harness when it ships.
- * Mid lane stays on claude-ds until then — do not route jobs here.
+ * Experimental official DeepSeek Harness (`dsh`, npm @deepseek-ai/dsh) as a
+ * coding worker — `dsh --profile headless` with a per-job Cordis patch that
+ * pins the model. Mid lane stays on claude-ds; this is an opt-in worker only
+ * (`--worker deepseek`), not a mid replacement.
+ *
+ * We never write ~/.dsh/settings.yaml (parallel jobs would race) and never
+ * put DEEPSEEK_API_KEY in the command or patch — the key travels via plan.env.
  */
+
+function findDsh(): string | null {
+  // Env override lets tests pin a fake dsh — but it must exist, so a stale
+  // override cannot pass health with a dangling path.
+  const override = process.env.CURSOR_ROUTE_DSH_BIN;
+  if (override) return existsSync(override) ? override : null;
+  try {
+    return (
+      execSync("command -v dsh", {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+        // Bun may ignore mutated process.env.PATH unless env is passed explicitly
+        env: { ...process.env },
+      }).trim() || null
+    );
+  } catch {
+    return null;
+  }
+}
+
+/** Same resolution as claude-ds: passed model/modelId wins, else env, else Flash. */
+function pickModel(
+  requested?: DsModelAlias,
+  modelId?: string,
+): { alias: DsModelAlias; id: string } {
+  if (modelId) {
+    const alias = requested ?? resolveDsModel(modelId).alias;
+    return { alias, id: modelId };
+  }
+  if (requested) {
+    return { alias: requested, id: DS_MODEL_IDS[requested] };
+  }
+  // Env default (startJob normally resolves this; kept for direct buildLaunch callers)
+  return resolveDsModel(process.env.CURSOR_ROUTE_DS_MODEL || process.env.ANTHROPIC_MODEL);
+}
+
+/** Whitelist model ids before interpolating into YAML (no newlines / injection). */
+function assertPatchModelId(modelId: string): string {
+  if (!/^[a-z0-9][a-z0-9.\-[\]]*$/i.test(modelId)) {
+    throw new Error(`Invalid DeepSeek model id for dsh patch: ${modelId}`);
+  }
+  return modelId;
+}
+
+/** Per-job Cordis patch path. Never reuse the prompt path (would overwrite it). */
+export function patchPathForPrompt(promptFile: string): string {
+  return promptFile.endsWith(".prompt")
+    ? promptFile.replace(/\.prompt$/, ".dsh-patch.yml")
+    : `${promptFile}.dsh-patch.yml`;
+}
+
+/** Per-job Cordis patch (whole-row replace). `name` is required or dsh silently skips. */
+function patchYaml(modelId: string): string {
+  const id = assertPatchModelId(modelId);
+  return [
+    "- id: agent-default-model",
+    "  name: '@deepseek-ai/dsh-agent-default-model'",
+    "  config:",
+    "    provider: deepseek-official",
+    `    model: '${id}'`,
+  ].join("\n") + "\n";
+}
+
 export const deepseekAdapter: Adapter = {
   kind: "deepseek",
-  label: "Official DeepSeek harness (unreleased)",
+  label: "Official DeepSeek Harness (dsh)",
   health(): WorkerHealth {
+    const binary = findDsh();
+    if (!binary) {
+      return {
+        worker: "deepseek",
+        ok: false,
+        binary: null,
+        detail:
+          "dsh (@deepseek-ai/dsh) not found — install: npm i -g @deepseek-ai/dsh. Mid default remains claude-ds.",
+      };
+    }
+    if (!process.env.DEEPSEEK_API_KEY) {
+      return {
+        worker: "deepseek",
+        ok: false,
+        binary,
+        detail:
+          "DEEPSEEK_API_KEY not set — export your DeepSeek API key to use dsh (@deepseek-ai/dsh). Mid default remains claude-ds.",
+      };
+    }
     return {
       worker: "deepseek",
-      ok: false,
-      binary: null,
-      detail:
-        "unreleased — mid lane uses claude-ds (DeepSeek behind Claude Code). See README.",
+      ok: true,
+      binary,
+      detail: "ok (dsh @deepseek-ai/dsh headless; mid default remains claude-ds)",
     };
   },
-  buildLaunch() {
-    throw new Error(
-      "Official DeepSeek harness is not available yet — use --lane mid / --worker claude-ds",
-    );
+  buildLaunch({ promptFile, cwd, alwaysApprove, model, modelId, dryRun }) {
+    // Missing dsh is tolerated here so `--dry-run` can still print the command;
+    // real starts are gated by the health preflight (binary + DEEPSEEK_API_KEY).
+    const binary = findDsh() || "dsh";
+    const choice = pickModel(model, modelId);
+
+    // Per-job patch next to the prompt file (never touch ~/.dsh/settings.yaml).
+    const patchFile = patchPathForPrompt(promptFile);
+    writeFileSync(patchFile, patchYaml(choice.id), { mode: 0o600 });
+    if (dryRun) {
+      // Dry-run keeps no durable artifacts (jobs.ts removes the prompt likewise).
+      try {
+        unlinkSync(patchFile);
+      } catch {
+        /* ignore */
+      }
+    }
+
+    // Launcher flags before the task; prompt inlined via cat (never the key).
+    const parts = [
+      shellQuote(binary),
+      "--profile",
+      "headless",
+      "--patch",
+      shellQuote(patchFile),
+      `"$(cat ${shellQuote(promptFile)})"`,
+    ];
+
+    const ask = process.env.CURSOR_ROUTE_ASK === "1";
+    const skip = alwaysApprove && !ask;
+    const env: Record<string, string> = {
+      DSH_PERMISSION_MODE: skip ? "danger-full-access" : "workspace-write",
+    };
+    // Key travels via env only — never interpolated into command or patch.
+    if (process.env.DEEPSEEK_API_KEY) {
+      env.DEEPSEEK_API_KEY = process.env.DEEPSEEK_API_KEY;
+    }
+
+    return {
+      worker: "deepseek",
+      command: `cd ${shellQuote(cwd)} && ${parts.join(" ")}`,
+      alwaysApprove: skip,
+      env,
+    };
   },
 };

package/src/adapters/types.ts

@@ -24,9 +24,11 @@ export interface Adapter {
     promptFile: string;
     cwd: string;
     alwaysApprove: boolean;
-    /** Mid-lane DeepSeek flash|pro (ignored by other workers / Anthropic escape hatch). */
+    /** Mid-lane DeepSeek flash|pro (claude-ds + deepseek; ignored by grok/openrouter / Anthropic escape hatch). */
     model?: DsModelAlias;
     /** Concrete DeepSeek model id for -Model/--model (preserves pro[1m]). */
     modelId?: string;
+    /** True on --dry-run: adapters may drop artifacts they just wrote (e.g. dsh patch). */
+    dryRun?: boolean;
   }): LaunchPlan;
 }

package/src/cli.test.ts

@@ -1,5 +1,13 @@
 import { describe, expect, test } from "bun:test";
-import { mkdirSync, writeFileSync, chmodSync, rmSync } from "node:fs";
+import {
+  mkdirSync,
+  writeFileSync,
+  chmodSync,
+  rmSync,
+  readFileSync,
+  readdirSync,
+  existsSync,
+} from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { resolveWorker, startJob } from "./jobs.ts";
@@ -8,7 +16,7 @@ import { shellQuote, newJobId } from "./util.ts";
 import { runHealth } from "./health.ts";
 import { looksLikeSecretMaterial, redactSecrets } from "./secrets.ts";
 import { isDeepSeekRouted, isDeepSeekBaseUrl, claudeDsAdapter } from "./adapters/claude-ds.ts";
-import { deepseekAdapter } from "./adapters/deepseek.ts";
+import { deepseekAdapter, patchPathForPrompt } from "./adapters/deepseek.ts";
 import { grokAdapter } from "./adapters/grok.ts";
 
 describe("resolveWorker", () => {
@@ -190,15 +198,56 @@ describe("startJob product path", () => {
     }
   });
 
-  test("--worker deepseek dry-run fails", () => {
-    const result = startJob({
-      prompt: "ping",
-      worker: "deepseek",
-      dryRun: true,
-    });
-    expect(result.ok).toBe(false);
-    if (result.ok) return;
-    expect(result.error).toMatch(/not available|claude-ds/i);
+  test("--worker deepseek dry-run succeeds with fake dsh + key", () => {
+    const dir = join(tmpdir(), `cr-dsh-start-${process.pid}`);
+    mkdirSync(dir, { recursive: true });
+    const bin = join(dir, "dsh");
+    writeFileSync(bin, "#!/bin/sh\necho fake-dsh\n");
+    chmodSync(bin, 0o755);
+    const prev = {
+      bin: process.env.CURSOR_ROUTE_DSH_BIN,
+      key: process.env.DEEPSEEK_API_KEY,
+      ds: process.env.CURSOR_ROUTE_DS_MODEL,
+      am: process.env.ANTHROPIC_MODEL,
+      jobs: process.env.CURSOR_ROUTE_JOBS_DIR,
+    };
+    process.env.CURSOR_ROUTE_DSH_BIN = bin;
+    // Not a real key: short and dash-separated so the CLI refuse gate would not trip.
+    process.env.DEEPSEEK_API_KEY = "sk-test-not-a-real-key";
+    delete process.env.CURSOR_ROUTE_DS_MODEL;
+    delete process.env.ANTHROPIC_MODEL;
+    process.env.CURSOR_ROUTE_JOBS_DIR = join(dir, "jobs");
+    try {
+      const result = startJob({
+        prompt: "ping",
+        worker: "deepseek",
+        dryRun: true,
+      });
+      expect(result.ok).toBe(true);
+      if (!result.ok) return;
+      expect(result.job.worker).toBe("deepseek");
+      expect(result.job.model).toBe("flash");
+      expect(result.command).toContain("--profile headless");
+      expect(result.command).toContain("--patch");
+      expect(result.command).toContain("$(cat");
+      expect(result.command).toContain("DSH_PERMISSION_MODE");
+      expect(result.command).not.toContain("sk-test");
+      expect(result.command).not.toContain("npx");
+      // Dry-run keeps no durable artifacts (prompt + dsh patch both removed)
+      expect(readdirSync(join(dir, "jobs")).length).toBe(0);
+    } finally {
+      if (prev.bin === undefined) delete process.env.CURSOR_ROUTE_DSH_BIN;
+      else process.env.CURSOR_ROUTE_DSH_BIN = prev.bin;
+      if (prev.key === undefined) delete process.env.DEEPSEEK_API_KEY;
+      else process.env.DEEPSEEK_API_KEY = prev.key;
+      if (prev.ds === undefined) delete process.env.CURSOR_ROUTE_DS_MODEL;
+      else process.env.CURSOR_ROUTE_DS_MODEL = prev.ds;
+      if (prev.am === undefined) delete process.env.ANTHROPIC_MODEL;
+      else process.env.ANTHROPIC_MODEL = prev.am;
+      if (prev.jobs === undefined) delete process.env.CURSOR_ROUTE_JOBS_DIR;
+      else process.env.CURSOR_ROUTE_JOBS_DIR = prev.jobs;
+      rmSync(dir, { recursive: true, force: true });
+    }
   });
 
   test("grok command never includes deepseek-v4", () => {
@@ -220,16 +269,287 @@ describe("startJob product path", () => {
   });
 });
 
-describe("deepseek adapter slot", () => {
-  test("health is not ok and buildLaunch throws", () => {
-    expect(deepseekAdapter.health().ok).toBe(false);
-    expect(() =>
-      deepseekAdapter.buildLaunch({
-        promptFile: "/tmp/p",
-        cwd: "/tmp",
-        alwaysApprove: true,
-      }),
-    ).toThrow(/not available/);
+describe("deepseek adapter (dsh)", () => {
+  /** Executable fake `dsh` in a fresh tmpdir (existsSync passes). */
+  const makeFakeDsh = (suffix: string) => {
+    const dir = join(tmpdir(), `cr-dsh-${process.pid}-${suffix}`);
+    mkdirSync(dir, { recursive: true });
+    const bin = join(dir, "dsh");
+    writeFileSync(bin, "#!/bin/sh\necho fake-dsh\n");
+    chmodSync(bin, 0o755);
+    return { dir, bin };
+  };
+
+  /** Set/delete env for the duration of fn; restore afterwards. */
+  const withEnv = (
+    patch: Record<string, string | undefined>,
+    fn: () => void,
+  ) => {
+    const prev = new Map<string, string | undefined>();
+    for (const k of Object.keys(patch)) {
+      prev.set(k, process.env[k]);
+      const v = patch[k];
+      if (v === undefined) delete process.env[k];
+      else process.env[k] = v;
+    }
+    try {
+      fn();
+    } finally {
+      for (const [k, v] of prev) {
+        if (v === undefined) delete process.env[k];
+        else process.env[k] = v;
+      }
+    }
+  };
+
+  test("health: no binary and no key → not ok, install hint names the npm package", () => {
+    withEnv(
+      {
+        CURSOR_ROUTE_DSH_BIN: join(tmpdir(), `missing-dsh-${process.pid}`),
+        DEEPSEEK_API_KEY: undefined,
+      },
+      () => {
+        const h = deepseekAdapter.health();
+        expect(h.ok).toBe(false);
+        expect(h.detail).toMatch(/npm i -g @deepseek-ai\/dsh/);
+      },
+    );
+  });
+
+  test("health: binary but no key → not ok, tells operator to export DEEPSEEK_API_KEY", () => {
+    const { bin } = makeFakeDsh("nokey");
+    withEnv({ CURSOR_ROUTE_DSH_BIN: bin, DEEPSEEK_API_KEY: undefined }, () => {
+      const h = deepseekAdapter.health();
+      expect(h.ok).toBe(false);
+      expect(h.detail).toMatch(/DEEPSEEK_API_KEY/);
+    });
+  });
+
+  test("health: binary + key → ok", () => {
+    const { bin } = makeFakeDsh("ok");
+    withEnv({ CURSOR_ROUTE_DSH_BIN: bin, DEEPSEEK_API_KEY: "test-key" }, () => {
+      const h = deepseekAdapter.health();
+      expect(h.ok).toBe(true);
+      expect(h.binary).toBe(bin);
+    });
+  });
+
+  test("buildLaunch: flash default patch next to prompt; key only in env", () => {
+    const { dir, bin } = makeFakeDsh("flash");
+    const promptFile = join(dir, "job.prompt");
+    writeFileSync(promptFile, "ping");
+    withEnv(
+      {
+        CURSOR_ROUTE_DSH_BIN: bin,
+        DEEPSEEK_API_KEY: "test-key",
+        CURSOR_ROUTE_DS_MODEL: undefined,
+        ANTHROPIC_MODEL: undefined,
+      },
+      () => {
+        const plan = deepseekAdapter.buildLaunch({
+          promptFile,
+          cwd: dir,
+          alwaysApprove: true,
+        });
+        expect(plan.command).toContain("--profile headless");
+        expect(plan.command).toContain("--patch");
+        expect(plan.command).toContain("$(cat");
+        expect(plan.command).not.toContain("npx");
+        expect(plan.command).not.toContain("test-key");
+        expect(plan.env?.DSH_PERMISSION_MODE).toBe("danger-full-access");
+        expect(plan.env?.DEEPSEEK_API_KEY).toBe("test-key");
+        const patch = readFileSync(join(dir, "job.dsh-patch.yml"), "utf8");
+        expect(patch).toContain("agent-default-model");
+        expect(patch).toContain("provider: deepseek-official");
+        expect(patch).toContain("deepseek-v4-flash");
+        expect(patch).not.toContain("deepseek-v4-pro");
+        expect(patch).not.toContain("test-key");
+      },
+    );
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("buildLaunch: pro model → deepseek-v4-pro in patch", () => {
+    const { dir, bin } = makeFakeDsh("pro");
+    const promptFile = join(dir, "job.prompt");
+    writeFileSync(promptFile, "ping");
+    withEnv(
+      {
+        CURSOR_ROUTE_DSH_BIN: bin,
+        DEEPSEEK_API_KEY: "test-key",
+        CURSOR_ROUTE_DS_MODEL: undefined,
+        ANTHROPIC_MODEL: undefined,
+      },
+      () => {
+        deepseekAdapter.buildLaunch({
+          promptFile,
+          cwd: dir,
+          alwaysApprove: true,
+          model: "pro",
+        });
+        const patch = readFileSync(join(dir, "job.dsh-patch.yml"), "utf8");
+        expect(patch).toContain("deepseek-v4-pro");
+        expect(patch).not.toContain("deepseek-v4-flash");
+      },
+    );
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("buildLaunch: preserves deepseek-v4-pro[1m] in patch via modelId", () => {
+    const { dir, bin } = makeFakeDsh("pro1m");
+    const promptFile = join(dir, "job.prompt");
+    writeFileSync(promptFile, "ping");
+    withEnv(
+      {
+        CURSOR_ROUTE_DSH_BIN: bin,
+        DEEPSEEK_API_KEY: "test-key",
+        CURSOR_ROUTE_DS_MODEL: undefined,
+        ANTHROPIC_MODEL: undefined,
+      },
+      () => {
+        deepseekAdapter.buildLaunch({
+          promptFile,
+          cwd: dir,
+          alwaysApprove: true,
+          model: "pro",
+          modelId: "deepseek-v4-pro[1m]",
+        });
+        const patch = readFileSync(join(dir, "job.dsh-patch.yml"), "utf8");
+        expect(patch).toContain("deepseek-v4-pro[1m]");
+      },
+    );
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("buildLaunch: alwaysApprove false (--ask) → workspace-write", () => {
+    const { dir, bin } = makeFakeDsh("ask");
+    const promptFile = join(dir, "job.prompt");
+    writeFileSync(promptFile, "ping");
+    withEnv(
+      {
+        CURSOR_ROUTE_DSH_BIN: bin,
+        DEEPSEEK_API_KEY: "test-key",
+        CURSOR_ROUTE_DS_MODEL: undefined,
+        ANTHROPIC_MODEL: undefined,
+      },
+      () => {
+        const plan = deepseekAdapter.buildLaunch({
+          promptFile,
+          cwd: dir,
+          alwaysApprove: false,
+        });
+        expect(plan.env?.DSH_PERMISSION_MODE).toBe("workspace-write");
+        expect(plan.env?.DSH_PERMISSION_MODE).not.toBe("danger-full-access");
+      },
+    );
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("buildLaunch: CURSOR_ROUTE_ASK=1 opts out even when alwaysApprove true", () => {
+    const { dir, bin } = makeFakeDsh("ask-env");
+    const promptFile = join(dir, "job.prompt");
+    writeFileSync(promptFile, "ping");
+    withEnv(
+      {
+        CURSOR_ROUTE_DSH_BIN: bin,
+        DEEPSEEK_API_KEY: "test-key",
+        CURSOR_ROUTE_ASK: "1",
+        CURSOR_ROUTE_DS_MODEL: undefined,
+        ANTHROPIC_MODEL: undefined,
+      },
+      () => {
+        const plan = deepseekAdapter.buildLaunch({
+          promptFile,
+          cwd: dir,
+          alwaysApprove: true,
+        });
+        expect(plan.env?.DSH_PERMISSION_MODE).toBe("workspace-write");
+        expect(plan.alwaysApprove).toBe(false);
+      },
+    );
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("buildLaunch: missing binary falls back to plain `dsh` for dry-run", () => {
+    const { dir } = makeFakeDsh("nobin");
+    const promptFile = join(dir, "job.prompt");
+    writeFileSync(promptFile, "ping");
+    // Point PATH at an empty dir so `command -v dsh` finds nothing,
+    // regardless of what the dev machine has installed.
+    const empty = join(dir, "empty");
+    mkdirSync(empty, { recursive: true });
+    withEnv(
+      {
+        CURSOR_ROUTE_DSH_BIN: undefined,
+        DEEPSEEK_API_KEY: undefined,
+        PATH: empty,
+        CURSOR_ROUTE_DS_MODEL: undefined,
+        ANTHROPIC_MODEL: undefined,
+      },
+      () => {
+        const plan = deepseekAdapter.buildLaunch({
+          promptFile,
+          cwd: dir,
+          alwaysApprove: true,
+          dryRun: true,
+        });
+        expect(plan.command).toContain("'dsh' --profile headless");
+        expect(plan.command).toContain("--patch");
+        expect(plan.env?.DEEPSEEK_API_KEY).toBeUndefined();
+      },
+    );
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("buildLaunch: non-.prompt promptFile does not overwrite the prompt", () => {
+    const { dir, bin } = makeFakeDsh("noprompt-ext");
+    const promptFile = join(dir, "job");
+    writeFileSync(promptFile, "keep-me");
+    withEnv(
+      {
+        CURSOR_ROUTE_DSH_BIN: bin,
+        DEEPSEEK_API_KEY: "test-key",
+        CURSOR_ROUTE_DS_MODEL: undefined,
+        ANTHROPIC_MODEL: undefined,
+      },
+      () => {
+        expect(patchPathForPrompt(promptFile)).toBe(`${promptFile}.dsh-patch.yml`);
+        deepseekAdapter.buildLaunch({
+          promptFile,
+          cwd: dir,
+          alwaysApprove: true,
+        });
+        expect(readFileSync(promptFile, "utf8")).toBe("keep-me");
+        expect(existsSync(`${promptFile}.dsh-patch.yml`)).toBe(true);
+      },
+    );
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("buildLaunch: rejects modelId that would break YAML", () => {
+    const { dir, bin } = makeFakeDsh("badid");
+    const promptFile = join(dir, "job.prompt");
+    writeFileSync(promptFile, "ping");
+    withEnv(
+      {
+        CURSOR_ROUTE_DSH_BIN: bin,
+        DEEPSEEK_API_KEY: "test-key",
+        CURSOR_ROUTE_DS_MODEL: undefined,
+        ANTHROPIC_MODEL: undefined,
+      },
+      () => {
+        expect(() =>
+          deepseekAdapter.buildLaunch({
+            promptFile,
+            cwd: dir,
+            alwaysApprove: true,
+            model: "flash",
+            modelId: "x\n    injected: true",
+          }),
+        ).toThrow(/Invalid DeepSeek model id/);
+      },
+    );
+    rmSync(dir, { recursive: true, force: true });
   });
 });
 
@@ -290,23 +610,38 @@ describe("health", () => {
   test("returns structured report", () => {
     const r = runHealth();
     expect(r.product).toBe("cursor-route");
-    expect(r.version).toBe("0.1.7");
+    expect(r.version).toBe("0.1.8");
     expect(r.checks.length).toBeGreaterThan(3);
     expect(r.checks.some((c) => c.name === "tmux")).toBe(true);
     expect(r.checks.some((c) => c.name === "cursor_cli")).toBe(true);
   });
 
+  test("config version is 0.1.8", () => {
+    expect(config.version).toBe("0.1.8");
+  });
+
   test("OR-gate: ok can be true while worker:deepseek is false", () => {
-    const prev = process.env.CURSOR_ROUTE_RELAXED;
+    const prev = {
+      relaxed: process.env.CURSOR_ROUTE_RELAXED,
+      bin: process.env.CURSOR_ROUTE_DSH_BIN,
+      key: process.env.DEEPSEEK_API_KEY,
+    };
     process.env.CURSOR_ROUTE_RELAXED = "1";
+    // Force deepseek unhealthy even on machines that have a real dsh + key.
+    process.env.CURSOR_ROUTE_DSH_BIN = join(tmpdir(), `missing-dsh-${process.pid}`);
+    delete process.env.DEEPSEEK_API_KEY;
     try {
       const r = runHealth();
       const ds = r.checks.find((c) => c.name === "worker:deepseek");
       expect(ds?.ok).toBe(false);
       expect(r.ok).toBe(true);
     } finally {
-      if (prev === undefined) delete process.env.CURSOR_ROUTE_RELAXED;
-      else process.env.CURSOR_ROUTE_RELAXED = prev;
+      if (prev.relaxed === undefined) delete process.env.CURSOR_ROUTE_RELAXED;
+      else process.env.CURSOR_ROUTE_RELAXED = prev.relaxed;
+      if (prev.bin === undefined) delete process.env.CURSOR_ROUTE_DSH_BIN;
+      else process.env.CURSOR_ROUTE_DSH_BIN = prev.bin;
+      if (prev.key === undefined) delete process.env.DEEPSEEK_API_KEY;
+      else process.env.DEEPSEEK_API_KEY = prev.key;
     }
   });
 

package/src/cli.ts

@@ -52,9 +52,9 @@ Usage:
   cursor-route clean [--days N]
 
 Start options:
-  --worker <grok|claude-ds|openrouter>  Worker adapter (default: grok; deepseek = reserved slot)
+  --worker <grok|claude-ds|openrouter|deepseek>  Worker adapter (default: grok; deepseek = experimental official dsh)
   --lane <easy|mid|hard>                Lane → worker (easy=openrouter, mid=claude-ds, hard=grok)
-  --model <flash|pro>                   Mid DeepSeek only (default: flash / CURSOR_ROUTE_DS_MODEL). Parsed only for claude-ds
+  --model <flash|pro>                   Mid DeepSeek only (default: flash / CURSOR_ROUTE_DS_MODEL). Parsed for claude-ds + deepseek
   --dir <path>                          Working directory (default: cwd)
   --ask                                 Disable always-approve for this job
   --dry-run                             Print launch command; do not start
@@ -70,6 +70,8 @@ Env:
   CURSOR_ROUTE_DS_MODEL              Default mid model flash|pro (or deepseek-v4-pro[1m]); overridden by --model
   CURSOR_ROUTE_GROK_BIN              Override the grok binary path (tests / power users)
   CURSOR_ROUTE_CLAUDE_DS_BIN         Override the claude-ds binary path (tests / power users)
+  CURSOR_ROUTE_DSH_BIN               Override the dsh binary path (tests / power users)
+  DEEPSEEK_API_KEY                   DeepSeek API key (required for --worker deepseek)
   OPENROUTER_API_KEY                 OpenRouter key (required for --worker openrouter / --lane easy)
   CURSOR_ROUTE_OPENROUTER_MODEL      OpenRouter model (default: openrouter/free)
   OPENROUTER_BASE_URL                OpenRouter API base (default: https://openrouter.ai/api/v1)
@@ -250,8 +252,9 @@ async function main() {
 
     let model: DsModelAlias | undefined;
     let modelId: string | undefined;
-    // --model is DeepSeek/claude-ds only; ignore (do not validate) for other workers
-    if (f.model !== undefined && resolvedWorker === "claude-ds") {
+    // --model is DeepSeek-only (claude-ds mid lane + experimental deepseek worker);
+    // ignore (do not validate) for other workers
+    if (f.model !== undefined && (resolvedWorker === "claude-ds" || resolvedWorker === "deepseek")) {
       try {
         const choice = asDsModelChoice(f.model);
         if (choice) {

package/src/config.ts

@@ -2,7 +2,10 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { defaultJobsDir } from "./runtime.ts";
 
-/** Workers with a live adapter. `deepseek` is a reserved slot (unreleased harness). */
+/**
+ * Workers with a live adapter. `deepseek` is the experimental official
+ * DeepSeek Harness (dsh) — an opt-in worker, not a mid default.
+ */
 export type WorkerKind = "grok" | "claude-ds" | "openrouter" | "deepseek";
 export type Lane = "easy" | "mid" | "hard";
 
@@ -86,13 +89,16 @@ function maxConcurrentJobsFromEnv(): number {
  */
 export const config = {
   product: "cursor-route",
-  version: "0.1.7",
+  version: "0.1.8",
   get jobsDir(): string {
     return defaultJobsDir();
   },
   tmuxPrefix: "cursor-route",
   defaultWorker: "grok" as WorkerKind,
-  /** Lane → default worker (Cemini /route public core). */
+  /**
+   * Lane → default worker (Cemini /route public core).
+   * `deepseek` is experimental only — mid stays on claude-ds.
+   */
   laneWorkers: {
     easy: "openrouter" as WorkerKind,
     mid: "claude-ds" as WorkerKind,