@ran-sh/dsh-crew 1.8.0 → 1.9.1

package/docs/installation.md

@@ -1,138 +1,138 @@
-# Installation plan
-
-DSH Crew is a plugin for the official DeepSeek Harness and uses an explicit
-installer. Merely installing the npm package does not mutate the host.
-The managed production supervisor is currently supported on Windows; Linux and
-macOS are not yet production runtime targets.
-
-## Recommended path
-
-```bash
-npm install -g @ran-sh/dsh-crew@latest
-dsh-crew install
-```
-
-The installer registers the plugin in a dedicated official Harness
-`profile: dsh-crew` served on 3210. This is the canonical Crew control and
-execution surface; it is not a separate or forked Harness product.
-
-Desktop `--open` starts or reuses the separately installed official CLI's web
-frontend on 3080, then ensures Crew runs hidden on 3210. It never opens the 3210
-browser automatically. Install the official CLI separately so `dsh.cmd` is on
-PATH. Login startup and `--background` remain Crew-only.
-The launcher adds a Crew-owned overlay pointing to an immutable small frontend
-snapshot. It supplies the simple panel and the link to 3210; the backend links
-back to 3080. An already-running official instance without that overlay must be
-reloaded when idle; the desktop launcher does not terminate existing official work.
-
-To test GitHub `main` before an npm release:
-
-```bash
-git clone https://github.com/Ran-sh/dsh-crew.git
-cd dsh-crew
-node scripts/setup.mjs install
-node scripts/setup.mjs status
-```
-
-## Managed surfaces
-
-| Surface | Installed behavior | Uninstall behavior |
-| --- | --- | --- |
-| Crew plugin runtime | Official DeepSeek Harness isolated in `~/.config/dsh-crew/harness`, profile: dsh-crew, with the Crew plugin registered | Plugin registration removed; config kept unless `--purge` |
-| Codex MCP and roles | Points Worker, Reviewer, and MCP to the installed release | Only DSH Crew entries are removed |
-| Global Codex policy | Managed block inside `~/.codex/AGENTS.md` | Only the managed block is removed |
-| ZCode MCP, agents and commands | Installs `~/.zcode/AGENTS.md`, `agents/{ds-worker,ds-reviewer}.md`, commands and a source-aware `dsh-crew` MCP entry | Only DSH Crew-owned files/entry are removed |
-| Windows login startup | `DSH Crew.vbs`, `start-dsh-crew.cmd`, `start-dsh-crew.ps1`, the exact process controller, and its hash manifest | Only DSH Crew-owned files are removed; foreign pre-existing content at those exact paths is preserved or fails closed |
-| Official 3080 UI | Desktop launch starts/reuses the official program; Crew installer does not register plugins in its profile | Left running and untouched by Crew uninstall |
-
-The Windows launcher supervises only the Crew-owned 3210 service, so provider
-restart and rollback operations have one verifiable supervisor. The official
-3080 surface never starts, owns, or supervises 3210. The launcher does not
-store credentials.
-
-`dsh-crew install`, `update`, and `rollback` automatically perform an exact,
-crash-resumable watcher handoff after the payload transaction. The updater
-reserves handoff ownership before releasing its update lock, resumes any
-unfinished handoff first, and succeeds only after the isolated 3210 runtime
-reports the expected Crew and DSH versions.
-
-On Windows, installation registers login startup. To start immediately and
-open the Crew control:
-
-```powershell
-& "$env:USERPROFILE\.config\dsh-crew\launchers\start-dsh-crew.cmd" --open
-```
-
-Then verify <http://127.0.0.1:3210/> answers the Crew extension contract.
-
-```bash
-dsh-crew status
-dsh-crew inspect
-```
-
-ZCode uses `~/.zcode/cli/config.json` when it already has native MCP servers. If
-that native list is empty, the installer uses `~/.agents/mcp.json`; unrelated
-servers are preserved and a conflicting unowned `dsh-crew` entry fails closed.
-
-## Verification
-
-```bash
-dsh-crew status
-dsh-crew inspect
-dsh-crew jobs list
-```
-
-Source checkout verification:
-
-```bash
-node --test test/*.test.mjs
-pnpm run build:client
-npm pack --dry-run
-```
-
-## Harness CLI selection
-
-The Crew launcher and the 3210 Hub boot from one Crew-managed Harness entry,
-chosen in this order:
-
-1. `DSH_CREW_DSH_CLI`, when set to an explicit `@deepseek-ai/dsh` entry.
-2. The Crew-managed npm runtime at `<crew home>/runtime` (the normal install
-   path, written by `dsh-crew update`). It carries whatever cohort the installed
-   Crew release pinned; the launcher never substitutes a different version.
-3. A Crew-managed source cohort, discovered through a
-   `<crew home>/runtime-source-<label>.json` sidecar. The sidecar's recorded
-   `version` must equal the checkout's own `apps/cli/package.json`, so a stale
-   sidecar can never pin a half-updated tree.
-
-For the npm runtime the launcher uses the Crew home as `DSH_HOME`; a source
-cohort is its own home, because its profiles, sessions and settings live inside
-that tree. The launcher then derives `dsh_version` from the verified
-`@deepseek-ai/dsh` manifest and requires the Hub to report that same version, so
-a process left over from a previous cohort is never treated as healthy.
-
-Only override `DSH_CREW_DSH_CLI` deliberately — it wins over the managed runtime.
-Never point it at the official `~/.dsh` tree, which the Crew launcher treats as a
-read-only boundary.
-
-To build a source cohort instead of the npm runtime (for example to test an
-unpublished tag), clone the tag into `<crew home>/runtime-source-<label>`, build
-its CLI, and write the matching sidecar. On Windows a source install needs the
-native toolchain for its `fs-ext` dependency; a failed native build is reported
-as a runtime failure rather than silently falling back to another cohort.
-
-## Rollback vs uninstall
-
-```bash
-dsh-crew releases list
-dsh-crew rollback <version>
-```
-
-Use `dsh-crew rollback <version>` to switch the retained payload and verify the
-3210 runtime. Use `dsh-crew uninstall` only to remove managed files (backups and
-config are kept unless `--purge` is passed).
-
-```bash
-dsh-crew uninstall
-```
-
-Use `dsh-crew uninstall --purge` only when configuration and backups should also be deleted.
+# Installation plan
+
+DSH Crew is a plugin for the official DeepSeek Harness and uses an explicit
+installer. Merely installing the npm package does not mutate the host.
+The managed production supervisor is currently supported on Windows; Linux and
+macOS are not yet production runtime targets.
+
+## Recommended path
+
+```bash
+npm install -g @ran-sh/dsh-crew@latest
+dsh-crew install
+```
+
+The installer registers the plugin in a dedicated official Harness
+`profile: dsh-crew` served on 3210. This is the canonical Crew control and
+execution surface; it is not a separate or forked Harness product.
+
+Desktop `--open` starts or reuses the separately installed official CLI's web
+frontend on 3080, then ensures Crew runs hidden on 3210. It never opens the 3210
+browser automatically. Install the official CLI separately so `dsh.cmd` is on
+PATH. Login startup and `--background` remain Crew-only.
+The launcher adds a Crew-owned overlay pointing to an immutable small frontend
+snapshot. It supplies the simple panel and the link to 3210; the backend links
+back to 3080. An already-running official instance without that overlay must be
+reloaded when idle; the desktop launcher does not terminate existing official work.
+
+To test GitHub `main` before an npm release:
+
+```bash
+git clone https://github.com/Ran-sh/dsh-crew.git
+cd dsh-crew
+node scripts/setup.mjs install
+node scripts/setup.mjs status
+```
+
+## Managed surfaces
+
+| Surface | Installed behavior | Uninstall behavior |
+| --- | --- | --- |
+| Crew plugin runtime | Official DeepSeek Harness isolated in `~/.config/dsh-crew/harness`, profile: dsh-crew, with the Crew plugin registered | Plugin registration removed; config kept unless `--purge` |
+| Codex MCP and roles | Points Worker, Reviewer, and MCP to the installed release | Only DSH Crew entries are removed |
+| Global Codex policy | Managed block inside `~/.codex/AGENTS.md` | Only the managed block is removed |
+| ZCode MCP, agents and commands | Installs `~/.zcode/AGENTS.md`, `agents/{ds-worker,ds-reviewer}.md`, commands and a source-aware `dsh-crew` MCP entry | Only DSH Crew-owned files/entry are removed |
+| Windows login startup | `DSH Crew.vbs`, `start-dsh-crew.cmd`, `start-dsh-crew.ps1`, the exact process controller, and its hash manifest | Only DSH Crew-owned files are removed; foreign pre-existing content at those exact paths is preserved or fails closed |
+| Official 3080 UI | Desktop launch starts/reuses the official program; Crew installer does not register plugins in its profile | Left running and untouched by Crew uninstall |
+
+The Windows launcher supervises only the Crew-owned 3210 service, so provider
+restart and rollback operations have one verifiable supervisor. The official
+3080 surface never starts, owns, or supervises 3210. The launcher does not
+store credentials.
+
+`dsh-crew install`, `update`, and `rollback` automatically perform an exact,
+crash-resumable watcher handoff after the payload transaction. The updater
+reserves handoff ownership before releasing its update lock, resumes any
+unfinished handoff first, and succeeds only after the isolated 3210 runtime
+reports the expected Crew and DSH versions.
+
+On Windows, installation registers login startup. To start immediately and
+open the Crew control:
+
+```powershell
+& "$env:USERPROFILE\.config\dsh-crew\launchers\start-dsh-crew.cmd" --open
+```
+
+Then verify <http://127.0.0.1:3210/> answers the Crew extension contract.
+
+```bash
+dsh-crew status
+dsh-crew inspect
+```
+
+ZCode uses `~/.zcode/cli/config.json` when it already has native MCP servers. If
+that native list is empty, the installer uses `~/.agents/mcp.json`; unrelated
+servers are preserved and a conflicting unowned `dsh-crew` entry fails closed.
+
+## Verification
+
+```bash
+dsh-crew status
+dsh-crew inspect
+dsh-crew jobs list
+```
+
+Source checkout verification:
+
+```bash
+node --test test/*.test.mjs
+pnpm run build:client
+npm pack --dry-run
+```
+
+## Harness CLI selection
+
+The Crew launcher and the 3210 Hub boot from one Crew-managed Harness entry,
+chosen in this order:
+
+1. `DSH_CREW_DSH_CLI`, when set to an explicit `@deepseek-ai/dsh` entry.
+2. The Crew-managed npm runtime at `<crew home>/runtime` (the normal install
+   path, written by `dsh-crew update`). It carries whatever cohort the installed
+   Crew release pinned; the launcher never substitutes a different version.
+3. A Crew-managed source cohort, discovered through a
+   `<crew home>/runtime-source-<label>.json` sidecar. The sidecar's recorded
+   `version` must equal the checkout's own `apps/cli/package.json`, so a stale
+   sidecar can never pin a half-updated tree.
+
+For the npm runtime the launcher uses the Crew home as `DSH_HOME`; a source
+cohort is its own home, because its profiles, sessions and settings live inside
+that tree. The launcher then derives `dsh_version` from the verified
+`@deepseek-ai/dsh` manifest and requires the Hub to report that same version, so
+a process left over from a previous cohort is never treated as healthy.
+
+Only override `DSH_CREW_DSH_CLI` deliberately — it wins over the managed runtime.
+Never point it at the official `~/.dsh` tree, which the Crew launcher treats as a
+read-only boundary.
+
+To build a source cohort instead of the npm runtime (for example to test an
+unpublished tag), clone the tag into `<crew home>/runtime-source-<label>`, build
+its CLI, and write the matching sidecar. On Windows a source install needs the
+native toolchain for its `fs-ext` dependency; a failed native build is reported
+as a runtime failure rather than silently falling back to another cohort.
+
+## Rollback vs uninstall
+
+```bash
+dsh-crew releases list
+dsh-crew rollback <version>
+```
+
+Use `dsh-crew rollback <version>` to switch the retained payload and verify the
+3210 runtime. Use `dsh-crew uninstall` only to remove managed files (backups and
+config are kept unless `--purge` is passed).
+
+```bash
+dsh-crew uninstall
+```
+
+Use `dsh-crew uninstall --purge` only when configuration and backups should also be deleted.

