cursor-route 0.1.7 → 0.1.9

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,53 @@
+$ cursor-route --version
+0.1.9
+
+$ CURSOR_ROUTE_RELAXED=1 cursor-route health
+cursor-route v0.1.9
+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.
+  ✓ lane:mid         DeepSeek proven (claude-ds (DeepSeek shim))
+  ✓ 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.9**)
 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.9",
   "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

@@ -18,7 +18,7 @@ You are the **orchestrator**. Do **not** implement bulk code in this Cursor sess
 - Mid/hard implementation that should run on a subscription worker (Grok CLI / claude-ds)
 - Multi-file investigation that benefits from parallel panes
 
-**Do not steal federation `/route`.** Private Cemini `/route` (route-task → SIP → verify → Grok/claude-ds chain) is a different skill. This public skill only drives the `cursor-route` CLI.
+**Do not steal federation `/route`.** Private Cemini `/route` (route-task → verify → Grok/claude-ds chain) is a different skill. This public skill only drives the `cursor-route` CLI.
 
 ## Lanes (public core)
 
@@ -46,10 +46,23 @@ 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.
-2. Write a clear handoff prompt with **verify criteria** (no secrets, no LIVE Discord).
+1. Run `cursor-route health` (or `CURSOR_ROUTE_RELAXED=1` for headless). If the **target worker** is unhealthy, fix before spawning. If targeting **mid**, require `lane:mid` ✓ (or health JSON `lanes.mid.deepseek`) before spawn — `CURSOR_ROUTE_ALLOW_ANTHROPIC=1` is not DeepSeek proof.
+2. Write a clear handoff prompt with **Success criteria** + **Verify** + **NEVER** (no secrets, no LIVE Discord).
 3. Spawn:
 
 ```bash
@@ -57,24 +70,48 @@ cursor-route start --lane hard --dir "$PWD" "$(cat <<'EOF'
 ## Task
 ...
 
+## Success criteria
+- [ ] ...
+
 ## Verify
 - [ ] ...
+
+## NEVER
+- ...
 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.
+5. Summarize worker results with **verify evidence** — no status-only “done” (see Verify / claim closeout). If verify fails, reconsider the plan/definition (not only retry) — `send` a correction or spawn a follow-up; do not invent success.
+
+## Verify / claim closeout
+
+Verify criteria are an **external eval contract** (AutoDesign pattern), fixed by the parent — not a checklist the worker may rewrite:
+
+- Workers must **not rewrite Success criteria / Verify** to claim done
+- Parent closeout is an **evidence tree**: report **spawn** (job id, worker, lane, model) + **execute** (status, exit) + **verify** (`capture` excerpt / exit). A single “done” scalar is not enough.
+- Parent closes a job only on **capture / exit evidence** (`cursor-route capture <id>`, job exit status)
+- `cursor-route status --json` `.evidence.verify.claim` stays `"unverified"` until the parent reads capture
+- **activity ≠ verification** — busy panes, many tool calls, or long transcripts do not make a claim true
+
+## Eval & skill hygiene
+
+- **External eval contract (AutoDesign):** do not rewrite Verify / Success criteria mid-run to make a failing job look green — capture + exit status are the contract (see Verify / claim closeout).
+- **Skill misevolution:** do not auto-edit `route-orch` or promote skill variants from worker trajectories without operator HITL — write-time approval ≠ safe retrieval later.
+- **On verify fail:** prefer reconsidering the plan/definition (wrong approach) over grinding the same tactic; attribute failure to stage when possible (spawn vs execute vs verify).
 
 ## Always-approve
 
-Defaults on for workers. Opt out: `cursor-route start … --ask` or `CURSOR_ROUTE_ASK=1`.
+Defaults on for workers. Opt out: `cursor-route start … --ask` or `CURSOR_ROUTE_ASK=1`. Always-approve is for **coding worktrees only** — it does not authorize LIVE Discord, trading, or irreversible SaaS.
 
 ## 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 open-source or dump private Cemini `agent-toolkit` paths into public handoffs
+- Do not claim the official DeepSeek harness (`@deepseek-ai/dsh`) is the mid default — `--worker deepseek` is an opt-in experiment (cheap to abandon), not a product fork; mid stays **claude-ds**
+- Do not fork a second mid harness
+- Do not open-source or dump private cemini `agent-toolkit` paths into public handoffs
 - Do not mark done without reading `capture` / exit status
+- When editing this skill itself, treat changes as **skill-evolution** — do not auto-promote harmful instructions; prefer **HITL** (no unattended promote from worker trajectories)

package/src/adapters/claude-ds.ts

@@ -124,6 +124,25 @@ function resolveClaudeDs(): { binary: string; mode: string } | null {
   return null;
 }
 
+/**
+ * Mid lane is proven DeepSeek only via shim (`claude-ds` / `deepseek-claude`)
+ * or stock `claude` routed to DeepSeek. The Anthropic escape hatch is not proof.
+ */
+export function isMidDeepSeekProven(): boolean {
+  const resolved = resolveClaudeDs();
+  if (!resolved) return false;
+  return !resolved.mode.startsWith("claude → Anthropic");
+}
+
+/** Human detail for health `lane:mid` (mode when proven; install hint otherwise). */
+export function midDeepSeekProofDetail(): string {
+  const resolved = resolveClaudeDs();
+  if (!resolved || resolved.mode.startsWith("claude → Anthropic")) {
+    return "mid not proven DeepSeek — install claude-ds / set ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic. CURSOR_ROUTE_ALLOW_ANTHROPIC=1 is not proof.";
+  }
+  return `DeepSeek proven (${resolved.mode})`;
+}
+
 function pickModel(requested?: DsModelAlias, modelId?: string): { alias: DsModelAlias; id: string } {
   if (modelId) {
     const alias = requested ?? resolveDsModel(modelId).alias;

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