dsh-as-mcp 0.53.0 → 0.55.0

package/CHANGELOG.md

@@ -6,6 +6,105 @@ 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.55.0
+
+- Three new tools in the `session` group — `session_command_list`, `session_command` and
+  `session_goal` — bring the surface from 35 to 38 (the group from 18 to 21). A slash command
+  executes **without a model turn** (the registry parses the line and invokes the handler directly),
+  so `session_command` is the cheap half of "do what a human typing into the DSH composer would
+  do": compact a long session, export its log, enter plan mode or set a goal. `session_command_list`
+  reports every command the session's agent can see, with its description and input hint, and marks
+  each `permitted` instead of hiding the refused ones; `session_command` takes the line with or
+  without its leading slash and with arguments in the same string (`"compact"`, `"/export"`,
+  `"/goal <objective>"`, `"/plan off"`), and the run goes through the harness's own command
+  registry, so it is the same execution a human typing the line produces (the reply carries the
+  harness's `commandId`, `ok`, the handler's `text` and the `sourceEventSeq` it recorded). The
+  admitted set is explicit — `/compact`, `/plan`, `/goal`, `/export` — not "anything the registry
+  lists": `/permission` would change the session's permission preset (a remote caller must not
+  escalate its own session) and `/feedback` writes the user's own review records, so both are
+  refused **before** any handler runs — a refused call writes nothing to the session log — and an
+  unknown name is refused with the admitted set listed. A handler that reports an error comes back
+  as `ok: false` with its text, while a name/argument the registry did not admit is an error saying
+  nothing was logged.
+- `session_goal` reads and mutates the session's **durable goal** — the long-running objective the
+  harness's round driver keeps advancing across turns, which is how a caller delegates multi-hour
+  work instead of holding one turn open. `action` is `get` (the goal, or `null`) or
+  `create`/`edit`/`pause`/`resume`/`complete`/`clear`; `create` needs `objective`, `edit` needs
+  `objective` and/or `maxGoalRounds`, and every other action acts on the goal that exists now, so
+  its ref comes from a read rather than from the caller. `expectedRevision` (from a previous read) is
+  the lost-update guard: a mutation whose goal changed underneath — say the user edited it in the DSH
+  UI a moment ago — is refused instead of silently applied, the same spirit as the UI's conflict
+  handling. A goal reports `id`, `revision`, `objective`, `phase` (`active`/`paused`/`blocked`/
+  `complete`), `activation` (`armed`/`disarmed`), `maxGoalRounds`, `roundsStarted`, `blockedReason`
+  when blocked and its timestamps; `clear` returns `goal: null` with `cleared: true`, and `complete`
+  returns the completed goal.
+- `dsh_info.harnessServices` reports two more probes, `commands` and `goals` (29 in total, up from
+  27), and `toolAvailability` pre-flights the three tools against `sessionController` +
+  `sessionController.resolveAgent` plus the matching service, so an agent-scoped command or goal
+  service that a profile does not mount is reported unavailable instead of failing at call time.
+  `dsh_info.notes` gains one paragraph per surface: commands run without a model turn and only the
+  user-plane set is admitted, and goal mutations carry the harness's revision guard.
+- No new configuration keys: push, the two transports, the tool groups and the settings panel are
+  unchanged. Both READMEs gain the three tool rows, a "Session orchestration" flow and a
+  deployment-requirements row; `docs/CAPABILITY-GAPS.md` is re-counted to 38 tools and 29 probes and
+  marks slash commands and durable goals as shipped, with `resolveAgent` named as the bridging layer.
+  `tests/orchestration.test.ts` pins the new driver surface (allow-list before the handler, slash
+  normalization, the revision guard, projection of the goal view) and `tests/mcp-endpoint.test.ts`
+  the argument passthrough; `tests/availability.test.ts` covers the new pre-flight rules.
+
+## 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 —

package/CHANGELOG.zh.md

@@ -6,6 +6,20 @@
 - 两份文件的**版本标题必须完全一致**（集合与顺序），由 `tools/check-docs.mjs` 强制检查——发布时漏写中文条目会让检查失败，中文读者不会悄悄落后一个版本。
 - 版本号遵循 SemVer；项目仍是 pre-1.0，所以 minor 是功能，patch 是修复或文档。
 