package/docs/job-contracts.md

@@ -1,85 +1,85 @@
-# Job contracts and information flow
-
-DSH Crew is a narrow bridge and scheduler. Codex or Claude owns the main task;
-Crew owns one delegated Worker/Reviewer workflow and reports auditable evidence
-back to the caller.
-
-## Information flow
-
-```text
-caller objective
-  -> Worker in isolated workspace
-  -> structured outcome + candidate reference
-  -> optional Reviewer inspects the workspace directly
-  -> compact Result Contract + canonical job events
-  -> caller
-```
-
-The Worker receives the complete delegated objective. After it finishes, Crew
-does not copy the Worker's raw prose or full patch into the Reviewer prompt.
-The Reviewer receives a bounded capsule containing the objective, reported
-changes/tests/risks, changed-file names, base revision, and candidate
-fingerprint. It opens the relevant files and runs `git diff` in the isolated
-workspace when deeper inspection is needed.
-
-The Hub keeps only the latest assistant message needed as the final Delivery
-Report. It does not retain an ever-growing list of intermediate assistant
-messages.
-
-## Canonical events
-
-Every workflow result can expose a versioned, ordered `canonical_events` list.
-Each event has `schema_version`, `event_id`, `job_id`, `sequence`, `type`, `at`,
-`role`, `attempt`, and bounded structured `data`.
-
-Supported event types (the allow-list is versioned; `approval.required` is
-reserved for a future approval broker and is not emitted by the current
-runtime):
-
-- `job.created`, `job.started`
-- `model.selected`, `model.fallback`
-- `worker.started`, `worker.completed`
-- `review.started`, `review.completed`
-- `approval.required`
-- `job.completed`, `job.failed`, `job.cancelled`
-
-Events never carry a candidate patch, raw provider payload, credential, or full
-assistant response. `event_cursor` identifies the latest event in status views.
-
-## Result Contract
-
-`dsh_run_worker` and `dsh_worker_result` default to `detail: "compact"`. Their
-`evidence` object contains:
-
-- `status`: `PASS`, `FAIL`, `PARTIAL`, or `BLOCKED`
-- structured execution/test/delivery/review summary
-- bounded model-selection trace
-- changed files, reported changes, tests, risks, and unverified checks
-- reviewer verdict and evidence when review ran
-- candidate fingerprint/base revision and workspace recovery state
-- bounded machine error code/message when execution failed
-
-Raw worker prose and candidate patch text are excluded. For an explicit debug
-or recovery operation, pass `detail: "full"`; this preserves the previous rich
-workflow view and adds the same evidence envelope.
-
-## Profiles, Workspace Context, and watch
-
-Both blocking and asynchronous MCP dispatch accept optional `job_id`, `profile`,
-`workspace`, `constraints`, `workspace_id`, and `context_refs` fields. The
-caller id is echoed as `client_job_id`; it never replaces Crew's internal id.
-Profiles control role-compatible
-routing, isolation, timeout, fallback, and review strictness. Workspace Context
-adds bounded project facts by reference; instruction file contents are opened by
-the Agent in the workspace rather than copied through the hand-off.
-
-`dsh_worker_result` accepts `after_sequence`. The response includes only newer
-`canonical_events` plus the current numeric `event_cursor`, so callers can watch
-long jobs without replaying the entire event history.
-
-The isolated Hub also exposes `/extension`, `/profiles`, `/workspaces`,
-`/jobs/:id/contract`, and `/jobs/:id/events`. All remain loopback-only.
-
+# Job contracts and information flow
+
+DSH Crew is a narrow bridge and scheduler. Codex or Claude owns the main task;
+Crew owns one delegated Worker/Reviewer workflow and reports auditable evidence
+back to the caller.
+
+## Information flow
+
+```text
+caller objective
+  -> Worker in isolated workspace
+  -> structured outcome + candidate reference
+  -> optional Reviewer inspects the workspace directly
+  -> compact Result Contract + canonical job events
+  -> caller
+```
+
+The Worker receives the complete delegated objective. After it finishes, Crew
+does not copy the Worker's raw prose or full patch into the Reviewer prompt.
+The Reviewer receives a bounded capsule containing the objective, reported
+changes/tests/risks, changed-file names, base revision, and candidate
+fingerprint. It opens the relevant files and runs `git diff` in the isolated
+workspace when deeper inspection is needed.
+
+The Hub keeps only the latest assistant message needed as the final Delivery
+Report. It does not retain an ever-growing list of intermediate assistant
+messages.
+
+## Canonical events
+
+Every workflow result can expose a versioned, ordered `canonical_events` list.
+Each event has `schema_version`, `event_id`, `job_id`, `sequence`, `type`, `at`,
+`role`, `attempt`, and bounded structured `data`.
+
+Supported event types (the allow-list is versioned; `approval.required` is
+reserved for a future approval broker and is not emitted by the current
+runtime):
+
+- `job.created`, `job.started`
+- `model.selected`, `model.fallback`
+- `worker.started`, `worker.completed`
+- `review.started`, `review.completed`
+- `approval.required`
+- `job.completed`, `job.failed`, `job.cancelled`
+
+Events never carry a candidate patch, raw provider payload, credential, or full
+assistant response. `event_cursor` identifies the latest event in status views.
+
+## Result Contract
+
+`dsh_run_worker` and `dsh_worker_result` default to `detail: "compact"`. Their
+`evidence` object contains:
+
+- `status`: `PASS`, `FAIL`, `PARTIAL`, or `BLOCKED`
+- structured execution/test/delivery/review summary
+- bounded model-selection trace
+- changed files, reported changes, tests, risks, and unverified checks
+- reviewer verdict and evidence when review ran
+- candidate fingerprint/base revision and workspace recovery state
+- bounded machine error code/message when execution failed
+
+Raw worker prose and candidate patch text are excluded. For an explicit debug
+or recovery operation, pass `detail: "full"`; this preserves the previous rich
+workflow view and adds the same evidence envelope.
+
+## Profiles, Workspace Context, and watch
+
+Both blocking and asynchronous MCP dispatch accept optional `job_id`, `profile`,
+`workspace`, `constraints`, `workspace_id`, and `context_refs` fields. The
+caller id is echoed as `client_job_id`; it never replaces Crew's internal id.
+Profiles control role-compatible
+routing, isolation, timeout, fallback, and review strictness. Workspace Context
+adds bounded project facts by reference; instruction file contents are opened by
+the Agent in the workspace rather than copied through the hand-off.
+
+`dsh_worker_result` accepts `after_sequence`. The response includes only newer
+`canonical_events` plus the current numeric `event_cursor`, so callers can watch
+long jobs without replaying the entire event history.
+
+The isolated Hub also exposes `/extension`, `/profiles`, `/workspaces`,
+`/jobs/:id/contract`, and `/jobs/:id/events`. All remain loopback-only.
+
 Per-job precedence is request `constraints` > Profile > session defaults.
 `workspace.branch` pins the isolated base revision; `workspace.worktree` accepts
 `auto`, `existing`, or `none`. Workspace preflight reports `READY`, `CONFLICT`,
