dsh-any-agent 0.3.9 → 0.5.0

package/docs/en/security.md

@@ -0,0 +1,59 @@
+> Back to [README](../../README.md)
+
+# 🔐 Permissions
+
+| Tier | Approval default | Use for |
+|---|---|---|
+| `danger-full-access` (raw server default) | `auto-allow` | Zero friction; `setup` writes `workspace-write` by default |
+| `workspace-write` | `auto-allow` | Writes are limited to the workspace by DSH's sandbox; out-of-workspace requests are auto-allowed unless you pass `on_approval=ask` |
+| `read-only` | `auto-deny` | Analyzing untrusted samples (malware, unknown dumps) |
+
+`on_approval` can be `auto-allow`, `auto-deny`, or `ask` (which exposes a pending approval for `dsh_approval_decide` to adjudicate).
+
+**`read-only` is enforced, not merely a default**: it always runs with `auto-deny`; passing `auto-allow` or `ask` for a read-only conversation is rejected at `dsh_start`, and the approval layer refuses any permission request from a read-only conversation. After create/resume the server reads back the session's recorded tier; for read-only it **fails closed** if the projection cache has no permission record within the DSH flush window, rather than relying on the approval layer alone. Without that, a profile `defaultPreset` plus a permissive approval policy could let a write through (found by the adversarial audit).
+
+## 🪟 Workspace visibility in the DSH GUI
+
+Two different things — don't confuse them:
+
+| | Depends on | Status |
+|---|---|---|
+| **Workspace effectiveness** | the conversation's `cwd` | ✅ Always correct. Process working directory, file placement and sandbox write root all follow it |
+| **GUI grouping** | `sessionIds` in `~/.dsh/storages/workspace.json` | ⚠️ This server registers it, but **the running DSH server caches the registry in memory** — external file edits only take effect after a DSH restart |
+
+Verified experimentally ([`test/workspace-effect.mjs`](../../test/workspace-effect.mjs)): two conversations in two desktop folders, given **no path at all**, each wrote its file into its own workspace, self-reported the correct working directory, and leaked nothing into the server's cwd / home / temp / the other workspace (24/24 checks).
+
+Maintenance CLI:
+
+```bash
+node bin/dsh-any-agent-workspaces.mjs --list                  # inspect the registry
+node bin/dsh-any-agent-workspaces.mjs --backfill              # register every session found on disk
+node bin/dsh-any-agent-workspaces.mjs --prune-temp            # drop temp-directory entries
+node bin/dsh-any-agent-workspaces.mjs --prune-empty           # drop empty workspaces whose path is gone
+node bin/dsh-any-agent-workspaces.mjs --purge-test-sessions   # delete test sessions (strict rules)
+```
+
+> ⚠️ Before restarting DSH, **don't touch workspaces in the GUI** — the server will write its in-memory state back over the file.
+
+## 🕶️ Logging and privacy
+
+Silent by default — **not one byte is written**.
+
+1. MCP's **stdout is the protocol channel**; anything mixed in corrupts the stream.
+2. This server is launched by Claude/Codex, so its stderr lands in *their* logs.
+3. DSH's own stderr may carry model output **including reasoning**, so it is never forwarded by default.
+
+| Level | Behavior |
+|---|---|
+| `silent` (default) | nothing at all |
+| `info` | this server's own lifecycle events only — **never any DSH output** |
+| `debug` | more of our own events; still no DSH output |
+| `DSH_MCP_LOG_STDERR=1` | additionally forward DSH's raw stderr (**may contain reasoning**) |
+
+**This server never writes reasoning to disk** — with exactly one deliberate exception:
+
+- Not in logs (silent by default). The state file and the per-conversation metadata sidecars under `<state dir>/meta/` hold metadata only (id, cwd, permissions, counters, title hint) — a smoke-test assertion guards the registry.
+- **The async completion sentinel persists the answer, usage and tool inputs** (it must, so a caller can collect offline) but **strips `result.thinking`** and always reports `thinking_omitted` (true when reasoning was removed, false when there was none). Tool inputs are passed through the same credential redaction as approvals, but the sentinel still contains commands and file contents — treat it as sensitive. A test asserts that even when `reasoning=full` is requested, no reasoning text appears in the sentinel — while `dsh_get(run_id)` still returns it from memory. Set `DSH_MCP_SENTINEL_INCLUDE_REASONING=1` to break this on purpose.
+- Sentinels are pruned after 7 days by default (`DSH_MCP_SENTINEL_TTL_MS`; `0` keeps them forever).
+
+> ⚠️ **DSH writes its own session log under `~/.dsh/sessions` and that log contains the full reasoning text** (even with `reasoning=hide`). It is what makes resume possible and is outside this server's control. The absolute "reasoning never reaches disk" claim applies to *this server's* artifacts only.

package/docs/en/team.md