+## 0.55.0
+
+- 新增 3 个工具（`session_command_list`、`session_command`、`session_goal`），工具面从 35 增至 38，仍全在 session 组（该组从 18 增至 21）。斜杠命令**不消耗模型轮次**（注册表解析命令行后直接调用 handler），所以 `session_command` 就是「替人在 DSH 输入框里敲命令」的便宜一半：压缩长会话、导出日志、进入 plan 模式、设置目标。`session_command_list` 报出该会话 agent 能看到的全部命令（描述与输入提示），并用 `permitted` 标出本端点会执行哪些，而不是把被拒绝的隐藏掉；`session_command` 接受带或不带前导斜杠的命令行、参数写在同一字符串里（`"compact"`、`"/export"`、`"/goal <objective>"`、`"/plan off"`），执行走 harness 自己的命令注册表，与真人敲同一行的执行完全一致（回复带 harness 的 `commandId`、`ok`、handler 的 `text`，以及它记录的 `sourceEventSeq`）。放行集是显式的 `/compact`、`/plan`、`/goal`、`/export`，而不是「注册表里有什么就运行什么」：`/permission` 会改变会话的权限 preset（远程调用方不能给自己提权），`/feedback` 会写入用户自己的评审记录，两者在**任何 handler 运行之前**就被拒绝——被拒调用不向会话日志写任何东西；未注册的名字会被拒绝并列出放行集。handler 报错时返回 `ok: false` 与文本，注册表未接收的名字/参数返回「什么都没写进日志」的错误。
+- `session_goal` 读取和修改会话的**持久目标**——harness 的轮次驱动会在多轮之间持续推进的长期目标，调用方因此可以委派多小时的任务，而不必一直挂着一轮。`action` 取 `get`（返回目标或 `null`）或 `create`/`edit`/`pause`/`resume`/`complete`/`clear`；`create` 需要 `objective`，`edit` 需要 `objective` 和/或 `maxGoalRounds`，其余动作作用于当前存在的目标，其 ref 来自一次读取而不是调用方。`expectedRevision`（来自上一次读取）是丢失更新保护：目标在脚下被改过（比如用户刚在 DSH 界面里编辑过）就拒绝，而不是悄悄覆盖——与界面冲突处理同一思路。目标报出 `id`、`revision`、`objective`、`phase`（`active`/`paused`/`blocked`/`complete`）、`activation`（`armed`/`disarmed`）、`maxGoalRounds`、`roundsStarted`、被阻塞时的 `blockedReason` 与时间戳；`clear` 返回 `goal: null`（`cleared: true`），`complete` 返回已完成的目标。
+- `dsh_info.harnessServices` 新增 `commands` 与 `goals` 两个探针（共 29 个，原为 27 个）；`dsh_info.toolAvailability` 对三个新工具做预检，要求 `sessionController` + `sessionController.resolveAgent` 以及对应的 commands/goals 服务，缺能力的 profile 会把它们报成不可用，而不是等到调用时才失败；`dsh_info.notes` 各增一段（命令不消耗轮次且只放行用户面集合；目标修改带 harness 的 revision 保护）。
+- 无新增配置键：推送、两种传输、工具组与设置面板均不变。两份 README 增加三行工具表、「会话编排 / Session orchestration」流程与部署要求行；`docs/CAPABILITY-GAPS.md` 的工具数/探针数更新为 38/29，并把斜杠命令与持久目标两条差距标记为已交付、点名 `resolveAgent` 是打通它们的桥。`tests/orchestration.test.ts` 钉住新驱动面（handler 之前的 allow-list、斜杠归一化、revision 保护、目标投影），`tests/mcp-endpoint.test.ts` 钉住参数透传，`tests/availability.test.ts` 覆盖新的预检规则。
+
+## 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 依然没有删除会话。

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,7 +230,7 @@ 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. |
@@ -250,6 +252,9 @@ schema-aware client can read the object directly instead of parsing JSON out of
 | `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_command_list` | The slash commands this session's agent can run — each with a one-line description, an optional `input` hint and a `permitted` flag — so a caller can see that a command exists while this endpoint deliberately will not run it (the admitted set is `/compact`, `/plan`, `/goal`, `/export`; `/permission` and `/feedback` are refused on purpose). A command executes without a model turn — the handler is invoked directly — which makes this the cheap way to compact a long session, export its log, enter plan mode or set a goal, exactly as a human typing into the DSH composer would. Read-only; run one with `session_command`. |
