dsh-as-mcp 0.52.84 → 0.54.0

package/CHANGELOG.md

@@ -6,6 +6,156 @@ plugin is pre-1.0, so a minor bump is a feature and a patch is a fix or docs.
 A Chinese summary of every release lives in [CHANGELOG.zh.md](./CHANGELOG.zh.md);
 this file stays the authoritative record.
 
+## 0.54.0
+
+- Server push now covers the whole run instead of one turn-ending signal. The existing
+  `subscriptions/listen` stream carries a feed set as readable synthetic resources — no new tools,
+  so the surface stays at 35: `dsh://sessions` (add/remove/activity/status and subagent starts and
+  ends), `dsh://session/<id>/events` (the newest durable events projected to
+  `{seq, type, at, turn, step, summary, error}`, published on every append, at most 64 per read),
+  `dsh://session/<id>/assistant` (live `start`/`text`/`reasoning`/`tool`/`finish`/`end` frames with
+  a monotonic `seq`, sourced from `agent/assistant-stream`), `dsh://session/<id>/status` (the
+  `session_status` payload), `dsh://session/<id>/projections` (the allowlisted
+  `workingDirectory`/`worktree`/`goal`/`plan`/`todos`/`agentPreset`/`title` values), and
+  `dsh://jobs` / `dsh://jobs/<id>` (background shell jobs; the job tail read is non-consuming, so
+  watching it cannot steal bytes from `shell_output`). The `dsh://session/<id>/turn` settlement
+  resource from 0.52.86 remains and is now one feed among the set instead of the only one.
+  `resources/list` and `resources/templates/list` advertise the feeds; `dsh_info.notes` names them
+  too.
+- Publishes are coalesced per URI at 150 ms (`PUSH_COALESCE_MS`): the first publish of a window
+  goes out immediately, later ones collapse into one trailing publish, and different URIs never
+  wait on each other — so a token stream costs at most one notification per window per URI instead
+  of one per token. Turn settlement stays deliberately immediate. The live tails are bounded in
+  process: assistant frames keep 256 KiB / 2 000 frames per session and a read returns at most 200
+  frames and roughly 32 KiB of text (newest first, `truncated` when older frames were dropped), an
+  events read stops at 64, a job read returns at most the newest 8 192 characters of a 16 KiB
+  retained tail, and the job feed polls about once a second only while somebody is subscribed. No
+  subscriber means no work: the collectors return early and no harness service is read, so a
+  fire-and-forget prompt with no listener costs what it did before. `session.scope: "owned"` gates
+  notifications as well as reads — a session this endpoint did not create or fork produces no
+  frame (its subagent sessions included: their parent's feeds publish, and their own feeds remain
+  readable through the owned tree) — so the push channel cannot be used to enumerate ids the
+  tools would refuse.
+- A stateful 2025-era Streamable HTTP leg now sits beside the modern one. An `initialize` answers
+  with an `mcp-session-id` header; `POST`/`GET`/`DELETE` carrying it are served by a per-session
+  server and transport, and the long-lived `GET` with `Accept: text/event-stream` is the
+  notification channel — so `notifications/resources/updated` finally reaches 2025-era clients
+  that have no `subscriptions/listen`. Sessions are capped at 8 (least recently used evicted) and
+  closed after 30 minutes idle, answering `404 Session not found` so the client re-initializes.
+  Resumability is deliberately absent: `Last-Event-ID` replay is not implemented because every
+  notification is payload-less and a reconnect re-reads. Clients that never take the session id
+  keep the previous stateless serving unchanged — later `POST`s answered from a fresh stateless
+  instance, `GET`/`DELETE` still `405` (the stateless legacy GET is not a push channel; a stateful
+  session's GET is).
+- `bin/mcp-stdio.mjs` opens that GET stream after a stateful `initialize` and forwards every
+  server notification and server→client request to stdout as one JSON line, reconnecting with
+  500 ms→30 s backoff (a stream that delivered messages restarts at the base delay) and sending
+  the last SSE id it saw (harmless: the server ignores it). A stateless endpoint — no session id,
+  or a GET answered `404`/`405` — prints one push-disabled note and keeps the old request/reply
+  behavior. `src/mcp/feeds.ts` owns the collectors, reads and buffers, `src/mcp/push.ts` the
+  per-URI coalescing and the 2025 fanout, `src/mcp/http.ts` the stateful session manager;
+  `tests/feeds.test.ts`, `tests/feed-resources.test.ts`, `tests/legacy-http.test.ts` and
+  `tests/stdio-bridge.test.ts` pin each half, and both READMEs gain a "Server push and the two
+  transports" section with the era table, the feed table and the backpressure bounds. The tool
+  surface, the tool schemas and every configuration key are unchanged.
+
+## 0.53.0
+
+- The endpoint now covers Git worktrees and the sidebar's session organization. Six new tools —
+  `worktree_create`, `worktree_restore`, `session_archive`, `session_unarchive`, `session_pin`,
+  `session_unpin` — bring the surface from 29 to 35. `session_create` gained
+  `worktree: true | { name, from }`: the session is created first in the workspace (or bare
+  directory), so a session created with `workspaceId` keeps its place in that workspace group (a
+  cwd-only session stays ungrouped), and only then is a Git branch created, checked out and made the
+  session's live working directory — the sequence the DSH UI's "New worktree" option performs. A
+  failed worktree request leaves the session usable in the workspace and reports `worktreeError`
+  (retry with `worktree_create`); a profile with no worktrees service is refused *before* the
+  session is created. `worktree_create` does the same for an existing session, refusing while a turn
+  is running and serializing concurrent worktree operations per session (the harness service has no
+  lock of its own). `worktree_restore` re-checks a removed worktree out from the record
+  `worktree_create` returned, recreating the branch at `baseCommit` when it was deleted too.
+  `session_status` reports `workingDirectory` and the forge panel's `worktree` record when the
+  profile can read projections, and a change in either now wakes a held `waitMs`; `session_list`
+  gained `includeWorktree` to fold the same two fields into its rows, which also carry `archived`
+  and `pinned` flags. Archive/pin write the same registry sets the DSH sidebar's actions write:
+  archiving an active session requires `stopActivity: true` (the flag that also asks its work to
+  stop), archiving keeps the log, and the harness still has no session delete.
+- Fixed the one regression DSH 0.2.2 introduced in this bridge: `dsh_tool_call` failed every call
+  with "Tool batch execution failed" while `dsh_tool_list` kept working, because `ctx.tools.execute`
+  changed from a single-call input/output to a batch contract (`{ calls, signal, agent }` in,
+  `{ results }` out). The driver now tells the two shapes apart by the presence of `tools.resolve`
+  (shipped together with the batch executor), sends its one call in the right envelope and unwraps
+  the batch result, so the same build works on ≤0.1.7 and 0.2.2+. The allow-list and session-scope
+  checks run before either path.
+- DSH 0.2.2 removed `sessionController.inspect`. Log reads now prefer `sessionQuery`, keep `inspect`
+  on ≤0.1.7 and fall back to the controller's `events` message-aligned pages on 0.2.2 — enough for
+  "what is open now" and for the transcript, though a bounded page can cover less of a very long
+  log. Usage needs the whole log and deliberately does not use the paged reader (it would silently
+  under-count), so without `sessionQuery` (or `inspect` on ≤0.1.7) it reports an explicit capability
+  error instead of the `TypeError` a missing method used to produce. `session_search` remains
+  disabled on shipped Desktop profiles (the `session-query` index is configured `openAt: "never"`)
+  and says so. Worktree tools need the harness's `worktrees` service, first verified in
+  `0.2.2-rc.1` and shipped by the experimental forge bundle in Desktop/Web;
+  `dsh_info.harnessServices.worktrees` reports it and `toolAvailability` names every tool the
+  current profile cannot serve. Both READMEs gain a Worktrees section — the same-group workflow, a
+  typical flow and the two limits (no service, no commit) — and a tool table with all 35 rows;
+  `docs/CAPABILITY-GAPS.md` is re-counted to 35 tools and 27 probes.
+- `docs/NEW-CAPABILITIES-0.2.2.md` is the capability audit behind this release: the installed
+  `0.2.2-rc.1` service catalog against the old audit, what is now reachable, the ranked candidates
+  and the explicitly rejected additions (`typertGateway.invoke`, credentials, approval/sandbox
+  writes, …, restated for the implementation phase). `docs/WORKTREE-INTEGRATION-CONTRACT.md` is the
+  host-side contract the implementation follows: `ctx.worktrees.create/restore` signatures, the
+  proof that workspace grouping uses the durable header `cwd` (so entering a worktree keeps the
+  group only when the session was created with `workspaceId`), the forge panel's behavior to mirror,
+  the failure/concurrency matrix, and the recommended order of operations. `tools/check-docs.mjs`
+  and `tests/docs-consistency.test.ts` keep the two READMEs, the changelogs and the tool table in
+  step.
+
+## 0.52.86
+
+- A fire-and-forget turn can now report its own ending to a modern (2026-07-28) MCP client
+  instead of leaving the caller to poll. The endpoint advertises `resources.subscribe`, registers a
+  readable synthetic resource `dsh://session/<id>/turn` (the `session_status` payload), and — when a
+  `session_prompt { wait: false }` is admitted while a `subscriptions/listen` stream is open —
+  watches that turn with the same wait a blocking call uses and publishes
+  `notifications/resources/updated` when it settles: completed, failed, cancelled, or gone without
+  an ending. The watch is armed only while someone is listening (an unsubscribed fire-and-forget
+  prompt still costs nothing), one watch per request id (an idempotent retry does not
+  double-publish), and bounded by the same `promptTimeoutMs` — a wait that timed out never observed
+  an ending, so it publishes nothing rather than claiming one. Clients that do not subscribe,
+  including every 2025-era client and the stdio bridge, are unaffected and keep polling
+  `session_status`; the listen stream must be open *before* the prompt is admitted.
+- The server instructions and the `session_prompt` `wait` option now state the subscription contract
+  where a client will actually read it. `src/mcp/push.ts` owns the per-endpoint subscription bus and
+  the publish call, the driver arms and tears down the watchers, and
+  `tests/push-notifications.test.ts` pins the URI encoding, the subscriber gate, the advertised
+  capability, the readable template, both instruction sentences, and publish-once against a fake
+  session log.
+- The tool surface, the legacy stateless transport and the rest of the endpoint are unchanged.
+
+## 0.52.85
+
+- The MCP server's settings panel now also renders on the **Plugins page**, under this bundle's own
+  page: the browser half registers the same `McpSection` into the host's `plugins.bundle.config`
+  keyed seat, keyed by the bundle's package name (the page dispatches `entryKey = pkg.name`), so a
+  setting can be changed without opening DSH Settings. Both entries render the same component over
+  the same shared configuration form and snapshot — one value, two doors; a write from either is
+  visible in the other without a reload — and the new cell is registered only while the host serves
+  this entry's form (`ctx.configForms.whileServed`), exactly like the settings section. Because the
+  Plugins page renders bundle configuration inside a bare `section.detailSection` with no title of
+  its own, the cell asks the panel for a heading; the settings entry keeps relying on the settings
+  shell's nav and adds none. A host whose Plugins page declares no such seat simply shows no cell,
+  and the settings entry is unaffected. `src/client/contract.ts` now types both slot kinds (a list
+  entry's `id` arm and a keyed entry's `key` arm) and cites the harness `KindOptions` shape, instead
+  of assuming `settings.section`.
+- `tests/client-half.test.ts` pins the new surface against the built bundle and the source: the cell
+  is keyed by the package name (a wrong key renders nothing, silently, because the page's
+  `configured` ledger is exactly the set of registered keys), both surfaces sit behind the same
+  `whileServed` gate, and exactly one store backs both doors. The built `lib/client.js` still
+  requires only the platform's seeded modules.
+- The endpoint, tools and host half are unchanged apart from the version the MCP `initialize`
+  result advertises.
+
 ## 0.52.84
 
 - The GitHub-install instructions now lead with the approval that keeps working. pnpm matches a

package/CHANGELOG.zh.md

@@ -6,6 +6,31 @@
 - 两份文件的**版本标题必须完全一致**（集合与顺序），由 `tools/check-docs.mjs` 强制检查——发布时漏写中文条目会让检查失败，中文读者不会悄悄落后一个版本。
 - 版本号遵循 SemVer；项目仍是 pre-1.0，所以 minor 是功能，patch 是修复或文档。
 
+## 0.54.0
+
+- 服务端推送从「只报一轮结束」扩展到整场运行，仍走现有的 `subscriptions/listen` 流，且不新增任何工具（工具面仍是 35 个）：`dsh://sessions`（会话增删、活动/状态、subagent 起止）、`dsh://session/<id>/events`（最新持久事件投影为 `{seq, type, at, turn, step, summary, error}`，每次追加都发布，单次读取至多 64 条）、`dsh://session/<id>/assistant`（实时 `start`/`text`/`reasoning`/`tool`/`finish`/`end` 帧，`seq` 每会话单调递增）、`dsh://session/<id>/status`（与 `session_status` 同负载）、`dsh://session/<id>/projections`（白名单内的 `workingDirectory`/`worktree`/`goal`/`plan`/`todos`/`agentPreset`/`title`）、`dsh://jobs` 与 `dsh://jobs/<id>`（后台 shell 任务；任务尾部读取不消费，不会抢走 `shell_output` 的字节）。0.52.86 的 `dsh://session/<id>/turn` 结算资源保留，成为整个 feed 集合中的一项。`resources/list`/`resources/templates/list` 会公布这些 feed，`dsh_info.notes` 也会点名它们。
+- 发布按 URI 以 150 ms（`PUSH_COALESCE_MS`）合并：窗口内第一次立即发出，同一个 URI 的后续发布合并为一次尾随发布，不同 URI 互不等待——一段 token 流因此对每个 URI 至多每个窗口一条通知，而不是每个 token 一条；轮次结算仍立即发布。实时尾部在进程内是有界的：assistant 每会话保留 256 KiB / 2,000 帧，单次读取至多 200 帧、约 32 KiB 文本（从新到旧，更旧的帧被丢弃时带 `truncated`）；事件读取上限 64 条；任务读取至多返回 16 KiB 保留尾部里的最后 8,192 个字符；任务 feed 只在有人订阅时约每秒轮询一次。没有订阅者就什么都不做：采集器提前返回、不读任何 harness 服务，所以没有监听者的 fire-and-forget prompt 成本和以前一样。`session.scope: "owned"` 同样约束通知而不只是读取——本端点未创建或 fork 的会话不产生帧（其 subagent 会话亦然：父会话的 feed 照常发布，而这些 subagent 的 feed 仍按 owned 树可读）——推送通道因此无法用来枚举工具会拒绝的会话 id。
+- 在现代协议之外新增 2025 时代有状态 Streamable HTTP 的一条腿：`initialize` 回复带 `mcp-session-id`，带该头的 `POST`/`GET`/`DELETE` 由每会话的 server 与 transport 服务，长期 `GET`（`Accept: text/event-stream`）就是通知通道——没有 `subscriptions/listen` 的 2025 客户端终于能收到 `notifications/resources/updated`。会话上限 8 个（淘汰最久未用），静默 30 分钟后关闭并回答 `404 Session not found` 让客户端重新 initialize；刻意不实现 `Last-Event-ID` 重放（通知不携带负载，重连后重读资源即可）。不接收会话 id 的客户端保持此前的 stateless 服务不变：之后的 `POST` 由全新 stateless 实例应答，`GET`/`DELETE` 仍是 `405`（stateless 的旧式 GET 不是推送通道，有状态会话的 GET 才是）。`bin/mcp-stdio.mjs` 在有状态 `initialize` 后打开这条 GET 流，把每条通知与任何服务端→客户端请求作为一行 JSON 写到 stdout，按 500 ms→30 s 退避重连并带上最后看到的 SSE id（服务端会忽略，发送无害）；stateless 端点（没有会话 id，或 GET 回答 `404`/`405`）只打印一条「push disabled」提示，请求/应答行为不变。
+- `src/mcp/feeds.ts` 负责采集器、读取与缓冲，`src/mcp/push.ts` 负责按 URI 合并与 2025 会话扇出，`src/mcp/http.ts` 负责有状态会话管理；`tests/feeds.test.ts`、`tests/feed-resources.test.ts`、`tests/legacy-http.test.ts`、`tests/stdio-bridge.test.ts` 分别钉住各半边。两份 README 新增「Server push and the two transports / 服务端推送与两种传输」章节：时代对照表、feed 表与背压上限，并更新兼容性与设计说明。工具面、工具 schema 与所有配置键均不变。
+
+## 0.53.0
+
+- 新增 6 个 MCP 工具（`worktree_create`、`worktree_restore`、`session_archive`、`session_unarchive`、`session_pin`、`session_unpin`），工具面从 29 增至 35。`session_create` 新增 `worktree: true | { name, from }`：先在 workspace（或裸目录）里建好会话，因此带 `workspaceId` 创建的会话保持原工作区分组（只用 cwd 创建的会话不在任何组），然后再建 Git 分支、检出并设为会话的实时工作目录——与 DSH 界面「New worktree」选项同一套顺序；worktree 创建失败不回滚会话，回复用 `worktreeError` 说明（可用 `worktree_create` 重试），profile 没有 worktrees 服务时则在创建会话**之前**拒绝。`session_status` 报 `workingDirectory` 与 forge 面板的 `worktree` 记录（任一变化都会唤醒挂着的 `waitMs`），`session_list` 新增 `includeWorktree`，行上还带 `archived`/`pinned`。归档/置顶写的是 DSH 侧边栏动作所用的同一组 registry 集合：归档运行中的会话需要 `stopActivity: true`，日志保留，harness 依然没有删除会话。
+- 修复 0.2.2 带来的回归：`dsh_tool_call` 曾以 "Tool batch execution failed" 失败，而 `dsh_tool_list` 正常——0.2.2 把 `ctx.tools.execute` 从单调用输入/输出改成了批量契约。驱动现在靠 `tools.resolve` 区分两种形状（≤0.1.7 单调用、0.2.2+ 批量），同一份构建两边都能用；allow-list 与会话作用域检查仍在执行之前。
+- 0.2.2 移除了 `sessionController.inspect`：日志读取优先 `sessionQuery`，≤0.1.7 上仍用 `inspect`，0.2.2 上回退到控制器 `events` 的消息对齐分页——对"现在开着什么"和对话记录够用，只是有界分页在很长的日志上覆盖得少一些；用量需要整份日志，刻意不用分页读取（会少算），因此没有 `sessionQuery`（或 ≤0.1.7 的 `inspect`）时改为明确的能力错误而不是 `TypeError`。`session_search` 在随包 Desktop profile 上仍不可用（`session-query` 配的是 `openAt: "never"`）。Worktree 工具需要 forge bundle 提供的 `worktrees` 服务（`dsh_info.harnessServices.worktrees` 会报出）。两份 README 新增工作树章节与 35 行工具表，`docs/CAPABILITY-GAPS.md` 的工具数与探针数更新为 35/27；能力审计见 `docs/NEW-CAPABILITIES-0.2.2.md`，宿主侧契约见 `docs/WORKTREE-INTEGRATION-CONTRACT.md`。
+
+## 0.52.86
+
+- fire-and-forget 的 turn 现在能自己报告结束，现代（2026-07-28）MCP 客户端不必再轮询。端点宣布 `resources.subscribe`，注册一个可读的合成资源 `dsh://session/<id>/turn`（内容与 `session_status` 一致），并且当 `session_prompt { wait: false }` 被接收时若有打开着的 `subscriptions/listen` 流，就用与阻塞调用相同的等待去盯这一轮，结束时推送 `notifications/resources/updated`——完成、失败、取消，或没有 `turn/end` 而消失都算。watcher 只在有人监听时才会安排（没有订阅者的 fire-and-forget prompt 依旧零额外成本）、每个 request id 只一个（幂等重试不会重复推送），并且受同样的 `promptTimeoutMs` 约束：等待超时的 watcher 没有看见结束，就不推，而不是宣称一个假的结束。不订阅的客户端（包括所有 2025 客户端与 stdio 桥）不受影响，继续轮询 `session_status`；监听流必须在 prompt 被接收**之前**打开。
+- 服务端 instructions 与 `session_prompt` 的 `wait` 选项现在把订阅契约写在客户端真正会读的地方。`src/mcp/push.ts` 持有每端点的订阅总线和推送调用，driver 负责安排/清理 watcher；`tests/push-notifications.test.ts` 用假的会话日志固定住 URI 编码、订阅者门控、能力宣告、可读模板、两句 instructions，以及「只推一次」。
+- 工具面、旧的 stateless 传输与端点其余行为不变。
+
+## 0.52.85
+
+- MCP 服务的设置面板现在也渲染在**插件页**：本 bundle 自己的详情页里。浏览器半边把同一个 `McpSection` 注册进宿主的 `plugins.bundle.config` keyed 插槽，key 就是 bundle 的包名（页面按 `entryKey = pkg.name` 派发），所以改设置不必每次都打开 DSH 设置。两个入口是同一个组件、同一个共享配置表单与同一份快照——一个值两扇门，任一边写入另一边无需刷新即可见；新单元格和设置页一样，只在宿主确实提供这一项配置表单时注册（`ctx.configForms.whileServed`）。插件页把 bundle 配置放在一个没有标题的裸 `section.detailSection` 里，所以这个单元格让面板自己画标题；设置页入口仍沿用设置外壳的导航标题，不重复画。宿主插件页没有该插槽时什么都不显示，设置入口不受影响。`src/client/contract.ts` 现在同时描述两种插槽（list 的 `id` 与 keyed 的 `key`），并引用了 harness 的 `KindOptions` 形状，不再假设只有 `settings.section`。
+- `tests/client-half.test.ts` 把新入口钉在构建产物与源码上：单元格以包名作 key（key 写错不会报错，只是静默不渲染，因为页面判断"有没有配置"就是已注册 key 的集合）、两个入口在同一道 `whileServed` 门后、且只有一个 store 同时支撑两者；构建出的 `lib/client.js` 仍然只 require 平台预置模块。
+- 除 MCP `initialize` 宣告的版本号外，端点、工具与宿主半边均无变化。
+
 ## 0.52.84
 
 - GitHub 安装指引改为先给「能长期有效的放行方式」：pnpm 按 `<name>@<git url>`（不带 `#<ref>`）匹配 git 依赖的构建，一条 `allowBuilds` 条目就能覆盖之后的所有 commit；原文先让读者抄 pnpm 打印的、钉在 commit 上的 key（`…/tar.gz/<sha>: true`），上游一 push 就失效，每更新一次都得重新手动放行。同时纠正本页两条命令的实际门槛：`github:…` 与 release `.tgz` 都按 tarball 拉取，所以按仓库 URL 放行需要 pnpm ≥11.19.0（11.11.0 只覆盖克隆形式的 git 依赖）；pnpm 10 上该开关叫 `onlyBuiltDependencies`。并新增「不放行构建」的通道：npm 与预构建的 Release 资产，两者都不执行 `prepare`。

package/README.md

@@ -218,7 +218,9 @@ advertised models (`catalog.providerModels`): that asks the adapters, some of wh
 discovery, so it is opt-in and time-boxed per provider — and it is the reliable way to pick a valid
 `session_create.model` or `session_set_model.model`. Every catalog field is optional and independently
 guarded, and `catalog.unavailable` names whichever read could not be answered, so a missing entry means
-"this profile does not say" rather than "nothing is allowed".
+"this profile does not say" rather than "nothing is allowed". Its `notes` also name the push feeds and the
+two transports this endpoint serves, so a caller can find the subscription surface without reading this
+README.
 
 ## Tools
 
@@ -228,22 +230,28 @@ schema-aware client can read the object directly instead of parsing JSON out of
 
 | Tool | What it does |
 | --- | --- |
-| `dsh_info` | Endpoint, version and uptime, token source, enabled groups, available harness services, usage/cost availability, the `catalog` of accepted providers, agent presets and sandbox mode, and `toolAvailability` — the tools that passed every rule (`availableTools`, comparable with `tools/list`), those this deployment cannot serve, and why. `probeSearch` additionally exercises a real search to say whether the index answers, rather than just whether the tool is enabled. |
+| `dsh_info` | Endpoint, version and uptime, token source, enabled groups, available harness services, usage/cost availability, the `catalog` of accepted providers, agent presets and sandbox mode, `toolAvailability` — the tools that passed every rule (`availableTools`, comparable with `tools/list`), those this deployment cannot serve, and why — and the push feed URIs in `notes`. `probeSearch` additionally exercises a real search to say whether the index answers, rather than just whether the tool is enabled. |
 | `workspace_create` | Register a directory as a DSH workspace (creating it if needed; pass `createDirectory: false` to require that it already exists). |
 | `workspace_list` | Every registered workspace with id, path, title, directory status, and the sessions **attached to the registration** (created with `workspaceId`) — that count is not the number of sessions whose `cwd` happens to be the directory; `session_list { cwd }` answers that. |
 | `workspace_delete` | Unregister a workspace (files and session history untouched); idempotent. |
-| `session_create` | Start a DSH agent session bound to a workspace or bare directory. |
+| `session_create` | Start a DSH agent session bound to a workspace or bare directory, optionally with its own Git checkout. Model selection falls back to this DSH instance's default route (`provider` and `model` must be given together — a half pair is refused before the session exists — and an unroutable pair still creates the session but reports `modelSelectionError`). Pass `worktree: true` (or `{ name, from }`) to create a Git branch and checkout from the workspace after the session exists and make it the session's live working directory: a session created with `workspaceId` keeps that workspace group (its durable directory stays the workspace), while a cwd-only session stays ungrouped. The reply carries the `worktree` record and the new `workingDirectory`; a failed worktree request leaves the session usable in the workspace and reports `worktreeError` (retry with `worktree_create`), and a profile with no worktrees service is refused before the session is created. |
+| `worktree_create` | Create a Git branch and checkout from a session's current checkout and make it that session's working directory — the DSH UI's "New worktree" option, for a session that already exists (refused while a turn is running; concurrent worktree calls on one session are serialized). `name` is the new branch and the directory under the source checkout's `.agents/worktrees/`; `from` is a local commit, branch or tag (default the checkout's `HEAD`); uncommitted files stay in the source checkout, and an existing branch or checkout name fails. The reply carries `path`, `branch`, `baseCommit`, `repositoryRoot` and `from` — keep it for `worktree_restore`. Needs the worktrees service. |
+| `worktree_restore` | Check a session's worktree out again at the recorded `path` after it was removed outside the session: the `branch` is checked out when it still exists, otherwise recreated at `baseCommit`, under the recorded `repositoryRoot`. The session's working directory is not changed, and uncommitted changes lost with the directory cannot be recovered. Pass the record `worktree_create` (or `session_status.worktree`) returned. Needs the worktrees service. |
 | `session_fork` | Branch a session (live or restored from disk) into a child that inherits its event prefix, optionally up to `atSeq` (event position) or `atTurn` (turn boundary); with no boundary the harness picks the latest completed turn. Continuing from that point costs one turn, not a replay, and `session_usage` reports the inherited prefix separately. |
 | `session_set_model` | Change the provider route and model later turns use: start cheap, escalate for a hard turn, or fall back when a route is unavailable. `reasoningEffort` optionally raises the thinking budget for the same route. The reply's per-model usage shows which route spent what. |
 | `session_rename` | Set an explicit user title on a session, so what an external harness names a task stays the name a human sees in the DSH UI (and automatic title generation stops). A session currently held open by another DSH process is refused by the harness. |
 | `session_search` | Search session **message content** (FTS tokens/phrases), returning `sessionId`, a snippet, and (when the session listing is readable) the match's `cwd`/`updatedAt`/`running` plus `parentSessionId`/`origin` for subagent sessions; the harness caps a search at 20 and reports `hasMore`. Matching is FTS tokens/phrases (not arbitrary substrings), and multiple terms must all match. **Opt-in:** shipped compositions configure `session-query` with `openAt: "never"`, in which case the tool explains how to enable the index instead of searching. |
-| `session_list` | Live session summaries, most recently updated first; `includeTitle` also folds each session's latest title (one log read per session), and `cwd`/`running` filter before the limit applies. A subagent session carries `parentSessionId` and `origin: "subagent"`, and `origin` (`root` / `subagent`) filters before the limit, so the flat list becomes a tree view. The reply carries `total` (matches before the cut) and `truncated` when the limit hid some. |
-| `session_status` | One session's live state, for work started with `session_prompt { wait: false }`: `running`, the open `turn`/`step`, the newest event (`lastEventSeq`/`lastEventAt`), `idleMs` (how long the log has been quiet), `stalled` (running but silent for a minute — a symptom, not a verdict), how the last turn ended (`lastTurn.reason`), and `failure` when it ended abnormally. `waitMs` holds the call until something changes or the bound elapses (capped at 60 s), so a supervisor polls once per change instead of on a guessed interval. Read-only. |
+| `session_list` | Live session summaries, most recently updated first; `includeTitle` also folds each session's latest title (one log read per session), `includeWorktree` folds each row's live `workingDirectory` and the forge panel's `worktree` record (one projection read per session — how rows of one workspace are told apart when each works in its own checkout), and `cwd`/`running` filter before the limit applies. Rows carry `archived` and `pinned` flags read from the same registry sets the DSH sidebar's archive and pin actions write. A subagent session carries `parentSessionId` and `origin: "subagent"`, and `origin` (`root` / `subagent`) filters before the limit, so the flat list becomes a tree view. The reply carries `total` (matches before the cut) and `truncated` when the limit hid some. |
+| `session_status` | One session's live state, for work started with `session_prompt { wait: false }`: `running`, the open `turn`/`step`, the newest event (`lastEventSeq`/`lastEventAt`), `idleMs` (how long the log has been quiet), `stalled` (running but silent for a minute — a symptom, not a verdict), how the last turn ended (`lastTurn.reason`), and `failure` when it ended abnormally. When the profile can read session projections it also reports `workingDirectory` (the directory the session currently works in — a worktree checkout after it entered one) and `worktree` (the forge panel's record for a worktree it created); a change in either counts as a change for `waitMs`, so a held call reports entering a worktree instead of sleeping to its bound. `waitMs` holds the call until something changes or the bound elapses (capped at 60 s), so a supervisor polls once per change instead of on a guessed interval. Read-only. |
 | `session_prompt` | Send one task to a DSH session; by default waits for the turn and returns the reply, the tool calls the agent made, that turn's wall-clock duration (`turn.durationMs`), and its token usage plus the session's running total. `toolCalls` controls how much of each call is echoed: `summary` (default) gives name/id/argument size, `full` also the arguments (bounded by `maxArgumentChars`), `none` just counts. Attach screenshots with `images` (png/jpeg/webp/gif, at most 4; the harness decodes them, so a header-only file that `file_read_image` would sniff is refused as malformed). Pass an `idempotencyKey` and a retried call returns the existing turn instead of sending the task twice — with `wait: true` that retry *waits* for the turn, which is how a caller awaits work it queued with `wait: false`. If the client sends a `progressToken`, the wait reports `notifications/progress` at most once a second, and its message separates the elapsed wait from the log silence (`turn 3: 2 tool call(s), 41s elapsed, log quiet for 12s`). `maxReplyChars` optionally caps the agent's final reply (a cut reply reports `replyTruncated` and its original `replyChars`), and `turn.models` lists the `provider/model` routes that answered. An abnormal ending is reported, not returned as an ordinary reply: `turn.failure` carries `{kind, message}` for the harness's `error`/`blocked`/`max-tokens`/`interrupted` endings, and for the two conditions the wait detects itself — `unreadable` (the log stopped being readable mid-wait) and `vanished` (the turn stopped without a `turn/end`); a completed turn carries no failure block, and `aborted: true` keeps meaning "the caller cancelled". A client cancellation (`notifications/cancelled` for this call) stops the turn and settles the wait with `turn.aborted: true` — the endpoint routes that notification itself, because the SDK version in use only acknowledges it. The usage snapshot carries `partial: true` only when it was taken while the turn was still running; a turn that settled on cancellation has final numbers. A second prompt **from this connection** while a turn is running waits behind it (the endpoint runs one turn at a time per session) instead of entering the harness inbox; a second MCP client is what queues a message behind a running turn, and `mode: "steer"` folds one into the running turn. |
 | `session_messages` | Read a session's user/assistant transcript; `sinceSeq`/`role` make it an incremental poll, `maxCharsPerMessage` caps each message (a cut message reports `truncated` and its original `chars`), each message carries the `id` that queue mutations address (and user messages carry the admission `requestId` that `idempotencyKey` derives), `includeToolCalls` folds each assistant message's tool calls (name, call id, argument JSON length, and — once the tool has answered — the result's length and error flag) into the transcript, `includeToolResults` adds each tool result as its own `role: "tool"` row (callId, text, error) so one read covers the whole timeline (`"errors"` keeps only the failed ones); assistant and tool rows carry `turn`/`step`, and `turn: N` (or `fromTurn`/`toTurn`) narrows a read to one turn or a phase, and `beforeSeq` pages backwards so a transcript longer than the window stays reachable (pass the oldest seq you hold; the tail of the older window comes back). The reply carries `total` (messages matched by the filters) and `truncated` when the limit window hid older ones. |
 | `session_queue` | Without `messageId`/`action`, list the session's **pending** inbox with the ids queue mutations address (a queued message has no transcript event yet, so `session_messages` cannot show it); each row carries its text, image count, and the harness's inbox `source` kind (a message queued through this endpoint reports `user` — it is the harness's classification, not a client identity). With `messageId` + `action`, mutate one: `remove` (it never runs), `edit` (replace its text; the id is preserved), or `steer` (deliver it into the running turn). `session_cancel` stops the running turn; this changes the work waiting behind it. |
 | `session_tool_result` | Read one recorded tool result, addressed by `callId` (from `session_messages { includeToolCalls: true }`) or by `toolName` (the most recent completed call of that tool): the text, its original length, whether the harness marked it an error, `maxChars` to cap it, and `from: "end"` to keep the tail (a stack trace ends with the error). Debug a failing tool without re-reading the transcript. |
 | `session_cancel` | Ask the agent to stop its current turn. |
+| `session_archive` | Archive a session — the same registry-global archive the DSH sidebar's archive action writes. An archived session leaves the UI's grouping and its future turns are refused, but its log is kept, so `session_unarchive` restores it. Archiving a session that still has running work is refused unless `stopActivity: true` is passed, which also asks that work to stop; that flag is deliberately something the caller must ask for. Nothing is deleted. |
+| `session_unarchive` | Return an archived session to its recorded position in the DSH UI. Idempotent: an id that is not archived is not an error, and the log was never touched, so the session is visible and promptable again. |
+| `session_pin` | Pin a session to the top of the DSH UI's session list (the same pin set the sidebar writes). The session must exist and must not be archived; pinning is idempotent. |
+| `session_unpin` | Remove a session from the DSH UI's pin set. Idempotent: an id that is not pinned is not an error. |
 | `session_usage` | Token usage per session (its subagents included by default): exact bucket counts, a per-model breakdown, optional per-turn detail, and money when a price plugin is installed. Pass `sessionIds` to tally several known sessions in one receipt, or `cwd` to total every session that ran in one workspace directory. |
 | `file_read` | Read a UTF-8 file through DSH's filesystem service. Bounded by a byte limit; `offset`/`nextOffset` page through a larger file (both are **byte** offsets, so an offset at or past EOF is an empty complete read), `maxBytes` asks for a smaller window so reading a slice costs less, and `sha256: true` returns the whole file's hash as the compare-and-swap value for a later write/edit. |
 | `file_read_image` | Read an image (png/jpeg/gif/webp/bmp, detected from the bytes) and return it as an MCP image block, preceded by a metadata block (path, mimeType, bytes), so you can look at a screenshot or chart instead of guessing. Capped at 8 MiB. |
@@ -295,10 +303,160 @@ refused *and* hidden from `dsh_tool_list`. The omissions that matter:
 - **`ask_user_question` and `present`** reach the human at the keyboard.
 - **`workflow`, `ralph`, `send_message`, `spawn_teammate`, `schedule_create`** start work that
   outlives the call; **`create_goal` and `update_goal`** sustain unattended execution.
+- **`create_worktree`** (DSH 0.2.2+) changes the calling session's working directory. The same
+  operation is exposed as the first-class `worktree_create`, which scopes it to a session this
+  endpoint may address and reports the retained branch and checkout; admitting the model-facing
+  tool would let an agent move whatever session it happens to be in and hide the record.
 
 An operator can widen this deliberately with the `agentTools.allow` setting, or subtract from
 the default with `agentTools.deny`.
 
+## Worktrees
+
+A session can work in its own Git checkout of the same repository. The operation is the one the
+DSH UI's "New worktree" option performs: a new branch is created from a revision, checked out under
+the source checkout's `.agents/worktrees/`, and made the session's live working directory. This is
+how several sessions in one workspace group each isolate their work.
+
+The ordering is what keeps the sidebar grouping intact. `session_create { worktree: true }` creates
+the session **first**, bound to the workspace (or bare directory) the caller named, then creates the
+worktree from that checkout. The session's durable directory stays the workspace, so a session
+created with `workspaceId` stays in that workspace group in the DSH UI; a session created with a
+bare `cwd` was never in a group and stays ungrouped. Its tools, commands and prompts run in the
+worktree. For a session that already exists, `worktree_create { sessionId, name?, from? }` performs
+the same move and is refused while the session has a running turn (concurrent calls on one session
+are serialized).
+
+Typical flow:
+
+```
+session_create { workspaceId: "...", worktree: true }
+  -> session_prompt { sessionId: "...", prompt: "Implement the feature here; main stays clean." }
+  -> session_status { sessionId: "..." }          # workingDirectory is the new checkout
+```
+
+The reply of `session_create` (and of `worktree_create`) carries the record `worktree_restore`
+needs: `path`, `branch`, `baseCommit`, `repositoryRoot` (plus the `from` revision, `null` for
+`HEAD`). Keep it: if the checkout directory is removed outside the session, `worktree_restore`
+checks that branch out again — recreating it at `baseCommit` when the branch was deleted too — and
+does not change the session's current working directory. Uncommitted changes lost with the directory
+cannot be recovered.
+
+Two limits are worth stating. **The tools need a worktrees service**, shipped by the forge bundle
+in DSH Desktop/Web; `dsh_info.harnessServices.worktrees` reports it, and `toolAvailability` names the
+tools a profile cannot serve. On a profile without it, `session_create { worktree }` is refused
+before a session is created and the rest of the endpoint is unchanged. **The worktree is not a
+commit**: it is a branch plus a checkout, so uncommitted files stay in the source checkout and are
+not copied, and an existing branch or checkout name fails rather than being reused.
+
+`session_status` reports `workingDirectory` and the forge panel's `worktree` record when the profile
+can read session projections, and `session_list { includeWorktree: true }` folds the same two fields
+into its rows. The full host-side contract — service signatures, grouping proof, failure matrix and
+the recommended order of operations — is `docs/WORKTREE-INTEGRATION-CONTRACT.md`; the capability
+audit behind this release is `docs/NEW-CAPABILITIES-0.2.2.md`.
+
+## Server push and the two transports
+
+An MCP server cannot call a client on its own, so every "something changed" travels as a
+resource notification. This endpoint publishes one change-feed surface over both standard push
+channels, and each notification is **payload-less**: it names a synthetic resource, and the
+client reads that resource for the JSON. No tools were added for this — the surface is still the
+35 in the table above — and push has no configuration key: it is always on and costs nothing
+while nobody subscribes.
+
+| Client era | Handshake | Server→client channel | How push is requested |
+| --- | --- | --- | --- |
+| **2026-07-28 (modern)** | `server/discover`; every request carries its own `_meta` envelope plus the `mcp-protocol-version` / `mcp-method` headers, so there is no session | one long-lived `subscriptions/listen` stream | name the feeds in `notifications.resourceSubscriptions`; the server answers `notifications/subscriptions/acknowledged` and then publishes `notifications/resources/updated` |
+| **2025-era Streamable HTTP** | `initialize` answers with an `Mcp-Session-Id`; later `POST`/`DELETE` carry it | that session's long-lived `GET` with `Accept: text/event-stream` | the endpoint advertises `resources.subscribe` and publishes its feeds to every live stateful session, so the same `notifications/resources/updated` frames arrive on the stream; `resources/read` fetches the payload |
+| **stdio** (`bin/mcp-stdio.mjs`) | the bridge POSTs `initialize` over HTTP and keeps the issued session id | its own long-lived `GET` on that session | each notification, and any server→client request, is written to stdout as one JSON line; the channel reconnects with 500 ms→30 s backoff |
+
+The bridge reacts to a stateless endpoint — an `initialize` that carried no session id, or a `GET`
+answered `404`/`405` — by printing one push-disabled note and leaving request/reply untouched.
+
+A concrete modern exchange (a 2025 client replaces steps 1–2 with the stateful handshake and its
+GET stream; the payloads are identical):
+
+```json
+// 1. open one stream and name the feeds. Session feeds exist with tools.session,
+//    the job feeds with tools.shell; resources/list and resources/templates/list
+//    advertise them.
+{ "jsonrpc": "2.0", "id": 1, "method": "subscriptions/listen",
+  "params": { "notifications": { "resourceSubscriptions": [
+    "dsh://sessions",
+    "dsh://session/<sessionId>/events",
+    "dsh://session/<sessionId>/assistant",
+    "dsh://jobs" ] } } }
+
+// 2. the acknowledgement names the subset the server honored
+{ "jsonrpc": "2.0", "method": "notifications/subscriptions/acknowledged",
+  "params": { "notifications": { "resourceSubscriptions": [ … ] } } }
+
+// 3. every change is one payload-less frame …
+{ "jsonrpc": "2.0", "method": "notifications/resources/updated",
+  "params": { "uri": "dsh://session/<sessionId>/events" } }
+
+// 4. … and resources/read on that URI returns the data
+{ "jsonrpc": "2.0", "id": 2, "method": "resources/read",
+  "params": { "uri": "dsh://session/<sessionId>/events" } }
+```
+
+| Feed URI | Payload | Published when |
+| --- | --- | --- |
+| `dsh://sessions` | the session list as `session_list` reports it, minus titles (`sessions`, `total`) | a session is added, removed, created or disposed, starts or stops running, changes activity or status, or a subagent starts or ends |
+| `dsh://session/{id}/events` | the newest durable events, projected to `{seq, type, at, turn, step, summary, error}` with `asOfSeq` (at most 64 events per read; `summary` is a bounded preview and `error` marks a failed tool result or an abnormal turn end) | every durable append to that session |
+| `dsh://session/{id}/assistant` | live assistant frames `{seq, at, turn, step, kind, text, done}` with `asOfSeq` and `truncated`; `kind` is `start`, `text`, `reasoning`, `tool`, `finish` or `end`, and `seq` is monotonic per session | while a model turn streams — a frame for its start and end, then one per text, reasoning or tool-call delta, plus the finish frame |
+| `dsh://session/{id}/status` | the same payload as `session_status` | any new durable event for that session, or a change in the agent's status |
+| `dsh://session/{id}/projections` | the allowlisted projection values: `workingDirectory`, `worktree`, `goal`, `plan`, `todos`, `agentPreset`, `title` | a turn ends, an agent preset is selected, a user message is appended, or the goal changes |
+| `dsh://jobs` | every background shell job this endpoint started (`jobs`) | a job starts or settles, or its status or pending bytes change |
+| `dsh://jobs/{id}` | one job plus its retained output tail (`tail`, `tailTruncated`) | its output tail grows or its status changes |
+| `dsh://session/{id}/turn` | the same payload as `session_status` | that turn settles — the resource from 0.52.86, still published immediately rather than coalesced |
+
+**Backpressure, so a token stream does not become a request storm.** Publishes are coalesced per
+URI: the first one goes out at once, later ones for the same URI collapse into a single trailing
+publish after 150 ms (`PUSH_COALESCE_MS`), and different URIs never wait on each other. A token
+stream therefore costs at most one notification per 150 ms per URI rather than one per token.
+Turn settlement is the exception — it is a discrete event a caller is waiting for, so it is
+published immediately. A notification is payload-less, so a burst of deltas costs one
+`resources/read`, not one reply-sized payload per token. The live feeds are bounded in process:
+the assistant buffer keeps at most 256 KiB / 2,000 frames per session, and a read returns at most
+200 frames and roughly 32 KiB of text (newest first, with `truncated` when older frames were
+dropped or not returned), an events read is capped at 64 events, and a job read returns at most
+the last 8,192 characters of a tail retained at 16 KiB. The job feed is polled about once a
+second, and only while somebody is subscribed: with no subscriber the collectors return early and
+no harness service is read, so a fire-and-forget prompt with no listener costs exactly what it
+did before. The job tail is deliberately non-consuming — `shell_output` still owns the delivery
+buffer, so watching `dsh://jobs/{id}` cannot steal bytes from the caller that polls it.
+
+**The 2025-era leg is stateful, and the old stateless behavior is preserved.** A 2025 `initialize`
+now answers with an `mcp-session-id` header; requests carrying it are served by a per-session
+server and transport, so `GET` (the notification stream) and `DELETE` (session teardown) work,
+and `notifications/resources/updated` reaches a 2025 client at last. At most 8 sessions are kept:
+the least recently used is evicted when a ninth opens, and a session silent for 30 minutes is
+closed, after which its id answers `404 Session not found` and the client re-initializes. A
+client that never takes the session id keeps the previous stateless serving unchanged — every later
+`POST` (one that is not another `initialize`) is answered from a fresh instance — and its
+`GET`/`DELETE` are `405`: the stateless legacy GET is **not** a push channel, a *stateful session's*
+GET is. Push has no replay store: a dropped stream reconnects without a cursor (`Last-Event-ID` is
+not honored), which is safe precisely because notifications carry no payload — the client re-reads
+the resource it was told about.
+
+**Security and scope.** Every request goes through the bearer check — the long-lived 2025 `GET`
+stream and session `DELETE` included — so there is no unauthenticated push path; a rejected
+request answers `401` with `WWW-Authenticate: Bearer realm="dsh-as-mcp"`. `session.scope:
+"owned"` gates notifications as well as reads: only a session this endpoint created or forked
+(the recorded owned ids) produces a frame, so the channel cannot be used to enumerate other
+sessions' ids. An owned session's own subagent sessions therefore produce no frames either —
+their parent's feeds publish, and their feeds remain readable because reads follow the owned
+tree like the tools do. The `dsh://jobs` feeds are not session-scoped: they show the background
+jobs this endpoint started.
+
+One bound is unchanged and still deliberate: for the turn feed, the stream must be open **before**
+the prompt is admitted; a prompt admitted while nothing is listening arms no watcher, so a later
+subscription may miss that settlement. The watcher is the same wait a blocking `session_prompt`
+performs (same `promptTimeoutMs` bound, same cancellation behaviour), one per request id, and a
+watch that timed out publishes nothing rather than claiming an ending it never saw. Push does not
+replace polling: a client that subscribes to nothing behaves exactly as before.
+
 ## Usage accounting
 
 DSH has no "session ended" event, so there is no hook to subscribe to and no final callback to
@@ -784,6 +942,14 @@ contributes an **MCP server** section to the settings panel. It edits the same `
 namespace the configuration above fills, so the panel and the file are two views of one
 value, not two copies.
 
+The same panel is also contributed to the **Plugins page**, under this bundle's own page — the
+host's `plugins.bundle.config` seat, keyed by the package name — so a setting can be changed there
+without opening the settings panel at all. Both entries render the same component over the same
+shared configuration form and publish from one snapshot, so they are two doors onto one value: a
+write made in either is visible in the other without a reload. The Plugins-page cell is registered
+only while the host serves this entry's form, exactly like the settings section; a host whose
+Plugins page declares no such seat simply shows no cell, and the settings entry is unaffected.
+
 The panel covers every setting including the `agentTools.allow` and `agentTools.deny` lists,
 which are edited as comma-separated text. Both are ordinary `string[]` values, so an entry with a
 comma in it cannot be expressed here; use the configuration file for that.
@@ -816,9 +982,10 @@ layer — inside that layer's Host/Origin and browser-cookie fence, so it inheri
 authorization and is never exposed on a bare port. `dsh_info` still reports only the token's
 source: a caller that authenticated with the token does not need it echoed into its transcript.
 
-The panel is a `settings.section` page the browser half registers through
-`ctx.configForms.whileServed`, so it appears only while the host actually serves this entry's
-form. That needs `@deepseek-ai/schemastery`: DSH 0.2.0-rc.2 projects a form only for an entry
+Both seats — the `settings.section` page and, where the host declares it, the Plugins page's
+`plugins.bundle.config` cell — are registered through `ctx.configForms.whileServed`, so each
+appears only while the host actually serves this entry's form. That needs
+`@deepseek-ai/schemastery`: DSH 0.2.0-rc.2 projects a form only for an entry
 whose `Config` carries a `toJSON()`, and it keeps only fields marked `meta.volatile`. There is
 no schemastery-free path to a panel, so the module is a declared peer and imported directly —
 without it the plugin cannot be imported at all, which is why the compatibility range below is
@@ -834,13 +1001,16 @@ but a deployment can switch the capability off.
 
 | Tool group | Requires | Notes |
 | --- | --- | --- |
-| `dsh_info`, `session_usage` (by id) | nothing beyond the durable log | `session_usage` by id works as long as the log is readable (`sessionQuery`, or the controller's `inspect` fallback) |
+| `dsh_info`, `session_usage` (by id) | nothing beyond the durable log | `session_usage` by id works as long as a whole-log reader is present (`sessionQuery`, or the controller's `inspect` on ≤0.1.7; 0.2.2 removed `inspect`, and usage deliberately does not fall back to the bounded `events` page because it would under-count) |
 | `session_create` / `session_list` / `session_prompt` / `session_messages` / `session_cancel` / `session_fork` / `session_rename` / `session_set_model` | `sessionController` | the bridge waits for it only where it must (`session_create`/`prompt`); elsewhere the tool reports the missing service |
 | `session_search` | `sessionController.search` **and** a session-query index that is open | `session-query-sqlite` ships with `openAt: "never"`; set it to `startup` or `first-search` to enable search |
+| `worktree_create` / `worktree_restore` / `session_create { worktree }` | `worktrees` **and** `sessionController.resolveAgent` | the forge bundle in DSH Desktop/Web provides the service (`@deepseek-ai/dsh-experimental-forge-bundle`); a bare profile has none, `dsh_info.toolAvailability` reports the tools unavailable, and `session_create { worktree }` is refused before the session exists. Git and Node must exist in the session's execution world |
+| `session_status.workingDirectory` / `session_status.worktree` / `session_list { includeWorktree }` | readable session projections (`sessionController.projections` or `sessionQuery.observeSession`) | optional: without them both replies omit those two fields and the rest is unchanged |
+| `session_archive` / `session_unarchive` / `session_pin` / `session_unpin` | `workspaceRegistry.archiveSession` / `pinSession` | the same registry sets the DSH sidebar's actions write; if the methods are missing the tools are reported unavailable |
 | `workspace_*` | `workspaceRegistry` | provided by the base bundle in normal profiles |
 | `file_*` | `fs` | the deployment's sandbox policy still applies; `file_read_image` additionally needs a supported image format |
 | `shell_*` | `shell` | `shell_run` uses `run()` when present and `execute()` otherwise; background jobs need `start()` or `execute()` |
-| `dsh_tool_list` / `dsh_tool_call` | `tools` **and** `sessionController.resolveAgent` | the allow-list is applied on top of the session's own policy |
+| `dsh_tool_list` / `dsh_tool_call` | `tools` **and** `sessionController.resolveAgent` | `dsh_tool_call` auto-detects the host's tool-execution contract (single-call ≤0.1.7, batch on 0.2.2+); the allow-list is applied on top of the session's own policy |
 | money in usage replies | `costMeter` | a third-party price plugin (`dsh-cost-meter`); absent by default, and the reply says so |
 | `approval.policy: "allow"` | `approval` **and** a resolvable agent | absent service or agent means the create/fork reply reports `approvalPolicyError` |
 | `http.mountOnWebServer` | `webServer` | the plugin waits for it and mounts; `dsh_info.mountNote` says while it is still waiting |
@@ -853,6 +1023,15 @@ but a deployment can switch the capability off.
   included) *before* the plugin is imported; an incompatible install is refused unless the host
   grants an exact-version exemption (`dsh plugin allow-version`).
 - **Node** `^22.19.0 || >=24.0.0`.
+- **MCP protocol eras.** One URL serves both the modern 2026-07-28 per-request protocol
+  (`server/discover`, self-contained requests) and the 2025-era Streamable HTTP flow
+  (`initialize` → `Mcp-Session-Id`, then stateful `POST`/`GET`/`DELETE`). A 2025 client that never
+  takes the session id keeps the previous stateless serving unchanged, where `GET`/`DELETE` answer
+  `405`; only a stateful session's `GET` is the push channel. Stateful sessions are capped at 8 and
+  closed after 30 minutes idle (an evicted client re-initializes on the `404`), and the server does
+  not implement resumability: `Last-Event-ID` replay is deliberately absent because every
+  notification is payload-less, so a reconnecting client just re-reads the resource. The bundled
+  `bin/mcp-stdio.mjs` uses the same stateful flow and forwards the stream's frames to stdout.
 - The `@deepseek-ai/dsh` peer is declared **optional**, purely so `dsh plugin add` does not pull
   a full harness install into every profile just to satisfy it. Optional only changes
   installation — DSH's compatibility gate reads `peerDependencies` regardless of
@@ -867,8 +1046,38 @@ but a deployment can switch the capability off.
   settings model**; on a 0.1.x runtime the endpoint still runs from the configuration file, but
   there is no panel, because that runtime only projects a form for a namespace a plugin
   registered through the removed call.
+- **The Plugins-page seat is optional too.** The browser half registers into
+  `plugins.bundle.config` only when the Plugins page declares that seat and the entry's form is
+  being served; a host whose Plugins page declares none shows no configuration cell there, and
+  the settings section keeps working unchanged. The seat is keyed by the bundle's package name,
+  which is what the page dispatches — a different key would render nothing, silently.
+- **0.2.2's tool-execution contract is auto-detected.** DSH 0.2.2 replaced
+  `ctx.tools.execute`'s single-call input/output with a batch contract (raw calls with JSON-string
+  arguments in, a `{ results }` batch out), which made `dsh_tool_call` fail with "Tool batch
+  execution failed" while `dsh_tool_list` kept working. The driver now tells the two shapes apart
+  by `tools.resolve` (shipped together with the batch executor), sends one call in the right
+  envelope, and unwraps its result, so the same build works on ≤0.1.7 and 0.2.2+; the allow-list
+  and scope checks run before either path.
+- **0.2.2 removed `sessionController.inspect`.** Log reads now prefer `sessionQuery`, keep using
+  `inspect` on ≤0.1.7, and on 0.2.2 fall back to the controller's `events` message-aligned pages —
+  enough for "what is open now" and for the transcript, though a bounded page can cover less of a
+  very long log. Usage needs the whole log and deliberately does not use the paged reader, because
+  it would silently under-count: without `sessionQuery` (or `inspect` on ≤0.1.7) it reports an
+  explicit capability error instead of the `TypeError` a missing method used to produce.
+  `session_search` remains disabled on shipped Desktop profiles regardless: the `session-query`
+  index is configured with `openAt: "never"`, and the tool explains that instead of searching.
+- **Worktrees (Git).** `worktree_create`, `worktree_restore` and `session_create { worktree }`
+  need `ctx.worktrees`, first verified in DSH `0.2.2-rc.1` and provided by the experimental forge
+  bundle (`@deepseek-ai/dsh-experimental-forge-bundle`) that Desktop/Web compose. On an older or
+  bare profile the worktree tools are reported unavailable in `dsh_info.toolAvailability` and
+  `session_create { worktree }` is refused before a session is created; the rest of the endpoint
+  is unchanged. `session_status.workingDirectory` and `session_list { includeWorktree }` also work
+  without the forge bundle when a projections reader is available; without one the two fields are
+  omitted rather than guessed.
 - **Usage needs the session log.** Token figures are folded from the durable log through
-  `sessionQuery` (preferred) or `sessionController.inspect`; `dsh_info` reports this as
+  `sessionQuery` (preferred) or, on ≤0.1.7, `sessionController.inspect`; 0.2.2 removed `inspect`,
+  and its bounded `events` page is deliberately not used for usage because it would under-count, so
+  a 0.2.2 profile without `sessionQuery` reports `tokenUsage: false`. `dsh_info` reports this as
   `tokenUsage`. Without either, a `session_prompt` reply says `usageUnavailable` with a reason
   instead of pretending the turn was free, the session tools keep working, and `session_usage` with
   a `sessionId` returns an `error` row (its totals exclude it). Without a `sessionId` it reports the
@@ -912,7 +1121,20 @@ but a deployment can switch the capability off.
   write goes through `ctx.fs`, so the same path rules and sandboxing the DSH agent lives
   under apply to the caller.
 - **No session deletion.** The harness offers `archiveSession`/`unarchiveSession` but no
-  delete, so neither does this plugin.
+  delete, so neither does this plugin. `session_archive`/`session_unarchive` and
+  `session_pin`/`session_unpin` write the same registry sets the DSH sidebar's actions write, and
+  `session_list` reports each row's `archived`/`pinned` flags. Archiving keeps the log and is
+  reversible; nothing here removes a transcript.
+- **Push is a change signal, not a payload.** Every feed is a synthetic resource: a notification
+  names one URI and `resources/read` returns the JSON, which is the only payload-carrying event a
+  2026-07-28 subscription can receive and the same shape a 2025 session's GET stream can carry
+  unchanged. One publish surface feeds both transports — the modern handler's subscription bus and
+  every live stateful 2025 session — so the two eras cannot disagree about which resource changed.
+  Publishes are coalesced per URI at 150 ms (turn settlement immediate), the assistant buffer is
+  bounded and only collects while a feed has subscribers, the job feed reads a retained,
+  non-consuming tail, and a dropped stream is recoverable by one read because the notification
+  itself carried nothing to lose. `session.scope: "owned"` applies to publishes as well as reads,
+  so the push channel cannot be used to probe session ids the tools would refuse.
 
 ## Development
 
@@ -958,11 +1180,15 @@ build:
 
 | Tool groups enabled | Tools advertised | Last result |
 | --- | --- | --- |
-| all six | 29 | live-checks 195/195 with `--with-model --with-subagent` and acceptance 166/166 — one boot, search index open |
-| `session`, `usage` only | 14 | live-checks 95/95 with `--with-model` (file/shell/workspace sections skip) |
-| `workspace`, `session`, `agentTools`, `usage` | 19 | live-checks 64/64 (a disabled group's reason names its `tools.<group>` switch) |
+| all six | 35 | live-checks 195/195 with `--with-model --with-subagent` and acceptance 166/166 — one boot, search index open |
+| `session`, `usage` only | 20 | live-checks 95/95 with `--with-model` (file/shell/workspace sections skip) |
+| `workspace`, `session`, `agentTools`, `usage` | 25 | live-checks 64/64 (a disabled group's reason names its `tools.<group>` switch) |
 | `files`, `shell` only | 11 | live-checks 68/68 (session/usage/queue/search sections skip) |
 
+The advertised counts are the current surface (0.53.0: 18 session-group tools and 35 overall); the
+last-result column records runs made against 0.52.86, before the six new tools, and has not been
+re-measured for this release.
+
 A fifth shape, `mountonly`, boots with `http.enabled: false` and `mountOnWebServer: true` and
 checks the endpoint over DSH's own web server: 109/109, all cheap, including the assertions that
 `dsh_info` reports `listening: false`, `mountedOnDshWebServer: true` and an endpoint string that