@@ -0,0 +1,74 @@
+> Back to [README](../../README.md)
+
+# 🧑‍🤝‍🧑 Team mode (opt-in)
+
+**Off by default since 0.5.0.** Turn it on with one command; no client config editing.
+
+When enabled: the profile switches to `dsh-team` (the experimental Agent Teams
+packages, with the legacy `subagent` tools disabled), and `dsh_send` adds a short
+"form a team if this needs parallel or multi-role work" line; simple tasks are not
+forced into a team.
+
+## Commands
+
+```bash
+dsh-any-agent team on       # enable (writes settings.json)
+dsh-any-agent team off      # disable
+dsh-any-agent team status   # show the effective value, source and profile
+```
+
+`team on/off` writes the `team` field in `<DSH_HOME>/.dsh-any-agent/settings.json`;
+it does **not** touch client configs. Reconnect the MCP server (or restart the
+client) for the change to take effect.
+
+## Enable
+
+1. Run:
+
+   ```bash
+   dsh-any-agent team on
+   ```
+
+2. Reconnect: in Claude Code, `/mcp` → `dsh-any-agent` → reconnect; other clients
+   restart or reconnect in their MCP panel.
+3. Verify: `dsh_start` should report:
+
+   ```
+   Team mode: on (profile=dsh-team; dispatch prompts suggest a team when needed)
+   ```
+
+   or run `dsh_doctor` and look for the `team` check (`on`).
+
+## Disable
+
+```bash
+dsh-any-agent team off
+```
+
+After reconnecting, the profile is back to `dsh-mcp`: no team tools, no injection.
+
+**One call only** (profile stays `dsh-team`):
+
+```
+dsh_send(..., team=false)
+```
+
+## Precedence
+
+1. `DSH_MCP_TEAM` environment variable (`1` / `0`) — **highest**;
+2. the `team` field in `settings.json`;
+3. off by default.
+
+If an older client config still carries `DSH_MCP_TEAM`, it overrides `team on/off`.
+`dsh-any-agent team status` shows the source (`env` / `file` / `default`), and
+`team on/off` warns when the env var is present.
+
+## Notes
+
+- Team mode requires DSH `>= 0.1.7-0`; an older runtime stays off even after
+  `team on`, and `dsh_doctor` marks it `warn`.
+- The team profile disables the legacy `subagent` tools and replaces them with
+  nine team tools; teammates share one workspace.
+- Agent Teams is **experimental** and carries no stability promise.
+- You do not need to delete `~/.dsh/profiles/dsh-team`; it is simply unused when
+  team mode is off.

package/docs/en/tests.md