+| `session_command` | Execute one slash command against a session's agent without spending a model turn, as if the human had typed it into the DSH composer: give the `command` with or without its leading slash, with its arguments in the same string (`"compact"`, `"/export"`, `"/goal <objective>"`, `"/plan off"`). The run goes through the harness's own command registry, so it is the same execution a human typing the line produces and the session log records it; the reply carries the harness's `commandId`, `ok` (`false` when the handler itself reported an error result), the handler's `text` and the `sourceEventSeq` it recorded when it reported one. Only the user-plane commands are admitted (`/compact`, `/plan`, `/goal`, `/export`); `/permission` (which would change the session permission preset) and `/feedback` (which would write the user's own review records) are refused before any handler runs, so a refused call writes nothing to the session log, and a name that is not registered on this profile is refused with the admitted set listed. A name or argument the registry did not admit is an error saying nothing was logged. Call `session_command_list` first to see the exact names and the input hint this agent accepts. |
+| `session_goal` | Read or mutate the session's durable goal — the long-running objective the harness's round driver keeps advancing across turns, which is how a caller delegates multi-hour work instead of holding one turn open. `action` is `get` (which returns the `goal` or `null`), or one of `create` (needs `objective`), `edit` (needs `objective` and/or `maxGoalRounds`), `pause`, `resume`, `complete`, `clear`; every action except `create` acts on the goal that exists now, so its ref comes from a read rather than from the caller. Pass `expectedRevision` (from a previous read) to refuse a mutation whose goal changed underneath you — the equivalent of the DSH UI's conflict handling. A goal reports `id`, `revision`, `objective`, `phase` (`active`/`paused`/`blocked`/`complete`), `activation` (`armed`/`disarmed`), `maxGoalRounds`, `roundsStarted`, `blockedReason` when blocked, and `createdAt`/`updatedAt`; `clear` returns `goal: null` (and `cleared: true`), while `complete` returns the completed goal. |
 | `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. |
@@ -309,6 +314,33 @@ refused *and* hidden from `dsh_tool_list`. The omissions that matter:
 An operator can widen this deliberately with the `agentTools.allow` setting, or subtract from
 the default with `agentTools.deny`.
 
+### Session orchestration
+
+Some work is not a single prompt. Compacting a long session, exporting its log, entering plan mode or
+setting a goal are user-plane actions a human performs by typing a slash command into the DSH
+composer; a durable goal also turns a one-turn request into an objective the harness's round driver
+keeps advancing across turns. Neither path costs a model turn of its own. The intended flow:
+
+```
+session_command_list { sessionId }                                    # what this agent accepts; permitted marks the admitted set
+  -> session_command { sessionId, command: "/compact" }               # run one; no model turn
+  -> session_goal { sessionId, action: "create", objective: "Finish the migration", maxGoalRounds: 20 }
+  -> session_goal { sessionId, action: "get" }                        # poll phase/revision...
+     or subscribe to dsh://session/<id>/projections                   # ...or be told when the goal changes
+  -> session_goal { sessionId, action: "pause", expectedRevision: 3 } # then resume / complete / clear
+```
+
+`session_command_list` reports each entry's `permitted` flag instead of hiding the refused commands, so
+a caller can see that `/permission` and `/feedback` exist on the profile and that this endpoint
+deliberately will not run them: `/permission` would change the session's permission preset and
+`/feedback` would write the user's own review records, and neither reaches a handler or writes anything
+to the session log. `session_status` reports the session's turn and log state, not the goal itself; the
+goal's phase and revision come from `session_goal { action: "get" }`, and the
+`dsh://session/<id>/projections` feed (which includes `goal`) publishes when it changes, so following a
+goal is a poll or a subscription rather than a prompt per turn. A mutation without `expectedRevision`
+acts on the goal that exists at that moment; pass the revision a read returned when two supervisors
+could race.
+
 ## Worktrees
 
 A session can work in its own Git checkout of the same repository. The operation is the one the
@@ -353,29 +385,107 @@ into its rows. The full host-side contract — service signatures, grouping proo
 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`.
 
-## Turn notifications for modern clients
-
-`session_prompt { wait: false }` returns as soon as the message is admitted, so the universal
-reporting path is polling `session_status` (optionally with `waitMs`). A client speaking the modern
-**2026-07-28** MCP protocol can be *told* instead of polling, over that protocol's
-`subscriptions/listen` stream:
-
-1. **Before prompting**, open one `subscriptions/listen` request and keep it open, naming the feed
-   you want: `notifications: { resourceSubscriptions: ["dsh://session/<sessionId>/turn"] }`. The
-   server answers `notifications/subscriptions/acknowledged` on that stream.
-2. Call `session_prompt` with `wait: false`.
-3. When that turn settles — completed, failed, cancelled, or gone without an ending — the server
-   publishes `notifications/resources/updated` for that URI on the stream. `resources/read` on the
-   same URI returns the same payload as `session_status`, including `failure` and `lastTurn`.
-
-Two bounds are deliberate. 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 event.
-And push exists only in the modern protocol: 2025-era clients — including `bin/mcp-stdio.mjs` and
-the bundled smoke/exercise scripts — have no listen method. They are unaffected: polling stays the
-universal path, and a fire-and-forget prompt with no subscriber costs exactly one durable read, as
-before. 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.
+## 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
+38 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
 
@@ -927,6 +1037,7 @@ but a deployment can switch the capability off.
 | `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 |
+| `session_command_list` / `session_command` / `session_goal` | `sessionController.resolveAgent` **and** `commands` / `goals` | both services are agent-scoped, so the session's live agent is the bridge; a profile without them reports the three tools unavailable in `dsh_info.toolAvailability`, and each call names the missing service and the bundle that provides it |
 | `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()` |
@@ -943,6 +1054,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
@@ -1036,6 +1156,16 @@ but a deployment can switch the capability off.
   `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
 
@@ -1081,14 +1211,14 @@ build:
 
 | Tool groups enabled | Tools advertised | Last result |
 | --- | --- | --- |
-| 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) |
+| all six | 38 | live-checks 195/195 with `--with-model --with-subagent` and acceptance 166/166 — one boot, search index open |
+| `session`, `usage` only | 23 | live-checks 95/95 with `--with-model` (file/shell/workspace sections skip) |
+| `workspace`, `session`, `agentTools`, `usage` | 28 | 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.
+The advertised counts are the current surface (0.55.0: 21 session-group tools and 38 overall); the
+last-result column records runs made against 0.52.86, before the 0.53.0 additions, and has not been
+re-measured since.
 
 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