cursor-route 0.1.7 → 0.1.8

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.1.8 — 2026-08-14
+
+- Experimental `--worker deepseek`: official DeepSeek Harness (`dsh`, `@deepseek-ai/dsh`) runs headless — `dsh --profile headless` with a per-job Cordis patch pinning the model. Not a mid default: `laneWorkers.mid` stays `claude-ds`.
+- `--model flash|pro` (and `deepseek-v4-pro[1m]`) now applies to both `claude-ds` and `deepseek`; patch sets `agent-default-model` → `provider: deepseek-official` (never rewrites `~/.dsh/settings.yaml`, so parallel jobs don't race).
+- Always-approve → `DSH_PERMISSION_MODE=danger-full-access`; `--ask` → `workspace-write`. `DEEPSEEK_API_KEY` travels via env only — never in the launch command or patch.
+- Health: `worker:deepseek` ✓ only when `dsh` is on PATH (override `CURSOR_ROUTE_DSH_BIN`) **and** `DEEPSEEK_API_KEY` is set.
+- Dry-run for `--worker deepseek` works without `dsh` installed (falls back to plain `dsh` in the printed command); real starts stay gated by health.
+- `clean` also removes leftover `.dsh-patch.yml` files; patch path never overwrites a non-`.prompt` prompt file.
+
 ## 0.1.7 — 2026-08-12
 
 - Fix: `CURSOR_ROUTE_DS_MODEL` / `ANTHROPIC_MODEL` now apply on the `start` product path (live default)

package/CONTRIBUTING.md

@@ -11,6 +11,7 @@ CURSOR_ROUTE_RELAXED=1 ./bin/cursor-route health   # without tmux
 ./bin/cursor-route start --dry-run --worker grok "ping"
 ./bin/cursor-route start --dry-run --lane mid --model flash "ping"
 ./bin/cursor-route start --dry-run --lane mid --model pro "ping"
+./bin/cursor-route start --dry-run --worker deepseek --model flash "ping"   # needs dsh + DEEPSEEK_API_KEY for real starts
 ```
 
 Keep `skills/route-orch/SKILL.md` and `.cursor/skills/route-orch/SKILL.md` identical when editing the skill.

package/README.md

@@ -102,6 +102,36 @@ Working notes for this repo (edit in place): [docs/briefs/WORKING.md](./docs/bri
 | `sessions` | Managed tmux sessions |
 | `clean [--days N]` | Drop old job files |
 
+## Demo
+
+A dry-run capture (no live workers, no secrets) is committed as a reproducible fixture:
+
+```bash
+# Needs Bun or Node 20+ and a runnable ./bin/cursor-route (clone: bun install)
+docs/fixtures/generate-hero-demo.sh      # regenerate docs/fixtures/hero-demo.log
+```
+
+```text
+$ cursor-route --version
+0.1.8
+
+$ CURSOR_ROUTE_RELAXED=1 cursor-route health
+cursor-route v0.1.8
+health: OK
+
+$ cursor-route start --lane mid --model flash --dry-run "Add a unit test for shellQuote"
+dry-run job a1b2c3d4
+worker: claude-ds
+model:  flash
+command: cd '~/Projects/cursor-route' && '~/.local/bin/claude-ds' -PromptFile '~/.local/share/cursor-route/jobs/a1b2c3d4.prompt' -Model 'deepseek-v4-flash' --dangerously-skip-permissions
+
+$ cursor-route jobs --json
+[]
+```
+
+Full capture: [docs/fixtures/hero-demo.log](./docs/fixtures/hero-demo.log).
+A real hero GIF is still pending — recording steps live in [docs/DEMO_GIF.md](./docs/DEMO_GIF.md).
+
 ## Lanes
 
 | Lane | Worker | Intent |
@@ -155,7 +185,18 @@ Persist the same vars under `~/.claude/settings.json` → `"env": { … }` if yo
 
 **Also accepted:** `claude-ds` or `deepseek-claude` on PATH (Cemini shims). The adapter passes `-Model deepseek-v4-flash|deepseek-v4-pro`.
 
-**Reserved:** `--worker deepseek` is a slot for an official DeepSeek coding harness — not wired yet. Mid stays on `claude-ds`.
+**Experimental:** `--worker deepseek` runs the official DeepSeek Harness (`dsh`, npm `@deepseek-ai/dsh`) as an opt-in worker — **mid stays on `claude-ds`**; don't default lanes here.
+
+```bash
+npm i -g @deepseek-ai/dsh
+export DEEPSEEK_API_KEY=YOUR_DEEPSEEK_API_KEY   # from platform.deepseek.com
+
+cursor-route health                              # worker:deepseek should be ✓
+cursor-route start --worker deepseek "…"         # Flash (default)
+cursor-route start --worker deepseek --model pro "…"   # Pro when you need it
+```
+
+The adapter launches `dsh --profile headless` with a **per-job Cordis patch** (`jobs/<id>.dsh-patch.yml`, mode 0600) that pins `--model flash|pro` (`deepseek-v4-pro[1m]` preserved) — it never rewrites `~/.dsh/settings.yaml`, so parallel jobs don't race. Always-approve maps to `DSH_PERMISSION_MODE=danger-full-access`; `--ask` drops to `workspace-write`. Your `DEEPSEEK_API_KEY` travels via env only — never in the launch command or patch. Override the binary with `CURSOR_ROUTE_DSH_BIN`.
 
 **Not the default:** bare `claude` still talking to Anthropic. Health refuses that so a misconfigured install cannot silently burn frontier $ rates. Escape hatch only: `CURSOR_ROUTE_ALLOW_ANTHROPIC=1`.
 
@@ -249,8 +290,8 @@ MIT © Cemini — see [LICENSE](LICENSE).
 
 ## Roadmap (explicitly later)
 
-- Homebrew tap  
-- Native DeepSeek harness adapter  
-- Codebase map injection (`--map`)  
-- Cursor CLI `agent` as alternate supervisor  
+- Homebrew tap
+- Stabilize the DeepSeek harness adapter (experimental `--worker deepseek` since 0.1.8)
+- Codebase map injection (`--map`)
+- Cursor CLI `agent` as alternate supervisor
 - Web UI / CAO-style MCP supervisor

package/dist/adapters/deepseek.js

@@ -1,19 +1,138 @@
+import { execSync } from "node:child_process";
+import { existsSync, writeFileSync, unlinkSync } from "node:fs";
+import { shellQuote } from "../util.js";
+import { DS_MODEL_IDS, resolveDsModel, } from "../config.js";
 /**
- * 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() {
+    // 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, modelId) {
+    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) {
+    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) {
+    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) {
+    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 = {
     kind: "deepseek",
-    label: "Official DeepSeek harness (unreleased)",
+    label: "Official DeepSeek Harness (dsh)",
     health() {
+        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 = {
+            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/dist/cli.js

@@ -29,9 +29,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
@@ -47,6 +47,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)
@@ -221,8 +223,9 @@ async function main() {
         const resolvedWorker = worker ?? (lane ? config.laneWorkers[lane] : config.defaultWorker);
         let model;
         let modelId;
-        // --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/dist/config.js

@@ -65,13 +65,16 @@ function maxConcurrentJobsFromEnv() {
  */
 export const config = {
     product: "cursor-route",
-    version: "0.1.7",
+    version: "0.1.8",
     get jobsDir() {
         return defaultJobsDir();
     },
     tmuxPrefix: "cursor-route",
     defaultWorker: "grok",
-    /** 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",
         mid: "claude-ds",

package/dist/jobs.js

@@ -219,7 +219,7 @@ export function startJob(opts) {
     writeSecure(paths.prompt, opts.prompt);
     let model;
     let modelId;
-    if (worker === "claude-ds") {
+    if (worker === "claude-ds" || worker === "deepseek") {
         if (opts.model) {
             model = opts.model;
             modelId = opts.modelId ?? DS_MODEL_IDS[opts.model];
@@ -249,6 +249,7 @@ export function startJob(opts) {
             alwaysApprove,
             model,
             modelId,
+            dryRun: Boolean(opts.dryRun),
         });
     }
     catch (e) {
@@ -421,7 +422,7 @@ export function cleanJobs(olderThanDays = 7) {
             if (Number.isFinite(t) &&
                 t < cutoff &&
                 (job.status === "completed" || job.status === "failed" || job.status === "killed")) {
-                for (const ext of [".json", ".prompt", ".log"]) {
+                for (const ext of [".json", ".prompt", ".log", ".dsh-patch.yml"]) {
                     const fp = underJobsDir(id, ext);
                     if (existsSync(fp))
                         unlinkSync(fp);

package/docs/DEMO_GIF.md

@@ -1,5 +1,21 @@
 # Hero demo recording (GIF)
 
+## Status
+
+No real GIF yet — the checkbox stays open until a `docs/fixtures/hero.gif` exists.
+
+Committed fixture for now: [docs/fixtures/hero-demo.log](./fixtures/hero-demo.log),
+a reproducible dry-run capture (no live workers, no secrets). Regenerate it with:
+
+```bash
+docs/fixtures/generate-hero-demo.sh
+```
+
+Also see [docs/fixtures/claude-ds-smoke.log](./fixtures/claude-ds-smoke.log)
+(headless `claude-ds` smoke proof). Both are machine-agnostic.
+
+## Recording the real GIF (later)
+
 tmux is required for the viral attach/send demo. On this laptop brew needs sudo — record after:
 
 ```bash
@@ -27,4 +43,4 @@ If you previously exported `$HOME/.cursor-route/bin`, that dir is stale — remo
 
 Record with [asciinema](https://asciinema.org/) or CleanShot → export GIF → `docs/fixtures/hero.gif`.
 
-Until then, use `docs/fixtures/claude-ds-smoke.log` as the committed proof fixture.
+When a real GIF lands, check off the **Hero GIF** item in `docs/briefs/WORKING.md` and reference it here.

package/docs/briefs/WORKING.md

@@ -1,9 +1,9 @@
 ---
 title: cursor-route workspace — working brief (edit in place)
 repo: ~/Projects/cursor-route
-npm: cursor-route@0.1.7 (LIVE on npm latest)
+npm: cursor-route@0.1.8 (LIVE on npm latest)
 created: 2026-08-12
-updated: 2026-08-12
+updated: 2026-08-14
 ---
 
 # cursor-route — living brief
@@ -24,7 +24,7 @@ Cursor Agent plans. Workers run in tmux via `cursor-route`:
 
 Always-approve on (`--ask` / `CURSOR_ROUTE_ASK=1` to opt out). Jobs live in `~/.local/share/cursor-route/jobs`, not in this clone.
 
-Install: `npm i -g cursor-route` → **0.1.7**. Release notes: [CHANGELOG.md](../../CHANGELOG.md).
+Install: `npm i -g cursor-route` → **0.1.8**. Release notes: [CHANGELOG.md](../../CHANGELOG.md).
 
 ## Open (edit / check off)
 
@@ -33,9 +33,10 @@ Install: `npm i -g cursor-route` → **0.1.7**. Release notes: [CHANGELOG.md](..
   - [x] add `--model flash|pro` on `start`
   - [x] document Grok **auth** ≠ usage-out (`grok login`) vs quota → Pro stand-in
 - [x] **Skill `route-orch`** — Flash/Pro table in `skills/` + `.cursor/skills/`
-- [x] **Official DeepSeek Harness** — `deepseek` adapter slot present; mid stays on claude-ds
+- [x] **Official DeepSeek Harness** — `deepseek` adapter slot present; `@deepseek-ai/dsh` 0.1.0-rc.6 (2026-08-13, github.com/deepseek-ai/deepseek-harness, MIT) is a developer-preview plugin kernel (web UI + `dsh --profile headless "job"`), not a Claude Code replacement; mid does not swap
 - [x] **0.1.7 debug fixes** — env default wired through `startJob`; Anthropic hatch omits DS ids; preserve `[1m]`
-- [ ] **Hero GIF** — still outstanding (`docs/DEMO_GIF.md`)
+- [x] **Experimental `--worker deepseek`** — 0.1.8: real dsh adapter (`dsh --profile headless` + per-job Cordis patch pins the model; never writes `~/.dsh/settings.yaml`). Always-approve → `DSH_PERMISSION_MODE=danger-full-access`, `--ask` → `workspace-write`; key via env only. Health ✓ needs `dsh` + `DEEPSEEK_API_KEY` (override `CURSOR_ROUTE_DSH_BIN`). Mid stays **claude-ds**.
+- [ ] **Hero GIF** — still outstanding; dry-run fixture ships as the substitute for now (`docs/fixtures/hero-demo.log` — see `docs/DEMO_GIF.md`)
 - [x] **Do not** paste private `ROUTE_KIT`, SIP, prod paths, or hang-watchdog env into this public repo
 
 ## Repo map
@@ -44,7 +45,7 @@ Install: `npm i -g cursor-route` → **0.1.7**. Release notes: [CHANGELOG.md](..
 |------|------|
 | `src/cli.ts` | `health` / `start` / `jobs` / `capture` / `send` / `kill` |
 | `src/adapters/claude-ds.ts` | Mid worker; DeepSeek URL required; `--model` → `-Model` |
-| `src/adapters/deepseek.ts` | Reserved unreleased harness slot |
+| `src/adapters/deepseek.ts` | Experimental dsh worker (`--worker deepseek`; mid stays claude-ds) |
 | `src/adapters/grok.ts` | Hard worker |
 | `src/adapters/openrouter.ts` | Easy worker |
 | `skills/route-orch/SKILL.md` | Cursor skill — spawn CLI, do not implement in-session |
@@ -59,3 +60,7 @@ Install: `npm i -g cursor-route` → **0.1.7**. Release notes: [CHANGELOG.md](..
 | 2026-08-12 | Shipped Flash default + `--model pro`, deepseek slot, skill table → 0.1.6. |
 | 2026-08-12 | npm `cursor-route@0.1.6` LIVE; CHANGELOG + README skill-install path fixed. |
 | 2026-08-12 | Grok debug → 0.1.7: env DS default, Anthropic hatch, `[1m]` preserve. |
+| 2026-08-13 | Hero demo dry-run fixture + docs: `docs/fixtures/generate-hero-demo.sh` → `hero-demo.log`; README Demo, DEMO_GIF.md, demo-notes pointer. Real GIF still open. |
+| 2026-08-13 | GPTSOL fixes: scrub inherited env/paths, stable job ids, ignore `docs/briefs/handoffs/`, GIF checkbox wording. |
+| 2026-08-14 | DeepSeek Harness eval: `@deepseek-ai/dsh` 0.1.0-rc.6 is a developer-preview plugin kernel, not a mid replacement; `--worker deepseek` stays unhealthy; mid remains claude-ds (docs-only, no version bump). |
+| 2026-08-14 | Experimental `--worker deepseek` wired to official dsh (headless + per-job patch + `DSH_PERMISSION_MODE` + key-via-env); `--model` applies to claude-ds + deepseek; mid stays claude-ds → 0.1.8 LIVE. |

package/docs/demo-notes.md

@@ -1,13 +1,15 @@
 # Demo fixture log (no secrets)
 
+> **Current fixture:** [docs/fixtures/hero-demo.log](./fixtures/hero-demo.log) — generated, dry-run, machine-agnostic (regenerate: `docs/fixtures/generate-hero-demo.sh`). Real GIF still pending: [DEMO_GIF.md](./DEMO_GIF.md).
+
 Simulated capture output for README / tweet assets — replace with a real GIF once tmux is available.
 
 ```
 $ cursor-route --version
-0.1.6
+0.1.8
 
 $ cursor-route health
-cursor-route v0.1.6
+cursor-route v0.1.8
 health: OK
   ✓ tmux
   ✓ runtime          bun ok
@@ -15,7 +17,7 @@ health: OK
   ✓ worker:grok
   ✓ worker:claude-ds
   ✓ worker:openrouter
-  ✗ worker:deepseek  unreleased — mid lane uses claude-ds
+  ✗ worker:deepseek  dsh not found — mid default remains claude-ds
   ✓ jobs_dir         ~/.local/share/cursor-route/jobs
 
 $ cursor-route start --lane mid "Add a failing test then make it pass"

package/docs/fixtures/generate-hero-demo.sh

@@ -0,0 +1,109 @@
+#!/usr/bin/env bash
+# generate-hero-demo.sh — regenerate docs/fixtures/hero-demo.log
+#
+# Dry-run only: no live Grok, no worker spawned, no secrets. Jobs dir is
+# sandboxed (trap-cleaned). Output is path-scrubbed + id-normalized so the
+# committed fixture is machine-agnostic and regenerates stably.
+#
+# Prerequisites: Bun or Node 20+; runnable ./bin/cursor-route
+# (git clone: bun install; npm global install ships dist/).
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+BIN="$ROOT/bin/cursor-route"
+OUT="$ROOT/docs/fixtures/hero-demo.log"
+
+if [[ ! -f "$BIN" ]]; then
+  echo "missing $BIN — run from a cursor-route checkout (need bun/node 20+)" >&2
+  exit 1
+fi
+
+# Neutralize inherited overrides that would leak private paths into the log.
+unset CURSOR_ROUTE_CLAUDE_DS_BIN CURSOR_ROUTE_GROK_BIN CURSOR_ROUTE_DSH_BIN \
+  CURSOR_ROUTE_ALLOW_ANTHROPIC \
+  CURSOR_ROUTE_ALLOW_STOCK_CLAUDE CURSOR_ROUTE_ANTHROPIC_BASE_URL CURSOR_ROUTE_DS_MODEL \
+  CURSOR_ROUTE_OPENROUTER_MODEL OPENROUTER_API_KEY OPENROUTER_BASE_URL \
+  ANTHROPIC_BASE_URL ANTHROPIC_AUTH_TOKEN ANTHROPIC_API_KEY ANTHROPIC_MODEL \
+  DEEPSEEK_API_KEY XAI_API_KEY 2>/dev/null || true
+
+TMP="$(mktemp -d)"
+trap 'rm -rf "$TMP"' EXIT
+export CURSOR_ROUTE_JOBS_DIR="$TMP/.demo-jobs"
+# Pin dsh to a missing path so worker:deepseek renders identically on machines
+# that do have a real dsh installed (the adapter shows the install hint, no path).
+export CURSOR_ROUTE_DSH_BIN="$TMP/no-such-dsh"
+
+RAW="$TMP/hero-demo.raw"
+NORM="$TMP/hero-demo.norm"
+
+{
+  echo "\$ cursor-route --version"
+  "$BIN" --version
+  echo
+
+  echo "\$ CURSOR_ROUTE_RELAXED=1 cursor-route health"
+  CURSOR_ROUTE_RELAXED=1 "$BIN" health
+  echo
+
+  echo "\$ cursor-route start --lane mid --model flash --dry-run \"Add a unit test for shellQuote\""
+  "$BIN" start --lane mid --model flash --dry-run "Add a unit test for shellQuote"
+  echo
+
+  echo "\$ cursor-route start --lane easy --dry-run \"Rewrite this FAQ answer in 3 sentences\""
+  "$BIN" start --lane easy --dry-run "Rewrite this FAQ answer in 3 sentences"
+  echo
+
+  echo "\$ cursor-route start --lane hard --dry-run \"Refactor auth module; run tests; report verify evidence\""
+  "$BIN" start --lane hard --dry-run "Refactor auth module; run tests; report verify evidence"
+  echo
+
+  echo "\$ cursor-route start --lane mid --dry-run --json \"Add a failing test then make it pass\""
+  "$BIN" start --lane mid --dry-run --json "Add a failing test then make it pass"
+  echo
+
+  echo "\$ cursor-route jobs --json"
+  "$BIN" jobs --json
+} > "$RAW"
+
+jobs_display="$HOME/.local/share/cursor-route/jobs"
+{
+  while IFS= read -r line || [[ -n "$line" ]]; do
+    line="${line//$TMP\/.demo-jobs/$jobs_display}"
+    line="${line//$ROOT/~/Projects/cursor-route}"
+    line="${line//$HOME/~}"
+    line="$(printf '%s' "$line" | sed -E \
+      -e 's#/Users/[^/\"'\'' ]+#~#g' \
+      -e 's#/home/[^/\"'\'' ]+#~#g' \
+      -e 's#/opt/cemini[^\"'\'' ]*#~#g' \
+      -e 's#/var/folders/[^\"'\'' ]+#/tmp#g')"
+    printf '%s\n' "$line"
+  done
+} < "$RAW" > "$NORM"
+
+python3 - "$NORM" "$OUT" <<'PY'
+import re, sys
+src, dst = sys.argv[1], sys.argv[2]
+text = open(src, encoding="utf-8").read()
+seq = ["a1b2c3d4", "b2c3d4e5", "c3d4e5f6", "d4e5f6a7"]
+seen: dict[str, str] = {}
+
+def take(jid: str) -> str:
+    if jid not in seen:
+        seen[jid] = seq[len(seen)] if len(seen) < len(seq) else f"{len(seen):08x}"
+    return seen[jid]
+
+out = []
+for line in text.splitlines(True):
+    def sub(m: re.Match[str]) -> str:
+        return m.group(1) + take(m.group(2)) + m.group(3)
+
+    line = re.sub(r"(dry-run job )([0-9a-f]{8})(\b)", sub, line)
+    line = re.sub(r'("id": ")([0-9a-f]{8})(")', sub, line)
+    line = re.sub(r"(jobs/)([0-9a-f]{8})(\.prompt)", sub, line)
+    line = re.sub(r"(headless-|cursor-route-)([0-9a-f]{8})(\b)", sub, line)
+    line = re.sub(r'("createdAt": ")[^"]+(")', r"\g<1>2026-08-13T00:00:00.000Z\2", line)
+    out.append(line)
+open(dst, "w", encoding="utf-8").write("".join(out))
+PY
+
+echo "wrote $OUT"

package/docs/fixtures/hero-demo.log

@@ -0,0 +1,52 @@
+$ cursor-route --version
+0.1.8
+
+$ CURSOR_ROUTE_RELAXED=1 cursor-route health
+cursor-route v0.1.8
+health: OK
+
+  ✓ tmux             ok
+  ✓ runtime          bun ok
+  ✓ script(1)        ok (tty log capture)
+  ✓ worker:grok      ok (auth checked at first start — run grok login if jobs fail) @ ~/.grok/bin/grok
+  ✓ worker:claude-ds ok (claude-ds (DeepSeek shim); default model deepseek-v4-flash) @ ~/.local/bin/claude-ds
+  ✗ worker:openrouter OPENROUTER_API_KEY not set — export your OpenRouter key (easy lane model defaults to openrouter/free) @ node '~/Projects/cursor-route/dist/openrouter-run.js'
+  ✗ worker:deepseek  dsh (@deepseek-ai/dsh) not found — install: npm i -g @deepseek-ai/dsh. Mid default remains claude-ds.
+  ✓ cursor_cli       optional ok (agent on PATH) — v0 supervisor is Cursor skill, not CLI
+  ✓ relaxed          CURSOR_ROUTE_RELAXED=1 — tmux optional (headless OK)
+  ✓ jobs_dir         ~/.local/share/cursor-route/jobs
+
+$ cursor-route start --lane mid --model flash --dry-run "Add a unit test for shellQuote"
+dry-run job a1b2c3d4
+worker: claude-ds
+model:  flash
+command: cd '~/Projects/cursor-route' && '~/.local/bin/claude-ds' -PromptFile '~/.local/share/cursor-route/jobs/a1b2c3d4.prompt' -Model 'deepseek-v4-flash' --dangerously-skip-permissions
+
+$ cursor-route start --lane easy --dry-run "Rewrite this FAQ answer in 3 sentences"
+dry-run job b2c3d4e5
+worker: openrouter
+command: node '~/Projects/cursor-route/dist/openrouter-run.js' --prompt-file '~/.local/share/cursor-route/jobs/b2c3d4e5.prompt'
+
+$ cursor-route start --lane hard --dry-run "Refactor auth module; run tests; report verify evidence"
+dry-run job c3d4e5f6
+worker: grok
+command: '~/.grok/bin/grok' -p "$(cat '~/.local/share/cursor-route/jobs/c3d4e5f6.prompt')" --cwd '~/Projects/cursor-route' --no-auto-update --output-format plain --always-approve
+
+$ cursor-route start --lane mid --dry-run --json "Add a failing test then make it pass"
+{
+  "id": "d4e5f6a7",
+  "schema": "cursor-route.job.v1",
+  "status": "pending",
+  "worker": "claude-ds",
+  "lane": "mid",
+  "model": "flash",
+  "prompt": "Add a failing test then make it pass",
+  "cwd": "~/Projects/cursor-route",
+  "alwaysApprove": true,
+  "tmuxSession": "cursor-route-d4e5f6a7",
+  "createdAt": "2026-08-13T00:00:00.000Z",
+  "command": "cd '~/Projects/cursor-route' && '~/.local/bin/claude-ds' -PromptFile '~/.local/share/cursor-route/jobs/d4e5f6a7.prompt' -Model 'deepseek-v4-flash' --dangerously-skip-permissions"
+}
+
+$ cursor-route jobs --json
+[]

package/llms.txt

@@ -2,7 +2,7 @@
 
 > Cursor stays the planner. DeepSeek (mid), Grok CLI (hard), and OpenRouter free models (easy) run parallel coding workers in tmux.
 
-MIT CLI + Cursor skill. npm: https://www.npmjs.com/package/cursor-route (latest **0.1.7**)  
+MIT CLI + Cursor skill. npm: https://www.npmjs.com/package/cursor-route (latest **0.1.8**)
 GitHub: https://github.com/cemini23/cursor-route
 
 ## FAQ

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursor-route",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Cursor stays the brain. Grok CLI + DeepSeek (claude-ds) + OpenRouter easy lane are the parallel army \u2014 lane-aware /route orchestration in tmux.",
   "type": "module",
   "license": "MIT",

package/skills/route-orch/SKILL.md

@@ -46,6 +46,19 @@ cursor-route start --lane mid --model pro --dir "$PWD" "…"
 
 If `worker:grok` is ✗ on health, that is usually **auth** (`grok login` / `XAI_API_KEY`) — not the Pro stand-in case.
 
+## Experimental: --worker deepseek (dsh)
+
+Official DeepSeek Harness headless as an opt-in worker — **not the mid default** (mid stays `claude-ds`).
+
+```bash
+npm i -g @deepseek-ai/dsh
+export DEEPSEEK_API_KEY=...        # platform.deepseek.com
+cursor-route start --worker deepseek --dir "$PWD" "…"
+cursor-route start --worker deepseek --model pro --dir "$PWD" "…"   # --model applies here too
+```
+
+Health ✓ needs `dsh` on PATH and `DEEPSEEK_API_KEY` set. The adapter pins `--model` via a per-job `--patch` (never touches `~/.dsh/settings.yaml`); always-approve → `DSH_PERMISSION_MODE=danger-full-access`, `--ask` → `workspace-write`. The key never enters the command or patch.
+
 ## Workflow
 
 1. Run `cursor-route health` (or `CURSOR_ROUTE_RELAXED=1` for headless). If the **target worker** is unhealthy, fix before spawning.
@@ -63,7 +76,7 @@ EOF
 )"
 ```
 
-Or `--worker grok` / `--worker claude-ds` / `--worker openrouter` (or `--lane easy`). Use `--no-tmux` only when tmux is unavailable.
+Or `--worker grok` / `--worker claude-ds` / `--worker deepseek` (experimental) / `--worker openrouter` (or `--lane easy`). Use `--no-tmux` only when tmux is unavailable.
 
 4. Monitor: `cursor-route jobs --json` · `cursor-route capture <id>` · `cursor-route send <id> "…"` (tmux only).
 5. Summarize worker results with **verify evidence** — no status-only “done”. If verify fails, `send` a correction or spawn a follow-up — do not invent success.
@@ -75,6 +88,6 @@ Defaults on for workers. Opt out: `cursor-route start … --ask` or `CURSOR_ROUT
 ## Anti-patterns
 
 - Do not paste API keys / private keys into prompts or `send`
-- Do not claim DeepSeek-native harness until that adapter ships — today is **claude-ds**
+- Do not claim the official DeepSeek harness (`@deepseek-ai/dsh`) is the mid default — `--worker deepseek` is experimental only; mid stays **claude-ds**
 - Do not open-source or dump private Cemini `agent-toolkit` paths into public handoffs
 - Do not mark done without reading `capture` / exit status