@@ -0,0 +1,96 @@
+> Back to [README](../../README.md)
+
+# 🧪 Tests
+
+```bash
+npm test                   # offline suites; smoke skips DSH sections if no DSH
+npm run test:all           # offline + model-backed suites (needs DSH/provider)
+node test/cleanup.mjs      # suite teardown on its own (test-created dirs only; --dry-run to preview)
+```
+
+Model-backed suites are not part of the hosted CI matrix (they need a real DSH
+install and provider credentials). Run them locally, or dispatch the
+`model-suites` workflow with a self-hosted runner that has DSH configured.
+
+The suite **cleans up after itself**: `run.mjs` always ends with `cleanup.mjs`, which removes sessions and workspace registrations whose cwd is **a test-created directory** (`tmpdir()/dsh-any-agent-*` or `Desktop/dsh-any-agent-test-*`). Real project sessions — including projects under `%TEMP%` — and your live state directory are never touched. To remove `Desktop/dsh-any-agent-test-*` artifacts explicitly, run `node bin/dsh-any-agent-workspaces.mjs --purge-test-sessions`.
+
+| Suite | Checks | Covers |
+|---|---|---|
+| `smoke` | 29 | handshake, tool table, conversation creation, config, registry purity |
+| `boundary` | 46 | protocol edges (double initialize, malformed lines, unknown method), argument validation (including read-only + permissive approval rejection, unknown provider/model, and no stale write-lock marker on a failed create), unknown ids, cursor edges, lifecycle idempotence, unicode |
+| `integration` | 30 | resume-with-memory across processes, interrupt, both interject modes |
+| `async` | 16 | fire-and-forget + later collection |
+| `sentinel` | 36 | completion sentinel: atomicity, latch semantics, per-conversation namespacing under concurrency, cancelled runs still land it, and **reasoning never reaching the file** |
+| `prune` | 11 | **sentinel retention**: prunes over-age and crash-leftover files, keeps fresh ones, removes empty shells, `TTL=0` disables pruning, and never touches the conversation registry beside it (no tokens, runs every time) |
+| `guards` | 40 | **environment-variable guards**: odd numbers always land on the safe side — `IDLE_TTL_MS=-1` means "never reap", garbage/empty falls back to the 10-minute default, a too-small reap interval falls back to the default (no busy loop), and the **lost-holder threshold is floored at 30 s** (so another instance cannot "legitimately" preempt and kill our turn); plus the team-mode default and precedence (`DSH_MCP_TEAM` > `settings.json` > off) (no tokens, runs every time) |
+| `sandbox-guard` | 21 | **the test sandbox itself**: a "throwaway HOME" that resolves to the real user profile, to the filesystem root, or to anywhere outside the OS temp dir is refused with an error instead of being written to and deleted. Every other suite builds its HOME through `test/sandbox-home.mjs` and can only destroy what it created there (no tokens, runs every time) |
+| `approval-details` | 27 | **approval review context**: the pending-approval snapshot carries the command, reason, cwd and original approval ID — not just a bare ID — so a caller can actually adjudicate; missing `rawInput` is correlated from the earlier `tool_call` update by ID; credential-shaped fields and common inline literals are redacted; closing a conversation cancels pending approvals. Verified end-to-end over real stdio MCP |
+| `failure-terminal` | 11 | **terminal state on failure**: an `ensureAlive` failure wakes `dsh_interject` waiters, writes an `error` sentinel, and attaches `runId` to the error; an approval with no matching option reports `effective=cancelled` instead of a fake allow; `dsh_get` reads a run back from its sentinel (no tokens) |
+| `shared-host` | 25 | **shared process host**: notifications and permission requests route by `sessionId`, unknown-session approvals are cancelled, a process exit fans out to every attached conversation, the child stops only when the last conversation detaches; **on by default and switchable off with `=0`** (an empty value counts as unset); the pre-takeover collision check for a shared process; RSS helper (no tokens) |
+| `shared-process` | 8 (skips without DSH) | **real-DSH shared process**: two conversations with the same `(cwd, permission)` share one PID, closing one leaves the other alive, closing both clears the host and exits the PID (needs a local DSH; runs with `--all`) |
+| `dispatch-tools` | 31 | **dispatch surface**: `dsh_inbox` aggregates pending approvals across conversations, `client_run_id` idempotency hits and evicts with its run, queue list/update/promote/remove (remove writes a cancelled sentinel), `dsh_get(max_chars)` truncates only the text while structured keeps the full answer, audit records metadata only, `dsh_doctor` essential checks (no tokens) |
+| `line-decoder` | 4 | **UTF-8 line framing**: multi-byte characters split across MCP/ACP stream chunks are preserved (no U+FFFD), including CRLF and EOF-without-newline (no tokens) |
+| `read-cursor` | 10 | **`dsh_read` cursor semantics**: text appended to an already-read entry is delivered again (revision cursor, match by `seq`), and `limit` is clamped to 1..500 so `0`/negative cannot spin or drop the tail (no tokens) |
+| `sentinel-redaction` | 19 | **sentinel disk hygiene**: `result.thinking` is stripped, `thinking_omitted` is always a boolean, and `answer`/`error`/`title`/`tools_used[].input` all pass the same credential redaction as approvals (no tokens) |
+| `forget-tombstone` | 10 | **`forget` is terminal**: `release(forget=true)` writes a tombstone, by-id lookups fail with a recovery path, lists exclude it, and deleting the tombstone restores the normal unknown-session path (no tokens) |
+| `bootstrap-profile` | 24 | **first-start profile works in the published zero-dependency form**: copies routing with the built-in YAML subset parser, strips `apiKey`/`headers`/literal secrets, never writes `defaultPreset`, is idempotent, and leaves a user-maintained profile byte-identical (no tokens) |
+| `workspace-safety` | 23 | **data-loss boundaries**: `isTempPath` is segment-aware (`tmpdir()+'Suffix'` and `/tmpfoo` are *not* temp), a corrupt `workspace.json` is never overwritten, an unreadable session root never wipes `sessionIds`, and automatic cleanup deletes only test-created sessions (no tokens) |
+| `permission-adopt` | 17 | **no silent privilege escalation**: adopting an external session with no permission record fails closed to `read-only`; a recorded `read-only` cannot be promoted by the sidecar; the runtime read-back rejects a recorded/requested mismatch (no tokens) |
+| `state-safety` | 26 | **state/sentinel/lock storage**: defaults live under `$DSH_HOME/.dsh-any-agent`, an unwritable directory fails startup loudly, sentinel write failures return `null` + `sentinel_error`, and bad numeric env values land on the safe side (no tokens) |
+| `setup` | 45 | **the registration CLI**: preview writes nothing, `--remove` takes out only its own entry, an absent client is skipped rather than failed, the Codex TOML block round-trips, and the command recorded in a config is actually spawned and must answer `initialize` (no tokens). It never invokes `claude mcp get` — that CLI rewrites `~/.claude.json` |
+| `removal-scope` | 24 | **unregistering touches only its own entry**: configs holding unrelated MCP servers, top-level Codex settings and sibling Zed settings are registered and then removed, asserting every other value is byte-identical; removing something never written is a no-op with no write (no tokens) |
+| `config-safety` | 407 | **the property the 0.3 line is about**, per client: preview leaves files byte-identical with no `.bak`; register-then-remove restores every other entry byte-for-byte, keeps key order and drops no top-level key; 4-space / 2-space indentation, single-line JSON, missing trailing newline, CRLF and a UTF-8 BOM all survive a write; malformed JSON and read-only files are refused without damage; the second `--yes` is a no-op with no new backup; every `.bak-dsh-<stamp>` appears once and equals the pre-write bytes; a `claude` on PATH is never invoked (no tokens) |
+| `real-configs` | 84 (66 with 7/9, 48 with 5/9 fixtures) | **round-trip on the real thing**: copies this machine's actual client configs (an 182693-byte `~/.claude.json` holding hundreds of `projects` entries and case-colliding keys, a 238-line Codex TOML, Zed's full `settings.json`) into a temp dir, registers, then removes, and requires every file back **byte for byte**; entry-presence is checked by key (not a bare substring), and missing fixtures are reported as skipped rather than green (no tokens) |
+| `commit-script` | 26 | commit messages go through stdin, never a temp file that `git add -A` could capture (no tokens) |
+| `roots` | 12 | `dsh_start` without `cwd` asks the client for MCP roots; a client without roots gets an actionable error (no tokens) |
+| `workspace-titles` | 15 | home-as-workspace is rejected before DSH starts; `title_hint` is returned separately from DSH's automatic title (no tokens) |
+| `package-check` | 14 | `files` whitelist, zero runtime dependencies, Node floor, and bin shebangs (no tokens) |
+| `timeout` | 38 | **timeout semantics**: `wait=false` is unaffected by `timeout_ms`; a `wait=true` expiry merely downgrades to background (turn not cancelled, result not lost, `busy` never lies); `timeout_ms<=0` waits forever; a failed resume invalidates the process instead of wedging the conversation; an empty prompt yields a clear error |
+| `lock` | 79 | **write lock and preemption**: four holder classifications, `writeMarker` never overwriting a live holder, malformed/missing registration edge cases; **end-to-end** with two real MCP instances fighting over one conversation → clear error → refusal → `force` takeover; **a crash releases the lock automatically**, **a wedged holder is preempted without `force`**; plus the "one turn, one sentinel" invariant (inline turns and idle interjects included) |
+| `cycle` | 36 | **the async dispatch lifecycle**: dispatch → collect the sentinel → idle reap → dispatch again, three rounds with no lock error; re-dispatch right on the reap boundary (widening the race); an immediate re-dispatch after `dsh_release`; and an assertion that reaping leaves no unattributable lock (this suite caught the reaper collecting a freshly spawned process as if it were idle) |
+| `concurrency` | 31 | three simultaneous conversations + live incremental reads |
+| `capability` | 22 | writing code, running scripts, **spawning its own subagents** (verified on disk via child session headers) |
+| `workspace-effect` | 24 | workspace actually effective when no path is given |
+| `acceptance` | 36 | two folders × two conversations doing a read-only IDA Pro analysis |
+| `multi` | 19 | **several instances and non-ASCII paths**: reproduces "two instances share the registry and the later save drops the earlier instance's conversation", then proves **that conversation is recoverable by id alone from the session store and actually usable** (registry loss, not an explicit `forget` — forget is a terminal tombstone); **recovery never silently escalates privileges** (a read-only conversation stays read-only); no `.tmp` residue; and **CJK / emoji workspace paths** create sessions, do real work, and place files in the right directory |
+| `permission` | 11 | ★ **whether the permission tiers actually take effect** (a safety property): it ignores our own return values (the very thing that used to lie) and reads **the session's own record** (`permissions.preset` / `sandboxMode` in the projection cache), checking all three tiers and that their recorded values differ. **This suite caught a silent privilege escalation**: a `defaultPreset` in the profile overrides `DSH_PERMISSION_MODE` at session creation |
+| `list` | 13 | **the cost of `dsh_list`** (measured): a default call with the on-disk probe takes ~1 s (it spawns a DSH process) while **repeated calls hit a cache and drop to single-digit milliseconds**; `only_running=true` and `include_closed=false` **skip the probe** with equivalent semantics (unopened on-disk sessions are simply excluded) |
+| `reasoning-check` | 8 | **reasoning visibility**: `reasoning=hide` returns no thinking body but non-zero stats; `reasoning=full` returns the text and the rendered section |
+
+**`node test/run.mjs` runs 937 checks on a machine with seven client fixtures (955 with all nine)** — smoke 29 + 908 offline checks (926 with nine). Every suite exited 0 on 0.5.0 (2026-11-03, Windows / Node 24.21.0); none needs a provider (smoke skips its session-creation sections when DSH is absent).
+
+That is **542 assertions in the client-registration suites alone** (`setup` 45, `removal-scope` 24, `config-safety` 407, `real-configs` 66; 560 with all nine fixtures), which is where the 0.3 work actually is.
+
+The model-backed suites (`smoke` 29, `boundary` 46, `integration` 30, `async` 16, `sentinel` 36, `timeout` 38, `lock` 79, `cycle` 36, `concurrency` 31, `capability` 22, `workspace-effect` 24, `acceptance` 36, `multi` 19, `permission` 11, `list` 13, `reasoning-check` 8) total 474 and were last measured in full on 0.3.9 — they need a working provider, so re-run them yourself before trusting a release: `node test/run.mjs --all`. `acceptance` now **skips explicitly** when the DSH profile has no IDA MCP (`mcp__ida__*`).
+
+> Three different totals are intentional: `node test/run.mjs` (937/955), the CI offline job (nominal 908/926, no smoke; hosted runners without client fixtures skip `real-configs` entirely), and the model-backed set (474 nominal). Counts are the numbers each suite prints itself; don't use one number for a different runner.
+
+### 🧯 Why `sandbox-guard` exists
+
+On 2026-10-29 a throwaway verification script stored its sandbox path in a **PowerShell** variable named `$home`. `$home` is a read-only automatic variable, so the assignment failed silently (the script ran with `$ErrorActionPreference = 'Continue'`), `$env:USERPROFILE` was pointed at the sandbox name anyway, and the cleanup line — `Remove-Item $home -Recurse -Force` — resolved to the **real user profile**. The run timed out at 120 s mid-delete, taking part of `~/.codex`, `~/.cursor` and `~/.claude` with it.
+
+Nothing in the test suites was ever green-but-wrong about the *writer*; what was missing was any assertion about the *sandbox*. `sandbox-guard` is that assertion: it refuses the real home, its subdirectories, case variants, the filesystem root, and any path outside `os.tmpdir()`. `test/sandbox-home.mjs` is now the only place a sandbox is created or destroyed, and `setup`/`removal-scope` no longer call `mkdtempSync` or `rmSync` themselves — the suite fails if they go back to doing so.
+
+### 📏 Numbers in this README must be reproducible
+
+Every figure in this document is either **printed by a test** or **measured with a command you can re-run**. If you change a number, change it to a measurement — not to an estimate, and never to a plausible-looking value.
+
+This section exists because that rule was violated. An early draft claimed `dsh_send(wait=false)` returned "in ~1 ms" (measured: 81 ms), that interruption converged in "~18 ms" (no test ever produced that number — `integration.mjs` only asserts `waited_ms` is between 0 and 25 s; four manual samples gave 91/102/105/119 ms), and that a conversation costs "~120 MB" (measured: 295–476 MB) — the last one contradicting itself in a single sentence, quoting both "120 MB each" and "three = 428 MB".
+
+**Three tiers, and how to state each:**
+
+| Tier | What it means | How to write it |
+|---|---|---|
+| **Tested** | A suite asserts it | Give the number; the suite is the authority |
+| **Measured** | You ran a command | Give the number **and the method**, so a reader can reproduce it |
+| **Estimated** | Derived or bounded | Say so ("roughly", "worst case", "≈") and show the arithmetic |
+
+**Recording a measurement inline.** The memory figures model the pattern — they name the tool, the before/after, and both samples:
+
+```text
+measured 300-480 MB per conversation
+  (Get-Process node: WorkingSet64 summed before vs. after one active
+   conversation reached end_turn; two cold starts gave 476 MB and 295 MB)
+```
+
+**When yours disagrees, say so.** Figures depend on machine, DSH version and load. A measurement outside a documented range is worth an issue — the range is a claim, not decoration.

