@ran-sh/dsh-crew 1.7.2 → 1.9.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-crew",
-  "version": "1.7.2",
+  "version": "1.9.0",
   "description": "Dispatch subtasks to DeepSeek Harness (DSH) agents as native subagents with live progress",
   "author": {
     "name": "ZSeven-W"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ran-sh/dsh-crew",
-  "version": "1.7.2",
+  "version": "1.9.0",
   "type": "module",
   "main": "./src/hub/entry.mjs",
   "bin": {

package/skills/dsh-crew/SKILL.md

@@ -32,10 +32,46 @@ same `dsh-crew` MCP server, so the behaviour below is identical from any host.
 | `dsh_worker_cancel` | cancel a workflow |
 | `dsh_worker_config` | read/update session settings: enable dispatch, tier, effort, timeout, presets, policy |
 
+Dispatch takes `task` (make it self-contained — the worker sees nothing else),
+`role` (`worker` for implementation, `reviewer` for an independent review pass),
+`cwd` (the workspace; defaults to the current project) and `timeout_seconds`.
+Use `dsh_spawn_worker` when you have other work to do meanwhile, then
+`dsh_worker_result` with `wait_seconds` to collect it.
+
 `dsh_worker_config` with no arguments is the cheapest way to answer "what is
 Crew set to right now". Its settings last for the session only; persisted
 changes belong in the 3210 panel.
 
+## Reading a result
+
+A result carries a `phase` and, when it did not succeed, a failure code. The
+phases are `created`, `queued`, `running`, `verifying`, `escalating`,
+`reviewing`, `ready`, `completed`, `failed`, `cancelled`, `interrupted`.
+
+**`phase: failed` does not mean the worker broke.** Most often it means the
+workflow's delivery gate rejected the result, and the reason code says which
+gate. Read the code before reacting:
+
+| Code | Means |
+|---|---|
+| `DELIVERY_INCOMPLETE` | the worker returned no change where the contract required one — a reply-only or question-only task lands here, and it is not a defect |
+| `TESTS_FAILED` / `TESTS_NOT_RUN` | the worker's own test evidence is failing or absent |
+| `REVIEW_CHANGES_REQUESTED` | the reviewer asked for changes; act on them |
+| `REVIEW_INCONCLUSIVE` | the review could not reach a verdict |
+| `WORKSPACE_MISMATCH` | the worker's changes are not in the workspace the job was meant to touch |
+| `TASK_BLOCKED` / `TASK_PARTIAL` | the worker says it could not finish |
+| `ATTEMPT_TIMEOUT` / `RUNTIME_FAILURE` / `EXECUTION_FAILED` | the run itself failed |
+| `POLICY_REJECTED` | Crew's own policy refused the dispatch; change the request, not the worker |
+| `PROVIDER_UNAVAILABLE` / `HUB_INCOMPATIBLE` | no model or no reachable hub |
+
+`terminal_reason: escalation_disabled` is **not** a separate failure — it is the
+escalation policy declining to retry after a failure. The failure code above it
+is the real reason.
+
+The selection trace names the model actually used and every candidate that was
+skipped, with the reason. Reach for it whenever the chosen model is not the one
+you expected.
+
 ## Choosing what to dispatch
 
 Delegate a bounded, independently verifiable unit when isolation,
@@ -48,6 +84,19 @@ Continue authorized work after a successful subtask; a returned workflow is a
 checkpoint, not the end of the task. If a worker's result is incomplete or its
 review asks for changes, that is a task result to act on — not approval.
 
+## Common ways a dispatch surprises you
+
+- **A task that only asks a question fails.** The delivery contract wants a
+  change; a reply-only task returns `DELIVERY_INCOMPLETE`. That is the gate
+  working, not the worker failing.
+- **Isolated workspaces need git.** The default `worktree` isolation fails with
+  `NOT_GIT_REPOSITORY` for a non-git workspace rather than silently sharing the
+  tree. Use `shared` deliberately if that is what you want.
+- **Long tasks need a longer timeout.** `timeout_seconds` is per attempt and
+  caps at 7200; the default is far shorter than a real refactor.
+- **A worker cannot see your conversation.** Anything it needs must be in
+  `task`, in the workspace, or in a file it can read.
+
 ## Configuration
 
 Two surfaces, and they are not equivalent:

package/src/mcp-runtime.mjs

@@ -285,7 +285,15 @@ export function buildMcpWorkflowRuntime(deps) {
     if (!repo.ok) {
       return { ok: false, reason: repo.reason ?? 'ISOLATION_UNAVAILABLE', error: `${job.role ?? 'worker'} needs an isolated git worktree: ${repo.error ?? repo.reason}` };
     }
-    const created = await createIsolatedWorkspace({ cwd: job.requested_cwd, jobId: job.id, baseRevision: job.workspace_branch ?? repo.baseRevision });
+    // The worktree name carries what the job was for, so an operator reading the
+    // directory list can tell a worker tree from a reviewer tree without opening
+    // anything. Role is the honest answer; it is what the job actually is.
+    const created = await createIsolatedWorkspace({
+      cwd: job.requested_cwd,
+      jobId: job.id,
+      purpose: job.role ?? 'job',
+      baseRevision: job.workspace_branch ?? repo.baseRevision,
+    });
     if (!created.ok) {
       return { ok: false, reason: created.reason ?? 'WORKTREE_CREATE_FAILED', error: `worktree create failed: ${created.error ?? ''}` };
     }

package/src/runtime-identity.mjs

@@ -36,7 +36,7 @@ export {
 // included in the identity contract.
 const RUNTIME_ID = randomUUID();
 
-export const RUNTIME_VERSION = '1.7.2';
+export const RUNTIME_VERSION = '1.9.0';
 export const HUB_PROTOCOL_VERSION = 1;
 
 export const HUB_CAPABILITIES = Object.freeze([

package/src/workspace-isolation.mjs

@@ -11,7 +11,7 @@
 // lock blocks cleanup.
 
 import { execFile } from 'node:child_process';
-import { existsSync, rmSync } from 'node:fs';
+import { existsSync, mkdirSync, rmSync } from 'node:fs';
 import { readFile, lstat } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join, resolve, basename } from 'node:path';
@@ -26,10 +26,23 @@ export const GIT_NOT_FOUND = 'GIT_NOT_FOUND';
 export const GIT_TIMEOUT = 'GIT_TIMEOUT';
 export const GIT_ERROR = 'GIT_ERROR';
 export const WORKTREE_LOCKED = 'WORKTREE_LOCKED';
+export const WORKTREE_RESERVE_FAILED = 'WORKTREE_RESERVE_FAILED';
 export const CANDIDATE_CAPTURE_FAILED = 'CANDIDATE_CAPTURE_FAILED';
 export const MAX_PARALLEL_CAP = 16;
 export const DEFAULT_MAX_PARALLEL = 3;
-const WORKTREE_PREFIX = 'dsh-crew-';
+// Worktree names read `Crew_YYYYMMDD_HHMMSS_<purpose>` so an operator can tell
+// from the directory alone when a job ran and what it was for. The legacy
+// prefix stays recognised as ours, so worktrees created by an earlier release
+// are still adopted and cleaned up rather than orphaned.
+const WORKTREE_PREFIX = 'Crew_';
+const LEGACY_WORKTREE_PREFIXES = Object.freeze(['dsh-crew-']);
+
+/** Whether a directory name is a worktree Crew created. */
+export function isCrewWorktreeName(name) {
+  const value = String(name ?? '');
+  return value.startsWith(WORKTREE_PREFIX)
+    || LEGACY_WORKTREE_PREFIXES.some((prefix) => value.startsWith(prefix));
+}
 
 async function defaultRunner(args, { cwd }) {
   try {
@@ -57,11 +70,46 @@ async function runGit(runner, args, opts) {
   }
 }
 
-function worktreeName(jobId) {
-  const safe = String(jobId ?? '').replace(/[^A-Za-z0-9._-]/g, '-') || 'job';
-  return `${WORKTREE_PREFIX}${safe}-${randomBytes(4).toString('hex')}`;
+const PURPOSE_MAX = 32;
+
+/** Local wall-clock stamp: readable, and what an operator expects to see. */
+function stamp(at) {
+  const d = at instanceof Date ? at : new Date(at ?? Date.now());
+  const p = (n) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}`
+    + `_${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`;
 }
 
+/**
+ * `Crew_<date>_<time>_<purpose>`, with a numeric suffix only when that name is
+ * already taken. Parallel jobs can start inside the same second, so the suffix is
+ * what keeps the name unique without putting random noise in every name.
+ */
+/**
+ * `Crew_<date>_<time>_<purpose>`, reserved by creating the directory.
+ *
+ * The reservation is a mkdir, not a lookup: two jobs starting in the same second
+ * both probe before either has created anything, so a check-then-act name would
+ * hand them the same path and one `git worktree add` would fail. mkdir
+ * fails on EEXIST, which makes the suffix loop race-free.
+ */
+function reserveWorktreeDir({ root, purpose, at }) {
+  mkdirSync(root, { recursive: true });
+  const safe = String(purpose ?? 'job').replace(/[^A-Za-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '').slice(0, PURPOSE_MAX) || 'job';
+  const base = `${WORKTREE_PREFIX}${stamp(at)}_${safe}`;
+  for (let n = 1; n <= 100; n += 1) {
+    const name = n === 1 ? base : `${base}-${n}`;
+    const dir = join(root, name);
+    try {
+      mkdirSync(dir);
+      return { ok: true, dir, name };
+    } catch (error) {
+      if (error?.code !== 'EEXIST') return { ok: false, error: String(error?.message ?? error) };
+    }
+  }
+  return { ok: false, error: 'no free worktree name' };
+}
 export function defaultWorktreeRoot() {
   return join(tmpdir(), 'dsh-crew-worktrees');
 }
@@ -90,15 +138,21 @@ export async function inspectRepository({ cwd, git, runner } = {}) {
   };
 }
 
-export async function createIsolatedWorkspace({ cwd, jobId, baseRevision, root = defaultWorktreeRoot(), git } = {}) {
+export async function createIsolatedWorkspace({ cwd, jobId, purpose, baseRevision, at, root = defaultWorktreeRoot(), git } = {}) {
   const run = git ?? defaultRunner;
   const repo = await inspectRepository({ cwd, git: run });
   if (!repo.ok) return { ok: false, reason: repo.reason, error: repo.error };
   const rev = baseRevision ?? repo.baseRevision;
-  const dir = join(root, worktreeName(jobId ?? repo.baseRevision));
+  const reserved = reserveWorktreeDir({ root, purpose, at });
+  if (!reserved.ok) return { ok: false, reason: WORKTREE_RESERVE_FAILED, error: reserved.error };
+  const { dir, name } = reserved;
   const res = await runGit(run, ['worktree', 'add', '--detach', dir, rev], { cwd: repo.repoRoot });
-  if (!res.ok) return { ok: false, reason: res.reason, error: res.error };
-  return { ok: true, worktreePath: dir, baseRevision: rev, repoRoot: repo.repoRoot, name: basename(dir) };
+  if (!res.ok) {
+    // Release the name so a retry is not blocked by an empty directory.
+    try { rmSync(dir, { recursive: true, force: true }); } catch {}
+    return { ok: false, reason: res.reason, error: res.error };
+  }
+  return { ok: true, worktreePath: dir, baseRevision: rev, repoRoot: repo.repoRoot, name };
 }
 
 function splitFirstTab(line) {
@@ -322,7 +376,7 @@ export async function cleanupIsolatedWorkspace({
   const run = git ?? defaultRunner;
   if (!worktreePath) return { ok: false, reason: NOT_GIT_REPOSITORY, error: 'worktree path required' };
   const root = repoRoot ?? (await mainRepoRoot(run, worktreePath));
-  const owned = basename(resolve(worktreePath)).startsWith(WORKTREE_PREFIX);
+  const owned = isCrewWorktreeName(basename(resolve(worktreePath)));
 
   if (root) {
     // Preferred path: `git worktree remove --force` (removes registration and
@@ -368,7 +422,7 @@ export async function staleWorktrees({ git, allowed = [] } = {}) {
           const path = block.split('\n').find((l) => l.startsWith('worktree '))?.slice('worktree '.length)?.trim();
           if (!path) continue;
           const abs = resolve(path);
-          if (basename(abs).startsWith(WORKTREE_PREFIX) && !set.has(abs)) stale.push(abs);
+          if (isCrewWorktreeName(basename(abs)) && !set.has(abs)) stale.push(abs);
         }
       }
     }