dsh-plugin-cc 0.1.0 → 0.2.0

package/.claude-plugin/marketplace.json

@@ -3,13 +3,13 @@
   "owner": { "name": "dsh-plugin-cc contributors" },
   "metadata": {
     "description": "Unofficial Claude Code plugin for DeepSeek Harness (dsh).",
-    "version": "0.1.0"
+    "version": "0.2.0"
   },
   "plugins": [
     {
       "name": "dsh",
       "description": "Use DeepSeek Harness from Claude Code to plan, review plans and delegate tasks.",
-      "version": "0.1.0",
+      "version": "0.2.0",
       "author": { "name": "dsh-plugin-cc contributors" },
       "source": "./plugins/dsh"
     }

package/README.md

@@ -1,10 +1,16 @@
 # dsh-plugin-cc
 
+[![npm](https://img.shields.io/npm/v/dsh-plugin-cc)](https://www.npmjs.com/package/dsh-plugin-cc)
+
 Use [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (`dsh`) from inside Claude Code to plan work, review plans and hand tasks to dsh.
 
-> **Unofficial.** This plugin is not affiliated with or endorsed by DeepSeek or Anthropic. It is also a separate project from [cpj-dev/dsh-plugin-cc](https://github.com/cpj-dev/dsh-plugin-cc), which has the same name and a similar purpose.
+This plugin is for Claude Code users who want an easy way to start using dsh from the workflow they already have.
+
+## What You Get
 
-The plugin follows the layout of [codex-plugin-cc](https://github.com/openai/codex-plugin-cc) (Apache-2.0). Its commands follow what dsh offers rather than mirroring Codex's.
+- `/dsh:plan` for a read-only implementation plan written by dsh
+- `/dsh:review-plan` to check a plan against the real code
+- `/dsh:rescue`, `/dsh:status`, `/dsh:result` and `/dsh:cancel` to delegate work and manage background jobs
 
 ## Requirements
 
@@ -15,19 +21,21 @@ The plugin follows the layout of [codex-plugin-cc](https://github.com/openai/cod
 ## Install
 
 ```
-/plugin marketplace add <path-or-url-of-this-repo>
+/plugin marketplace add TrungyuD/dsh-plugin-cc
 /plugin install dsh@dsh-plugin-cc
 /reload-plugins
 /dsh:setup
 ```
 
+The package is also published on npm as [`dsh-plugin-cc`](https://www.npmjs.com/package/dsh-plugin-cc) (`npm i dsh-plugin-cc`, `yarn add dsh-plugin-cc` or `pnpm add dsh-plugin-cc`). That only downloads the files into `node_modules`; it does not register the plugin with Claude Code. Install it with the `/plugin` commands above.
+
 `/dsh:setup` checks Node, dsh and its version, and runs a one-line read-only smoke prompt to confirm you are logged in. If dsh is missing it offers to install it.
 
 ## Commands
 
 | Command | What it does |
 |---|---|
-| `/dsh:plan <what to plan>` | dsh explores the repository and writes an implementation plan. Read-only. |
+| `/dsh:plan <what to plan>` | dsh explores the repository and writes an implementation plan, which is saved as `plans/<YYMMDD-HHmm>-<slug>/plan.md`. dsh itself is read-only. |
 | `/dsh:review-plan [path] [focus]` | dsh checks a plan against the real code and answers with `Verdict: approve`, `needs-changes` or `reject`, then findings. Read-only. |
 | `/dsh:rescue [--write\|--read-only] [--resume\|--fresh] <task>` | Hands a debugging or implementation task to dsh through the `dsh-rescue` subagent. |
 | `/dsh:status [job-id]` | Lists active and recent jobs for this repository. |
@@ -37,6 +45,15 @@ The plugin follows the layout of [codex-plugin-cc](https://github.com/openai/cod
 
 `/dsh:plan` and `/dsh:review-plan` take `--wait` or `--background`. Without either, Claude asks once and recommends background. `/dsh:rescue` takes the same flags. All of them take `--model flash|pro|<name>`.
 
+### Plan
+
+```
+/dsh:plan add a --version flag to the CLI
+/dsh:plan --model pro --wait split the session code into its own module
+```
+
+dsh stays read-only while it explores. When it finishes, the plugin saves the plan as `plans/<YYMMDD-HHmm>-<slug>/plan.md` in the repository and prints `Saved plan: <path>`. A run that fails or is cancelled saves nothing. `/dsh:review-plan` with no path then offers that plan first. If you track `plans/` in git, each run leaves a new untracked file.
+
 ### Review a plan
 
 ```
@@ -61,8 +78,8 @@ The default is `deepseek-flash`, dsh's own default, so nothing is overridden unl
 
 ## Permission model
 
-- `/dsh:plan` and `/dsh:review-plan` always run read-only. The sandbox denies file writes, and escalation requests fail because headless dsh has no approval channel.
-- `/dsh:rescue` can write by default, the same as the Codex plugin. Ask for diagnosis or research only, or pass `--read-only`, to prevent edits.
+- `/dsh:plan` and `/dsh:review-plan` always run read-only for dsh. The sandbox denies file writes, and escalation requests fail because headless dsh has no approval channel. `/dsh:plan` writes one file, the plan, after dsh has finished.
+- `/dsh:rescue` can write by default. Ask for diagnosis or research only, or pass `--read-only`, to prevent edits.
 - A resumed rescue session keeps the mode it was created with. Asking for a different mode on resume fails with a message to start a new session with `--fresh`.
 - "Read-only" protects your workspace. dsh still writes its own sessions and profile under `~/.dsh/`.
 - The plugin never uses dsh's `never` approval policy, because that auto-approves.
@@ -71,7 +88,7 @@ The default is `deepseek-flash`, dsh's own default, so nothing is overridden unl
 
 Every run is a one-shot `dsh --profile headless --json` process, and each one leaves a session under `~/.dsh/sessions/`. The footer of each result names the session, for example `dsh session: session-… · model: deepseek-flash · mode: read-only`. Continue a session in the terminal with `dsh tui --resume <session-id>`.
 
-Job records live in the plugin data directory, scoped to the repository and to the Claude session. Ending the Claude session cancels that session's running jobs.
+Job records live in the plugin data directory, scoped to the repository and to the Claude session. Ending the Claude session cancels that session's running jobs, including jobs it started in other directories with `--cwd`.
 
 ## Limits
 
@@ -80,16 +97,15 @@ Job records live in the plugin data directory, scoped to the repository and to t
 - No `--effort` option, and no stop-time review gate.
 - The plugin only knows the permission mode it started a session with. If you change a session's mode yourself in `dsh tui --resume`, the plugin's footer and its `--read-only` check no longer reflect it.
 - Foreground runs are limited by Claude Code's Bash timeout (the commands ask for 10 minutes). Use `--background` for longer work.
-- Quote and backslash characters in request text are normalized when the arguments are split.
-- Ending a Claude session only cancels jobs started from that session's starting directory; jobs started with `--cwd` elsewhere are not cleaned up.
-
-## Development
 
-```
-npm test
-```
+## Help and contributing
 
-Tests use a fake `dsh` binary, so they need neither network access nor credentials.
+- [docs/troubleshooting.md](docs/troubleshooting.md) covers common problems.
+- [SUPPORT.md](SUPPORT.md) explains where to ask for help and what to include.
+- [SECURITY.md](SECURITY.md) explains how to report a vulnerability privately.
+- [CONTRIBUTING.md](CONTRIBUTING.md) covers development, tests and releases.
+- [docs/dsh-compat.md](docs/dsh-compat.md) lists everything the plugin relies on in dsh.
+- [plugins/dsh/CHANGELOG.md](plugins/dsh/CHANGELOG.md) lists changes by version.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-cc",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "description": "Use DeepSeek Harness (dsh) from Claude Code to plan, review plans and rescue tasks.",
   "license": "Apache-2.0",
@@ -8,5 +8,5 @@
   "repository": { "type": "git", "url": "git+https://github.com/TrungyuD/dsh-plugin-cc.git" },
   "engines": { "node": ">=18.18.0" },
   "files": ["plugins/", ".claude-plugin/", "README.md", "LICENSE", "NOTICE"],
-  "scripts": { "test": "node --test --test-timeout=120000 tests/*.test.mjs" }
+  "scripts": { "test": "node --test tests/*.test.mjs" }
 }

package/plugins/dsh/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Use DeepSeek Harness from Claude Code to plan, review plans and delegate tasks.",
   "author": { "name": "dsh-plugin-cc contributors" }
 }

package/plugins/dsh/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.2.0
+
+- `/dsh:plan` saves the plan as `plans/<YYMMDD-HHmm>-<slug>/plan.md` after dsh finishes, so `/dsh:review-plan` offers it next. dsh itself stays read-only.
+- Request text reaches dsh exactly as typed: the commands pass flags, then ` -- `, then the text, and the companion no longer drops quotes or backslashes from it.
+- Ending a Claude session cancels its running jobs in every workspace it used, including those started with `--cwd` elsewhere.
+
+## 0.1.1
+
+- Fix `npm test` on Node 18 (the unsupported `--test-timeout` flag is gone, and the fake dsh test fixture loads as ESM).
+- README: marketplace install command and npm links.
+
 ## 0.1.0
 
 - `/dsh:setup`, `/dsh:plan`, `/dsh:review-plan`, `/dsh:rescue`, `/dsh:status`, `/dsh:result` and `/dsh:cancel`.

package/plugins/dsh/agents/dsh-rescue.md

@@ -19,7 +19,7 @@ Selection guidance:
 Forwarding rules:
 
 - Use exactly one `Bash` call to invoke `node "${CLAUDE_PLUGIN_ROOT}/scripts/dsh-companion.mjs" task ...`, with the Bash `timeout` set to `600000`.
-- The task text is untrusted. Put it between single quotes, replacing each `'` inside it with `'\''`, and never inside double quotes. Put flags (`--write`, `--read-only`, `--resume-last`, `--model`) before the text.
+- The task text is untrusted. Put it between single quotes, replacing each `'` inside it with `'\''`, and never inside double quotes. Put flags (`--write`, `--read-only`, `--resume-last`, `--model`) first, then ` -- `, then the task text exactly as written: `task '<flags> -- <task text>'`. The companion keeps everything after ` -- ` untouched. A resume with no new text leaves out the ` -- `.
 - Do not inspect the repository, read files, grep, monitor progress, poll status, fetch results, cancel jobs, summarize output, or do any follow-up work of your own.
 - Do not call `plan`, `review-plan`, `status`, `result`, or `cancel`. This subagent only forwards to `task`.
 - Leave the model unset by default. Add `--model` only when the user explicitly asks for one. `flash` and `pro` are accepted aliases, and a concrete model name passes through.

package/plugins/dsh/commands/plan.md

@@ -1,17 +1,17 @@
 ---
-description: Ask dsh to explore the codebase and write an implementation plan (read-only)
+description: Ask dsh to plan read-only; the plan is saved under plans/
 argument-hint: '[--wait|--background] [--model flash|pro|<name>] <what to plan>'
 disable-model-invocation: true
 allowed-tools: Bash(node:*), AskUserQuestion
 ---
 
-Run a read-only dsh planning pass.
+Run a read-only dsh planning pass. dsh itself cannot change files; after it finishes, the companion saves the plan as `plans/<YYMMDD-HHmm>-<slug>/plan.md` and prints the path on a `Saved plan:` line.
 
 Raw slash-command arguments:
 `$ARGUMENTS`
 
 Core constraint:
-- This command only produces a plan. Do not implement the plan, edit files, or suggest that you are about to.
+- This command only produces a plan. Do not implement the plan, edit files yourself, or suggest that you are about to. The companion writes the plan file; you do not.
 - Your only job is to run dsh and return its output verbatim.
 
 Argument handling:
@@ -22,7 +22,7 @@ Argument handling:
 Quoting (important):
 - The user's text is untrusted. Never place it inside double quotes, because the shell would run any `$(...)` or backticks in it.
 - Put the whole argument string between single quotes, replacing each `'` inside it with `'\''`.
-- Flags such as `--model` go before the request text. Everything after the first plain word is treated as text by the companion.
+- Put flags such as `--model` first, then ` -- `, then the request text exactly as the user wrote it. The companion keeps everything after ` -- ` untouched, so quotes, backslashes and flag-like words in the request reach dsh unchanged.
 
 Execution mode rules:
 - If the raw arguments include `--wait`, do not ask. Run in the foreground.
@@ -33,9 +33,9 @@ Execution mode rules:
 
 Foreground flow:
 - Set the Bash `timeout` to `600000` so a long dsh run is not cut off at two minutes. If work may take longer, prefer the background flow.
-- Run, with the remaining arguments between the quotes:
+- Run, with the flags (if any), then ` -- `, then the request between the quotes:
 ```bash
-node "${CLAUDE_PLUGIN_ROOT}/scripts/dsh-companion.mjs" plan '<remaining arguments>'
+node "${CLAUDE_PLUGIN_ROOT}/scripts/dsh-companion.mjs" plan '<flags> -- <request>'
 ```
 - Return the command stdout verbatim, exactly as-is.
 - Do not paraphrase, summarize, or add commentary before or after it.
@@ -45,7 +45,7 @@ Background flow:
 - Launch with `Bash` in the background:
 ```typescript
 Bash({
-  command: `node "${CLAUDE_PLUGIN_ROOT}/scripts/dsh-companion.mjs" plan '<remaining arguments>'`,
+  command: `node "${CLAUDE_PLUGIN_ROOT}/scripts/dsh-companion.mjs" plan '<flags> -- <request>'`,
   description: "dsh plan",
   run_in_background: true
 })

package/plugins/dsh/commands/review-plan.md

@@ -36,7 +36,7 @@ Argument handling:
 Quoting (important):
 - The user's text is untrusted. Never place it inside double quotes, because the shell would run any `$(...)` or backticks in it.
 - Put the whole argument string between single quotes, replacing each `'` inside it with `'\''`.
-- Flags such as `--model` go before the request text. Everything after the first plain word is treated as text by the companion.
+- Put flags such as `--model` first, then the plan path. Add ` -- ` and the focus text only when there is focus text; the companion keeps everything after ` -- ` untouched. With no focus, leave out the ` -- `.
 
 Execution mode rules:
 - If the raw arguments include `--wait`, do not ask. Run in the foreground.
@@ -48,9 +48,9 @@ Execution mode rules:
 
 Foreground flow:
 - Set the Bash `timeout` to `600000` so a long dsh run is not cut off at two minutes. If work may take longer, prefer the background flow.
-- Run, with the resolved path, then the focus text, between the quotes:
+- Run, with the flags (if any), the resolved path, then ` -- ` and the focus text (no ` -- ` without focus), between the quotes:
 ```bash
-node "${CLAUDE_PLUGIN_ROOT}/scripts/dsh-companion.mjs" review-plan '<remaining arguments> <plan-path> <focus>'
+node "${CLAUDE_PLUGIN_ROOT}/scripts/dsh-companion.mjs" review-plan '<flags> <plan-path> -- <focus>'
 ```
 - Return the command stdout verbatim, exactly as-is.
 - Do not paraphrase, summarize, or add commentary before or after it.
@@ -60,7 +60,7 @@ Background flow:
 - Launch with `Bash` in the background:
 ```typescript
 Bash({
-  command: `node "${CLAUDE_PLUGIN_ROOT}/scripts/dsh-companion.mjs" review-plan '<remaining arguments> <plan-path> <focus>'`,
+  command: `node "${CLAUDE_PLUGIN_ROOT}/scripts/dsh-companion.mjs" review-plan '<flags> <plan-path> -- <focus>'`,
   description: "dsh review-plan",
   run_in_background: true
 })

package/plugins/dsh/scripts/dsh-companion.mjs

@@ -22,7 +22,7 @@ import {
   resolveResultJob,
   resolveResumableTask
 } from "./lib/job-control.mjs";
-import { collectPlanFiles, findLatestPlanDir } from "./lib/plans.mjs";
+import { collectPlanFiles, findLatestPlanDir, savePlanFile } from "./lib/plans.mjs";
 import { binaryAvailable, processCommandIncludes, terminateProcessTree } from "./lib/process.mjs";
 import { interpolateTemplate, loadPromptTemplate } from "./lib/prompts.mjs";
 import {
@@ -32,13 +32,14 @@ import {
   renderStatusReport,
   renderStoredJobResult
 } from "./lib/render.mjs";
-import { generateJobId, upsertJob, withStateLock, writeJobFile } from "./lib/state.mjs";
+import { generateJobId, registerSessionWorkspace, upsertJob, withStateLock, writeJobFile } from "./lib/state.mjs";
 import {
   appendLogLine,
   createJobLogFile,
   createJobProgressUpdater,
   createJobRecord,
   createProgressReporter,
+  isJobCancelled,
   nowIso,
   recordDshPid,
   runTrackedJob
@@ -89,21 +90,24 @@ function outputCommandResult(payload, rendered, asJson) {
   outputResult(asJson ? payload : rendered, asJson);
 }
 
+// A single argv entry is the raw slash-command string: split it shell-style, but keep everything
+// after an unquoted `--` as one verbatim text. Several argv entries are already split.
 function normalizeArgv(argv) {
   if (argv.length === 1) {
     const [raw] = argv;
     if (!raw || !raw.trim()) {
-      return [];
+      return { tokens: [], verbatim: null };
     }
     return splitRawArgumentString(raw);
   }
-  return argv;
+  return { tokens: argv, verbatim: null };
 }
 
 // --wait and --background are handled by the slash commands. They are accepted and ignored here
 // so a stray flag never turns into prompt text.
 function parseCommandInput(argv, config = {}) {
-  return parseArgs(normalizeArgv(argv), {
+  const { tokens, verbatim } = normalizeArgv(argv);
+  const parsed = parseArgs(tokens, {
     ...config,
     booleanOptions: [...(config.booleanOptions ?? []), "background", "wait"],
     aliasMap: {
@@ -111,6 +115,11 @@ function parseCommandInput(argv, config = {}) {
       ...(config.aliasMap ?? {})
     }
   });
+  // The verbatim text never goes through option parsing, so text such as `--json` stays text.
+  if (verbatim) {
+    parsed.positionals.push(verbatim);
+  }
+  return parsed;
 }
 
 function canonicalCwd(cwd) {
@@ -206,9 +215,13 @@ function phaseForEvent(event) {
 
 /**
  * Runs one dsh headless process under job tracking, in the foreground of this process.
- * `summarize(finalText)` produces the one-line job summary.
+ * `summarize(finalText)` produces the one-line job summary. `finalize(result)` may return
+ * `{ payload, renderedSuffix }` extras that are stored with the job result and shown after the output.
  */
-async function executeRun({ job, prompt, permissionMode, model, sessionId, summarize, asJson }) {
+async function executeRun({ job, prompt, permissionMode, model, sessionId, summarize, finalize, asJson }) {
+  if (job.sessionId) {
+    registerSessionWorkspace(job.sessionId, job.workspaceRoot);
+  }
   const logFile = createJobLogFile(job.workspaceRoot, job.id, job.title);
   const jobWithLog = { ...job, logFile };
   upsertJob(job.workspaceRoot, jobWithLog);
@@ -259,7 +272,13 @@ async function executeRun({ job, prompt, permissionMode, model, sessionId, summa
             }
           }
         });
-        return { ...result, summary: summarize(result.payload.finalText, result) };
+        const extras = finalize?.(result);
+        return {
+          ...result,
+          payload: { ...result.payload, ...extras?.payload },
+          rendered: `${result.rendered}${extras?.renderedSuffix ?? ""}`,
+          summary: summarize(result.payload.finalText, result)
+        };
       },
       { logFile }
     );
@@ -322,6 +341,18 @@ async function handlePlan(argv) {
     permissionMode: READ_ONLY,
     model,
     summarize: (finalText) => shorten(firstMeaningfulLine(finalText, request)),
+    // dsh stays read-only; the plan file is written here, after dsh has exited.
+    finalize: (result) => {
+      if (result.exitStatus !== 0 || !result.payload.finalText.trim() || isJobCancelled(workspaceRoot, job.id)) {
+        return null;
+      }
+      try {
+        const planFile = savePlanFile(workspaceRoot, request, result.payload.finalText);
+        return { payload: { planFile }, renderedSuffix: `Saved plan: ${planFile}\n` };
+      } catch (error) {
+        return { payload: {}, renderedSuffix: `Plan not saved: ${error instanceof Error ? error.message : String(error)}\n` };
+      }
+    },
     asJson: options.json
   });
 }

package/plugins/dsh/scripts/lib/args.mjs

@@ -75,13 +75,21 @@ export function parseArgs(argv, config = {}) {
   return { options, positionals };
 }
 
+/**
+ * Splits one raw argument string like a shell would, except that an unquoted standalone `--` ends
+ * the splitting: everything after it comes back untouched as `verbatim`, so request text keeps its
+ * quotes and backslashes. `verbatim` is null when there is no such `--`.
+ */
 export function splitRawArgumentString(raw) {
   const tokens = [];
   let current = "";
   let quote = null;
   let escaping = false;
+  let wordStart = true;
+
+  for (let index = 0; index < raw.length; index += 1) {
+    const character = raw[index];
 
-  for (const character of raw) {
     if (escaping) {
       current += character;
       escaping = false;
@@ -90,6 +98,7 @@ export function splitRawArgumentString(raw) {
 
     if (character === "\\") {
       escaping = true;
+      wordStart = false;
       continue;
     }
 
@@ -104,6 +113,7 @@ export function splitRawArgumentString(raw) {
 
     if (character === "'" || character === "\"") {
       quote = character;
+      wordStart = false;
       continue;
     }
 
@@ -112,10 +122,17 @@ export function splitRawArgumentString(raw) {
         tokens.push(current);
         current = "";
       }
+      wordStart = true;
       continue;
     }
 
+    if (wordStart && character === "-" && raw[index + 1] === "-" && (index + 2 === raw.length || /\s/.test(raw[index + 2]))) {
+      // The one whitespace character that separates `--` from the text is not part of the text.
+      return { tokens, verbatim: raw.slice(index + 2).replace(/^\s/, "") };
+    }
+
     current += character;
+    wordStart = false;
   }
 
   if (escaping) {
@@ -126,5 +143,5 @@ export function splitRawArgumentString(raw) {
     tokens.push(current);
   }
 
-  return tokens;
+  return { tokens, verbatim: null };
 }

package/plugins/dsh/scripts/lib/plans.mjs

@@ -68,3 +68,63 @@ export function collectPlanFiles(absolutePath) {
   }
   return [planFile, ...listPhaseFiles(absolutePath).map((name) => path.join(absolutePath, name))];
 }
+
+const SLUG_LIMIT = 40;
+const HEADING_LIMIT = 120;
+
+function pad(value) {
+  return String(value).padStart(2, "0");
+}
+
+function slugify(text) {
+  // NFKD has no decomposition for the Vietnamese d with stroke, so map it first.
+  const slug = String(text ?? "")
+    .replace(/đ/g, "d")
+    .replace(/Đ/g, "D")
+    .normalize("NFKD")
+    .replace(/[̀-ͯ]/g, "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  if (slug.length <= SLUG_LIMIT) {
+    return slug;
+  }
+  const cut = slug.slice(0, SLUG_LIMIT + 1);
+  const boundary = cut.lastIndexOf("-");
+  return (boundary > 0 ? cut.slice(0, boundary) : cut.slice(0, SLUG_LIMIT)).replace(/-+$/, "");
+}
+
+/** Name of a new plan directory, `YYMMDD-HHmm-<slug>`, in the local time of `date`. */
+export function planDirName(request, date = new Date()) {
+  const stamp = `${pad(date.getFullYear() % 100)}${pad(date.getMonth() + 1)}${pad(date.getDate())}-${pad(date.getHours())}${pad(date.getMinutes())}`;
+  return `${stamp}-${slugify(request) || "dsh-plan"}`;
+}
+
+/**
+ * Writes `text` as `<workspaceRoot>/plans/<planDirName>/plan.md` and returns that path relative to
+ * the workspace. The directory is created exclusively, so two saves in the same minute with the
+ * same request get `-2`, `-3`, ... instead of sharing a directory.
+ */
+export function savePlanFile(workspaceRoot, request, text, date = new Date()) {
+  const plansDir = path.join(workspaceRoot, "plans");
+  fs.mkdirSync(plansDir, { recursive: true });
+
+  const base = planDirName(request, date);
+  let name = base;
+  for (let attempt = 2; ; attempt += 1) {
+    try {
+      fs.mkdirSync(path.join(plansDir, name));
+      break;
+    } catch (error) {
+      if (error?.code !== "EEXIST") {
+        throw error;
+      }
+      name = `${base}-${attempt}`;
+    }
+  }
+
+  const title = String(request ?? "").trim().replace(/\s+/g, " ").slice(0, HEADING_LIMIT);
+  const file = path.join(plansDir, name, "plan.md");
+  fs.writeFileSync(file, `# Plan: ${title}\n\n${String(text).trimEnd()}\n`, "utf8");
+  return path.join("plans", name, "plan.md");
+}

package/plugins/dsh/scripts/lib/state.mjs

@@ -10,6 +10,7 @@ const PLUGIN_DATA_ENV = "CLAUDE_PLUGIN_DATA";
 const FALLBACK_STATE_ROOT_DIR = path.join(os.tmpdir(), "dsh-companion");
 const STATE_FILE_NAME = "state.json";
 const JOBS_DIR_NAME = "jobs";
+const SESSIONS_DIR_NAME = "sessions";
 const MAX_JOBS = 50;
 const LOCK_DIR_NAME = ".lock";
 const LOCK_STALE_MS = 10000;
@@ -89,6 +90,11 @@ function defaultState() {
   };
 }
 
+function resolveStateRoot() {
+  const pluginDataDir = process.env[PLUGIN_DATA_ENV];
+  return pluginDataDir ? path.join(pluginDataDir, "state") : FALLBACK_STATE_ROOT_DIR;
+}
+
 export function resolveStateDir(cwd) {
   const workspaceRoot = resolveWorkspaceRoot(cwd);
   let canonicalWorkspaceRoot = workspaceRoot;
@@ -101,9 +107,75 @@ export function resolveStateDir(cwd) {
   const slugSource = path.basename(workspaceRoot) || "workspace";
   const slug = slugSource.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "workspace";
   const hash = createHash("sha256").update(canonicalWorkspaceRoot).digest("hex").slice(0, 16);
-  const pluginDataDir = process.env[PLUGIN_DATA_ENV];
-  const stateRoot = pluginDataDir ? path.join(pluginDataDir, "state") : FALLBACK_STATE_ROOT_DIR;
-  return path.join(stateRoot, `${slug}-${hash}`);
+  return path.join(resolveStateRoot(), `${slug}-${hash}`);
+}
+
+// ---------------------------------------------------------------------------
+// Session index: one marker per (Claude session, workspace), so SessionEnd can find every
+// workspace a session started jobs in, not only the directory it started in.
+
+function resolveSessionIndexDir(sessionId) {
+  const hash = createHash("sha256").update(String(sessionId)).digest("hex").slice(0, 16);
+  return path.join(resolveStateRoot(), SESSIONS_DIR_NAME, hash);
+}
+
+export function registerSessionWorkspace(sessionId, workspaceRoot) {
+  const dir = resolveSessionIndexDir(sessionId);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const marker = path.join(dir, `${path.basename(resolveStateDir(workspaceRoot))}.json`);
+  atomicWrite(marker, `${JSON.stringify({ workspaceRoot })}\n`);
+}
+
+export function listSessionWorkspaces(sessionId) {
+  const dir = resolveSessionIndexDir(sessionId);
+  let names;
+  try {
+    names = fs.readdirSync(dir);
+  } catch {
+    return [];
+  }
+  const roots = [];
+  for (const name of names) {
+    if (!name.endsWith(".json")) {
+      continue;
+    }
+    try {
+      const { workspaceRoot } = JSON.parse(fs.readFileSync(path.join(dir, name), "utf8"));
+      if (typeof workspaceRoot === "string" && workspaceRoot) {
+        roots.push(workspaceRoot);
+      }
+    } catch {
+      // A half-written or foreign file is not a marker.
+    }
+  }
+  return roots;
+}
+
+export function forgetSessionWorkspaces(sessionId) {
+  fs.rmSync(resolveSessionIndexDir(sessionId), { recursive: true, force: true });
+}
+
+// Drops marker dirs of sessions that never reached SessionEnd. Every run rewrites its marker, which
+// refreshes the dir mtime, so a session that is still running jobs keeps its markers.
+export function pruneSessionIndex(maxAgeMs) {
+  const sessionsDir = path.join(resolveStateRoot(), SESSIONS_DIR_NAME);
+  let names;
+  try {
+    names = fs.readdirSync(sessionsDir);
+  } catch {
+    return;
+  }
+  const cutoff = Date.now() - maxAgeMs;
+  for (const name of names) {
+    const dir = path.join(sessionsDir, name);
+    try {
+      if (fs.statSync(dir).mtimeMs < cutoff) {
+        fs.rmSync(dir, { recursive: true, force: true });
+      }
+    } catch {
+      // Already gone or unreadable; the next prune retries.
+    }
+  }
 }
 
 export function resolveStateFile(cwd) {

package/plugins/dsh/scripts/session-lifecycle-hook.mjs

@@ -5,11 +5,24 @@ import process from "node:process";
 
 import { CHILD_ENV } from "./lib/dsh.mjs";
 import { processCommandIncludes, terminateProcessTree } from "./lib/process.mjs";
-import { listJobs, readJobFile, resolveJobFile, resolveStateFile, upsertJob, withStateLock, writeJobFile } from "./lib/state.mjs";
+import {
+  forgetSessionWorkspaces,
+  listJobs,
+  listSessionWorkspaces,
+  pruneSessionIndex,
+  readJobFile,
+  resolveJobFile,
+  resolveStateDir,
+  resolveStateFile,
+  upsertJob,
+  withStateLock,
+  writeJobFile
+} from "./lib/state.mjs";
 import { nowIso, SESSION_ID_ENV } from "./lib/tracked-jobs.mjs";
 import { resolveWorkspaceRoot } from "./lib/workspace.mjs";
 
 const PLUGIN_DATA_ENV = "CLAUDE_PLUGIN_DATA";
+const SESSION_INDEX_MAX_AGE_MS = 7 * 24 * 3600 * 1000;
 
 function readHookInput() {
   const raw = fs.readFileSync(0, "utf8").trim();
@@ -85,10 +98,40 @@ function cleanupSessionJobs(cwd, sessionId) {
 function handleSessionStart(input) {
   appendEnvVar(SESSION_ID_ENV, input.session_id);
   appendEnvVar(PLUGIN_DATA_ENV, process.env[PLUGIN_DATA_ENV]);
+  try {
+    pruneSessionIndex(SESSION_INDEX_MAX_AGE_MS);
+  } catch {
+    // Housekeeping must never fail a session start.
+  }
 }
 
 function handleSessionEnd(input) {
-  cleanupSessionJobs(input.cwd || process.cwd(), input.session_id || process.env[SESSION_ID_ENV]);
+  const sessionId = input.session_id || process.env[SESSION_ID_ENV];
+  if (!sessionId) {
+    return;
+  }
+
+  // The starting directory plus every workspace this session ran a job in, one state dir each.
+  const roots = new Map();
+  for (const cwd of [input.cwd || process.cwd(), ...listSessionWorkspaces(sessionId)]) {
+    try {
+      roots.set(resolveStateDir(cwd), cwd);
+    } catch {
+      // A workspace that can no longer be resolved has nothing to clean.
+    }
+  }
+
+  try {
+    for (const cwd of roots.values()) {
+      try {
+        cleanupSessionJobs(cwd, sessionId);
+      } catch (error) {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+      }
+    }
+  } finally {
+    forgetSessionWorkspaces(sessionId);
+  }
 }
 
 function main() {

package/plugins/dsh/skills/dsh-cli-runtime/SKILL.md

@@ -9,10 +9,10 @@ user-invocable: false
 Use this skill only inside the `dsh:dsh-rescue` subagent.
 
 Primary helper:
-- `node "${CLAUDE_PLUGIN_ROOT}/scripts/dsh-companion.mjs" task "<raw arguments>"`
+- `node "${CLAUDE_PLUGIN_ROOT}/scripts/dsh-companion.mjs" task '<flags> -- <task text>'`
 
 Execution rules:
-- Set the Bash `timeout` to `600000` and put the task text between single quotes (escape each `'` as `'\''`), after all flags.
+- Set the Bash `timeout` to `600000` and put the whole argument string between single quotes (escape each `'` as `'\''`): the flags first, then ` -- `, then the task text. The companion keeps the text after ` -- ` untouched.
 - The rescue subagent is a forwarder, not an orchestrator. Its only job is to invoke `task` once and return that stdout unchanged.
 - Prefer the helper over hand-rolled `dsh` command lines or any other Bash activity.
 - Do not call `setup`, `plan`, `review-plan`, `status`, `result`, or `cancel` from `dsh:dsh-rescue`.