@ran-sh/dsh-crew 1.7.1 → 1.8.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-crew",
-  "version": "1.7.1",
+  "version": "1.8.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.1",
+  "version": "1.8.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/install/install-legacy.mjs

@@ -7,7 +7,7 @@ import { createHash } from 'node:crypto';
 import { dirname, join, resolve, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
-import { normalizeModelPriority } from '../model-routing.mjs';
+import { normalizeModelPriority } from '../model-routing.mjs';
 import { crewSkillFiles, installCrewSkill, readCrewSkill, removeCrewSkill } from './crew-skill.mjs';
 import { zcodeStatus } from './zcode.mjs';
 
@@ -70,17 +70,10 @@ function renderedCodexRole(root, file) {
   return source.replace(/args = \[.*server\.mjs"\]/, `args = ["${renderedPath}"]`);
 }
 
-function managedPolicyBlock(root) {
-  const policy = readText(join(root, 'codex', 'AGENTS.md'))?.trim();
-  if (!policy) return null;
-  return `${POLICY_START}\n${policy}\n${POLICY_END}`;
-}
-
 export function codexLegacyPolicyDigest(text) {
   const canonical = typeof text === 'string' ? text.replace(/\r\n/g, '\n').trim() : '';
   return canonical ? createHash('sha256').update(canonical, 'utf8').digest('hex') : null;
 }
-
 export function stripKnownLegacyCodexPolicy(text, { knownHashes = CODEX_LEGACY_POLICY_HASHES } = {}) {
   if (typeof text !== 'string') return text;
   const start = POLICY_START.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');

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.1';
+export const RUNTIME_VERSION = '1.8.0';
 export const HUB_PROTOCOL_VERSION = 1;
 
 export const HUB_CAPABILITIES = Object.freeze([

package/codex/AGENTS.md

@@ -1,53 +0,0 @@
-# Global capability-aware delegation policy
-
-The main Codex agent owns the task through final delivery. DSH Crew is an optional
-execution/review capability, not an automatic replacement for the main agent.
-
-## Discover and choose
-
-Before substantial delegation, read the live Crew configuration, capability and
-readiness contracts. Discover roles, models, modes and constraints dynamically;
-installed, configured, enabled and callable are different states. Refresh the
-snapshot after relevant configuration or availability changes, not every small step.
-
-Delegate bounded, independently verifiable units when isolation, specialization,
-parallel work or independent review provides a benefit. Give each unit its objective,
-owned files, workspace, constraints and acceptance evidence. Respect concurrency
-limits and manual/disabled capabilities. Keep ambiguity, integration, external
-effects and final communication in the main agent. Trivial work stays local.
-
-## Operator decision gate when DSH Crew is unavailable
-
-Once Crew is selected for a work unit, any required capability becoming unavailable
-or non-callable is a mandatory pause, regardless of cause. Do not implement further,
-repair/reconfigure Crew, silently fall back or switch execution paths. Perform only
-bounded read-only diagnosis, report the evidence and completed work, and wait for
-new operator direction: **repair Crew and continue through Crew**, or **do not repair
-Crew and continue with the main agent**. After repair, verify live readiness again;
-after local authorization, disclose that the affected work is not independently delegated.
-
-This gate does not apply when initial planning chooses local work without selecting
-Crew. A nonterminal wait is not an outage; continue the same workflow without duplicate
-dispatch. Review findings and failing code tests are task results to address, not by
-themselves evidence that Crew is unavailable.
-
-## Verify and finish
-
-Consume compact structured results and canonical events. Check changed scope,
-delivery completeness, tests, risks and the actual review verdict. Use independent
-review for non-trivial code when available and its invocation policy allows it;
-never bypass manual/disabled review. Requested changes or missing evidence are not
-approval. If selected review cannot run, use the operator gate above.
-
-Continue authorized work after a successful subtask; do not stop at its checkpoint.
-Delegation grants no new authority to push, publish, message, change credentials or
-delete data. Do not forward credentials, raw provider payloads or unbounded transcripts.
-
-## Harness upgrade redlines
-
-- Never install, update, register, unlink, repair, or mutate anything under ~/.dsh.
-- DSH Crew runtime upgrades must go through the Crew-owned installer and DSH_HOME.
-- Never use direct pnpm/npm/dsh plugin operations against the official web profile.
-- Preparing a Harness upgrade must not restart 3080 or 3210.
-- Standalone workers launch through the official DSH SDK profile contract; dsh-sdk-jsonrpc-demo is obsolete.
-- Legacy 3080 bridge must never be used for 3210 lifecycle/restart/rollback.

package/zcode/AGENTS.md

@@ -1,38 +0,0 @@
-# Global capability-aware delegation policy for ZCode
-
-ZCode is a host adapter for DSH Crew. Use the `dsh-crew` MCP server for Crew
-work only after its live capability and readiness surfaces have been checked.
-
-- Discover the current Crew configuration, capabilities, activation state and
-  readiness before delegating substantial work. Installed, configured, enabled
-  and callable are different states; do not infer one from another.
-- Match a bounded work unit to an available Crew role/model and preserve the
-  repository/worktree and Result Contract boundaries. Keep planning, ambiguous
-  requirements, integration, external side effects and final communication in
-  the host agent.
-- Dispatch selected work asynchronously with `dsh_spawn_worker`, save its
-  workflow ID, and poll that same workflow with `dsh_worker_result` using
-  `wait_seconds: 10`. A bounded wait that returns a nonterminal state is not a
-  failure when `dsh_worker_status` confirms that workflow is still running;
-  continue polling it and never start a duplicate workflow.
-- If Crew is selected and any required capability is unavailable, non-callable,
-  or returns an unknown/runtime/configuration/credential/routing/timeout error,
-  pause. Report the evidence and wait for the operator to choose repair Crew or
-  continue locally; do not repair/reconfigure, silently fall back or retry blindly
-  before that decision. A nonterminal bounded wait is not a transport timeout.
-- Validate returned evidence, changed scope, tests and completion state before
-  accepting delegated work. Do not expose credentials or raw provider payloads.
-- Continue the authorized task after a successful subtask; do not stop at its
-  checkpoint. Missing evidence or requested review changes are not approval.
-
-## Harness upgrade redlines
-
-- Never install, update, register, unlink, repair, or mutate anything under ~/.dsh.
-- DSH Crew runtime upgrades must go through the Crew-owned installer and DSH_HOME.
-- Never use direct pnpm/npm/dsh plugin operations against the official web profile.
-- Preparing a Harness upgrade must not restart 3080 or 3210.
-- Standalone workers launch through the official DSH SDK profile contract; dsh-sdk-jsonrpc-demo is obsolete.
-- Legacy 3080 bridge must never be used for 3210 lifecycle/restart/rollback.
-
-This file is installed as a managed block in `~/.zcode/AGENTS.md`; user-authored
-instructions outside the block are preserved.