@@ -92,24 +92,24 @@ changed files, a complete Delivery Report, at least one passing evidence check,
 and no failed check. If the Worker reports no changes but the workspace contains
 edits—or reports changes while the workspace is empty—the workflow fails closed
 with workspace-evidence mismatch.
-
-The CLI is a JSON projection of the same local HTTP surface:
-
-```text
-dsh-crew jobs list
-dsh-crew jobs get <job-id> --detail compact
-dsh-crew jobs watch <job-id> --after <sequence>
-dsh-crew jobs cancel <job-id>
-dsh-crew jobs submit --request job.json
-```
-
-## Compatibility boundary
-
-The internal legacy phase events remain in the explicit full view for current
-debug consumers. Canonical events and the compact Result Contract are the
-stable integration surface for new Codex, Claude, CLI, and HTTP consumers.
-
-This design borrows the useful boundary from
-[OpenMausBot](https://github.com/milind-soni/OpenMausBot)—a small provider
-contract and one normalized event stream—without adopting its desktop chat,
-bot roster, persona, connector, or general-purpose agent-platform scope.
+
+The CLI is a JSON projection of the same local HTTP surface:
+
+```text
+dsh-crew jobs list
+dsh-crew jobs get <job-id> --detail compact
+dsh-crew jobs watch <job-id> --after <sequence>
+dsh-crew jobs cancel <job-id>
+dsh-crew jobs submit --request job.json
+```
+
+## Compatibility boundary
+
+The internal legacy phase events remain in the explicit full view for current
+debug consumers. Canonical events and the compact Result Contract are the
+stable integration surface for new Codex, Claude, CLI, and HTTP consumers.
+
+This design borrows the useful boundary from
+[OpenMausBot](https://github.com/milind-soni/OpenMausBot)—a small provider
+contract and one normalized event stream—without adopting its desktop chat,
+bot roster, persona, connector, or general-purpose agent-platform scope.