package/docs/en/usage.md

@@ -0,0 +1,71 @@
+> Back to [README](../../README.md)
+
+## 📋 Workflow: dispatch, then collect later
+
+MCP tool calls **block**, so `dsh_send` **does not block by default** (`wait=false`): you get a receipt immediately, the turn runs in the background, and the sentinel file wakes you when it finishes. The whole flow:
+
+```text
+1. dsh_send(conversation_id, prompt, wait=false)
+     → { run_id: "run-abc123", background: true }        # returns without waiting for the turn
+
+2. …keep working on something else (verified: another conversation ran a full turn meanwhile)…
+
+3. dsh_status(conversation_id)
+     → state=running | elapsed=3.5s | current_tool=pwsh | out=37 chars
+
+4. dsh_read(conversation_id, cursor)                      # peek mid-flight
+     → [me] … | [turn] turn 1 started | [tool] pwsh [in_progress]
+
+5. dsh_get(conversation_id, run_id)                       # collect the result
+     → status=done, elapsed=20.3s, full answer
+```
+
+`run_id` is the receipt. Run records are **memory-only, last 20 kept**; under many concurrent runs old ones get evicted and `dsh_get` will fail — which is exactly why the completion sentinel below carries the result.
+
+## 🔔 Workflow: get notified on completion (no polling)
+
+Besides `run_id`, `wait=false` returns a **`sentinel_file`** path plus **`sentinel_file_posix`** (the Bash/MSYS form — use it directly; hand-converting Windows paths is the easiest way to make your waiter hang until timeout). When the turn ends — **whether it succeeds, fails, or is cancelled** — the service **atomically writes** a small file there containing the final `status` and `result`. So you neither poll nor block: **wait for that file with a background task in your own host (Claude/Codex); the moment it appears, you're woken up.**
+
+```bash
+# sent="$sentinel_file_posix"   ← copy it straight from the tool result
+sent='/c/Users/you/.dsh/.dsh-any-agent/runs/<conversation_id>/<run_id>.json'
+dl=$(( $(date +%s) + 2100 ))          # 35min safety net so a dead service can't hang you forever
+until [ -f "$sent" ]; do
+  [ "$(date +%s)" -ge "$dl" ] && { echo "TIMEOUT"; exit 1; }
+  sleep 2
+done
+echo "DONE"                            # task exits → host wakes you → read the file to collect
+```
+
+Once the file exists: **read it** for `status` and `result` (preferred — immune to the in-memory window and survives restarts), or use `dsh_get(conversation_id, run_id)`.
+
+Design notes (especially under **concurrent multi-session** use):
+
+- **No cross-talk**: the path is `<state dir>/runs/<conversation_id>/<run_id>.json`, namespaced by conversation. `run_id` sequence numbers are counted per-conversation, so two conversations *can* mint the same `run_id` in the same millisecond — the per-conversation directory keeps them apart. Arm one background task per run; each completes and wakes you independently.
+- **Latch semantics**: the file is written once and kept. Even if the run finishes *before* you arm the waiter, `[ -f ]` is immediately true — you never miss it.
+- **Atomic write**: `tmp` + `rename`; if the file exists its contents are complete. Each run uses its own tmp, so concurrent writes never clobber.
+- **No server push**: the service only answers requests over MCP (it sends no notifications). "Completion notification" is entirely the sentinel file plus your background waiter.
+- **★ No reasoning in the sentinel**: the payload carries the answer, thinking *statistics*, usage and (credential-redacted) tool inputs, but never reasoning text — `result.thinking` is stripped and replaced by a boolean `thinking_omitted` (`true` when reasoning was removed, `false` when there was none), because this server's rule is that reasoning never reaches its own disk artifacts. `dsh_get(run_id)` still returns it from memory while the record lives. `DSH_MCP_SENTINEL_INCLUDE_REASONING=1` breaks that guarantee deliberately. Note that **DSH's own session log does contain reasoning** — see [Logging and privacy](security.md#-logging-and-privacy).
+
+> Cleanup: sentinels contain full answers, so the service **prunes sentinels older than 7 days at startup** (tune with `DSH_MCP_SENTINEL_TTL_MS`; `0` disables). Your waiter should still `rm` the file after consuming it.
+
+## 🧵 Workflow: many conversations at once
+
+```text
+1. dsh_list(only_running=true)
+     - … | id=448b239b… | 🔵 running (9s, tool=pwsh, 40 chars this turn) | cwd=…
+     - … | id=33427096… | 🔵 running (8s, 34 chars this turn)        | cwd=…
+2. dsh_read(id,  cursor=0)      # read the first, note the cursor
+3. dsh_read(id2, cursor=0)      # switch to the second
+4. dsh_read(id,  cursor=<prev>) # switch back; entries that grew since <prev> reappear (match by seq)
+```
+
+## 🤫 Reasoning: hidden by default
+
+DSH separates reasoning from answer text at the model layer, and ACP exposes them as **two independent streams**. This server hides reasoning by default and returns only **statistics** (characters, duration, chunk count) — so the caller knows thinking happened without paying for it in context.
+
+- `reasoning=hide` (default) — content dropped, stats returned
+- `reasoning=marker` / `summary` / `full` — progressively more content (mind your context budget)
+- `dsh_read(include_reasoning=true)` — live reasoning of the *currently running* turn only; it is never buffered and is discarded when the turn ends
+
+> ⚠️ This server never writes reasoning to its own logs, state file or sentinels — but **DSH's own session log (`~/.dsh/sessions/**/session.v4.jsonl.zstd`) does contain the full reasoning text**, even when `reasoning=hide`. That is DSH's storage (it is what makes resume possible) and is outside this server's control; account for it when analyzing sensitive data.

package/docs/zh/architecture.md

@@ -0,0 +1,43 @@
+> 返回 [README](../../README.zh.md)
+
+# ⚡ 为什么不是直接把 DSH 包一层
+
+DSH 自带两个可编程入口。`sdk` profile 看着更简单，但它的 JSON-RPC 只有 **3 个请求 + 4 个通知**，缺了三样让 agent 实际不可用的能力；`acp` profile（Agent Client Protocol）全都有。以下结论全部针对 DSH `0.2.1-rc.5` 实测得出。
+
+| 能力 | `sdk` profile | `acp` profile（**本项目**） |
+|---|---|---|
+| **恢复会话** | ❌ 无 resume 方法，复用 id 报 `already exists` | ✅ `session/resume`，**跨进程实测通过** |
+| **中断回合** | ❌ 只能杀进程 | ✅ `session/cancel`，与用户手动按停止同一条路径 |
+| **应答审批** | ❌ 无通道，操作静默 fail-closed | ✅ `session/request_permission` 往返 |
+| 列出 / 关闭会话 | ❌ 无 | ✅ `session/list`、`session/close` |
+| 灰字 vs 黑字 | 同一条消息里靠 `type` 字段分 | ✅ 两条独立通道 `agent_thought_chunk` / `agent_message_chunk` |
+| 每会话 MCP 服务器 | ❌ 进程级 | ✅ `session/new` 与 `session/resume` 都接受 `mcpServers` |
+
+**核心思想：进程只是缓存，不是身份。** 对话的身份是 DSH 的 `sessionId`，落盘在 `~/.dsh/sessions`。进程被回收、崩溃、甚至整个 MCP 服务重启，下一次调用都会自动 `session/resume` 把它接回来，历史完整保留。
+
+<details>
+<summary>客户端、服务端与 DSH 是怎样连接的</summary>
+
+```
+  任意 MCP 客户端                    ← Claude Code、Codex、Cursor、Zed、Cline、你自己写的…
+  (Claude/Codex/Cursor/…)            │
+         │ MCP over stdio            │ 换行分隔 JSON-RPC（ACP）
+         ▼                           ▼
+   ┌─────────────┐          ┌──────────────────────────┐
+   │dsh-any-agent│─────────▶│ dsh --profile dsh-team   │  同 (cwd, 权限) 的会话
+   └─────────────┘          │                          │  共用一个长驻进程
+                            └────────────┬─────────────┘  （0.5.0 起默认）
+                                         │
+                            ┌────────────┴─────────────┐
+                            │ DSH 自带工具             │ 文件/shell/搜索/
+                            │                          │ 技能/子代理/workflow
+                            ├──────────────────────────┤
+                            │ dsh-mcp-client           │ → 你自己的其他 MCP 服务器
+                            └──────────────────────────┘
+```
+
+**进程模型。** 会话的身份是 `sessionId`，进程只是可丢弃的载体。0.5.0 起同一 `(cwd, permission)` 的会话默认共用一个 ACP 进程（`src/host.mjs`）：DSH 的 ACP 服务端支持一条连接上多会话、每个 session 有自己的 Agent，但沙箱根与审批策略是**进程级**的，所以只能按这两项分组。收益是第二个会话建起来约 300ms（独立进程约 4s），内存也按组只付一份；代价是这**一个**进程崩了，组里所有会话的进行中回合会一起断（会话本体无损，下次派活各自 resume）——因此 `dsh_takeover` 不会在不带 `force` 的情况下杀共享进程。要回到「一会话一进程」就设 `DSH_MCP_SHARED_PROCESS=0`。
+
+**MCP 兼容性。** 服务端只使用 `initialize`、`ping`、`tools/list`、`tools/call` 四个标准方法。已用一个协商旧版协议、从不发送 `notifications/initialized` 的原始客户端验证。
+
+</details>

package/docs/zh/compatibility.md

@@ -0,0 +1,49 @@
+> 返回 [README](../../README.zh.md)
+
+# 🧩 兼容性矩阵
+
+`dsh-any-agent` 依赖 DSH 的 ACP profile；团队模式还依赖 DSH 0.1.7 起才有的实验性 Agent Teams 包。
+升级 DSH 之前先对照这张表，并在升级后跑一遍 `dsh_doctor`。
+
+## 版本
+
+| dsh-any-agent | DSH | 状态 | 说明 |
+|---|---|---|---|
+| 0.5.x | `0.1.7-rc.1` 及以上 | ✅ 已验证 | ACP + 实验性 Agent Teams 包均可用；团队模式需 `dsh-any-agent team on` |
+| 0.5.x | `0.1.5-rc.1` | ⚠️ 部分可用 | ACP 基本路径可用；缺 team 包，团队模式会自动保持关闭 |
+| 0.5.x | `0.2.x` | ⚠️ 未验证 | ACP 的 `session/*` 面可能变化；team 包必须与 DSH 版本匹配。升级前先跑 `dsh_doctor` 和离线套件 |
+| 0.4.x | `0.1.7-rc.1` | ✅ 已验证 | 团队模式当时默认开启 |
+| 0.4.x | `0.1.5-rc.1` | ⚠️ 部分可用 | 无 team 包 |
+
+> 实验性包（`dsh-experimental-agent-team`、`dsh-experimental-tool-agent-team`）**没有稳定性承诺**。
+> 它们随 DSH 版本发布，不能跨大版本混用。
+
+## 运行时要求
+
+- **Node.js ≥ 22.15**（用到 `node:zlib` 的 `zstdDecompressSync` 读 DSH 会话头）；
+- DSH 已安装，且 `~/.dsh` 下已有可用的 provider 与凭据（GUI 能正常聊天即可）；
+- 团队模式额外要求 DSH `>= 0.1.7-0`，并且 profile 里真的挂上了两个 team 包。
+
+## 怎么确认
+
+```bash
+dsh-any-agent --version          # 本服务版本
+node <DSH_BIN> --version         # DSH 版本（DSH_BIN 可用环境变量指定）
+dsh-any-agent team status        # 团队开关与 profile
+```
+
+在 MCP 客户端里调用 `dsh_doctor`，重点看：
+
+- `dsh_bin`：DSH 入口与版本；
+- `profile`：是否存在、是否漂移、路由来源；
+- `team`：`on` / `off` / `requested but unavailable`（版本或 profile 不含 team 包）；
+- `config`：当前 permission、空闲回收、共享进程等生效值。
+
+## 升级建议
+
+1. 升级 DSH 前先记录 `dsh_doctor` 的输出；
+2. 升级后重新跑 `node test/run.mjs`（离线）和 `node test/run.mjs --all`（需要 provider）；
+3. 如果团队模式打不开，先看 `dsh-any-agent team status` 和 `dsh_doctor` 的 `team` 检查，
+   再确认 `~/.dsh/profiles/dsh-team/cordis.patch.yml` 是否包含
+   `@deepseek-ai/dsh-experimental-agent-team`；
+4. 需要固定 DSH 版本时，显式设置 `DSH_BIN`，不要让 npx 缓存自动挑版本。

package/docs/zh/demo.md

@@ -0,0 +1,90 @@
+> 返回 [README](../../README.zh.md)
+
+# ▶️ 5 分钟：派活 → 插话 → 验收
+
+这个页面不是功能列表，是一条**能跑通**的路径。跑完你会看到：一个 agent 在后台把活干完、你中途改过两次需求、最后你自己复核了它交的东西 —— 而不是只看它说"已完成"。
+
+```bash
+npm run demo
+```
+
+## 它解决的是什么问题
+
+你的编辑器里已经有一个编码 agent，它卡在你的窗口里：你一关编辑器，它就没了；你想改口，只能等它跑完。
+
+`dsh-any-agent` 把 DSH 变成**别的 agent 的后台同事**：你在 Claude Code / Codex / Cursor 里派活，它在后台跑，跑完由哨兵文件通知你。这条 demo 就是那套流程的最小可跑版本。
+
+## 0. 准备
+
+- **Node.js ≥ 22.15**（服务端用 `node:zlib` 的 `zstdDecompressSync` 读会话头，更早的版本没有这个 API）
+- **一份能用的 DSH**：`npm i -g @deepseek-ai/dsh`，并且 `~/.dsh` 里有可用的 provider 与凭据（DSH 的 GUI 里能正常聊天就说明配好了）
+- 不需要装 Claude Code / Codex —— demo 自己就是一个 MCP 客户端
+
+## 1. 跑
+
+```bash
+npm run demo
+```
+
+它会在临时目录里建一个空工作区，然后让 DSH 在里面写两个文件（`fib.mjs` 与 `test-fib.mjs`）并跑测试。**中途会插两次话**：
+
+1. 要求 `fib(n)` 对负数抛 `RangeError`，测试里补一条断言；
+2. 要求在 `fib.mjs` 顶部加一行复杂度注释。
+
+跑完脚本**自己会复核**：检查两个文件是否真的存在，并亲手跑一遍 `node --test test-fib.mjs`。模型的自我汇报在这里不算数。
+
+实测：本机（Windows / Node 24.21.0 / 默认 profile）一次完整跑完 **57.6 秒**，三个回合、两次插话、4 个测试用例全过。换模型会浮动，但这就是"5 分钟"的来源 —— 留足余量。
+
+## 2. 六步分别做了什么、为什么需要它
+
+| 步骤 | 工具 | 为什么这一步重要 |
+|---|---|---|
+| 1 | `initialize` / `tools/list` | 只走 4 个标准 MCP 方法；任何支持 MCP over stdio 的客户端都能接 |
+| 2 | `dsh_start` | 建一个**长驻**会话。身份是磁盘上的 `sessionId`，进程只是缓存 |
+| 3 | `dsh_send(wait=false)` | 派完立刻返回 `run_id` + `sentinel_file`，回合在后台跑 —— 别让客户端自己的超时把你的活掐掉 |
+| 4 | `dsh_interject` ×2 | 中途改口。走的是"取消 + 立刻开新回合"，**已经做的工作不丢** |
+| 5 | 读哨兵 | **一个回合 = 一个哨兵**：被打断那轮写 `cancelled`，最后一轮写 `done`。文件原子落地，服务中途重启也照样能读 |
+| 6 | `dsh_get` + 自己复核 | `run_id` 是验收凭据；但结论要靠磁盘上有什么，不靠模型说了什么 |
+
+## 3. 三个容易被忽略的设计
+
+**为什么第 3 步不等结果？** 因为 MCP 工具调用是阻塞的，而客户端的响应超时通常只有几分钟。`wait=false` 让"派活"这个动作瞬间返回，长任务用**哨兵文件**收尾 —— 这才是"把几小时的活交出去"的前提。
+
+**`dsh_interject` 会一直等到"改口后的那一轮"结束才返回。** 它不是一个"发出去就回"的通知：你看到的第 4 步耗时里包含了一整轮模型工作。这通常是好事（返回即代表改口已经生效），但要给它留够时间 —— 用 `timeout_ms` 设上限，等不到空闲会报错并把你这次插话按 `cancelled` 落地（**不会**留在队列里偷偷执行）。
+
+**插话为什么不毁掉已经做的工作？** ACP 明确拒绝并发 prompt（`a prompt is already in flight`），所以 `dsh_interject` 是"取消当前回合 + 立刻发新回合"，历史完整保留。这是实用等价物，不是真·中途改向 —— 见[已知限制](limits.md)第 2 条。
+
+**为什么 demo 用 `workspace-write` 而不是默认档？** 为了让沙箱真的在起作用：这个任务只该写临时工作区里的两个文件。`read-only` 档连 shell 都起不来，`danger-full-access` 又不适合当默认示范。
+
+## 4. 换一个任务 / 零成本预览
+
+```bash
+# 换成你自己的任务（会跳过内置的三个小要求）
+npm run demo -- --prompt "把这个目录里的 README 翻译成英文，并检查 Markdown 语法"
+
+# 回放上一次录制：不需要 DSH、不花 token、几秒钟看完
+npm run demo -- --replay
+
+# 跑完保留工作区，方便自己翻结果
+npm run demo -- --keep
+```
+
+想把它录成一份可回放的记录：
+
+```bash
+npm run demo -- --save      # 成功后写 demo/transcript.json
+```
+
+## 5. 隔离性：它不会动你的日常状态
+
+注册表、哨兵、写锁登记全部指向一个临时目录，脚本结束时删掉。也就是说：**跑 demo 不会污染你在 Claude Code 里真实使用的那套会话列表。**
+
+只有一件东西仍在 `~/.dsh` 里：DSH 自己的会话日志（凭据和 provider 在那儿，没法隔离）。脚本结束时会 `dsh_release(forget=true)` 把这个会话从注册表里移走。
+
+## 6. 它证明了什么、没证明什么
+
+**证明了**：MCP 握手通了、会话建得起来、后台派活收得到哨兵、插话能让任务改向且不崩、产出物落盘且测试真的能跑过。
+
+**没证明**：你的机器上模型一定按预期行事（不同模型差异很大）、长任务在几小时后仍然可用（demo 只跑几分钟）、以及并发多会话时的表现 —— 那些在[测试](tests.md)里另有覆盖。
+
+> 需要说明的是：**demo 会真的调用模型、真的花 token**。想先看流程再决定要不要跑，就先用 `--replay`。