diff --git a/docs/webui.md b/docs/webui.md
index 9b522c14..efc69d7a 100644
--- a/docs/webui.md
+++ b/docs/webui.md
@@ -243,7 +243,7 @@ The fourth registered provider is the **`exec` transport** (M4-2) — the one-sh
 | sessionCrud | partial — missing `createSession`, `listSessions`, `getSession`, `updateSession`, `renameSession`, `archiveSession`, `deleteSession`, `forkSession`, `getSessionForkOptions`, `loadSession`, `activateSession`. Only `--session` / `--continue` exist, and they re-enter a session rather than choose one |
 | streamingSend | full (`--input -` plus the `stream-json` event stream) |
 | interrupt | none — interface-absent: nothing to call. The SIGINT/SIGTERM/SIGHUP in `packages/tui/src/cli/run-exec-command.ts` are signals webui sends to the child **it** spawned, i.e. webui's own kill cascade, not a capability the transport offers |
-| toolSkillInvocation | partial — missing `listSkills`, `listRuntimeSkills`, `listPendingPermissions`, `replyPermission`, `setMode`. The transport PRODUCES `tool_call` items and webui does not read them; and `--permission` is fixed at spawn time (the CLI says `ask` requires TUI/ACP), so there is no permission request/reply pair |
+| toolSkillInvocation | partial — missing `listSkills`, `listRuntimeSkills`, `listPendingPermissions`, `replyPermission`, `setMode`. The transport PRODUCES `tool_call` items and webui consumes but does not render them; and `--permission` is fixed at spawn time (the CLI says `ask` requires TUI/ACP), so there is no permission request/reply pair |
 | turnDiff | none — interface-absent, **servedBy `local-runtime-v2`** |
 | turnRewindRedo | none — interface-absent (`mcode exec review` reviews local git changes and carries no turn coordinate, so it is not a rewind surface) |
 | plugins | none — interface-absent, **servedBy `local-runtime-v2`** |
@@ -257,7 +257,20 @@ The fourth registered provider is the **`exec` transport** (M4-2) — the one-sh
 
 Three cells are **weaker** than acp, and for structural reasons rather than unfinished engine work: `interrupt` (acp has a cancel notification, exec has nothing to declare one on), `subagents` (acp can parse sub-agent activity off its stream, exec's event union has no such kind) and `authCredentials` (acp has two RPC methods, exec has no channel). The reverse exception is the same two keys for the same reason, which is a finding rather than a copy: `/api/turn-diff*` and `/api/plugins*` project the in-process v2 host and gate on **no transport**, so every transport inherits it.
 
-**A known mismatch this audit surfaced, recorded rather than hidden.** The three event names `collectExecResult` branches on — `delta`, `message`, `exec.result` — are the *supervisor's internal* stream-event names. `--output-format stream-json` writes only what `ExecEventProjector` produces (`packages/tui/src/headless/output.ts` refuses the format with no projector, and `packages/tui/src/headless/runner.ts` always supplies one), so the wire carries the ten `ExecEvent` types and the two name families do not intersect. That is a real gap in the exec data plane. M4-2 does not fix it — the batch registers a declaration and changes no routing — but it is pinned in `EXEC_INTERFACE.consumedEvents` and asserted by a test that fails if the intersection ever becomes non-empty in either direction.
+**The mismatch this audit surfaced, and what it cost.** The three event names `collectExecResult` branched on — `delta`, `message`, `exec.result` — are the *supervisor's internal* stream-event names. `--output-format stream-json` writes only what `ExecEventProjector` produces (`packages/tui/src/headless/output.ts` refuses the format with no projector, `packages/tui/src/headless/runner.ts` always supplies one, and the encoder's `result()` leg goes through `projector.complete()` rather than writing the `ExecResult` itself), so the wire carries the ten `ExecEvent` types and the two name families did not intersect.
+
+That was not a missing feature but a **dead data plane**, and it is worth spelling out what a user saw on `MCODE_USE_ACP=0` — and on every non-`Full access` permission mode, which silently re-routes to exec: reasoning and answer text streamed in and never landed, the turn ended with no answer line at all, the context counters never moved, and the follow-up turn started a brand-new engine session because the session id was never read back. D1 rewrote the consumer against the wire:
+
+| Wire event | Consumed as |
+| --- | --- |
+| `sessionId` on every line | the engine session this run entered, written back to `cs.mcodeSessionId` so the next turn continues it |
+| `item.started` / `item.updated` | `item.contentDelta` appended to the answer / reasoning accumulator and streamed as a `●` / `▲` line |
+| `item.completed` | `item.content`, adopted only for an item that never streamed a delta |
+| `turn.completed` | per-turn `usage` and `durationMs` |
+| `turn.failed` | `status` and `error` |
+| `exec.completed` | the terminal `ExecResult`, and the call to `finalize()` |
+
+`EXEC_INTERFACE.consumedEvents` now names exactly those six, `EXEC_INTERFACE.baseOnlyEvents` names the four that carry nothing beyond `ExecEventBase`, and a test asserts the two partition the union, that the parser's `switch` arms are the same set, and that every consumed name is one the wire can emit. A `tool_call` item is consumed but not rendered — it carries a `toolCall` payload rather than text — which is why `toolSkillInvocation` stays `partial`.
 
 **`servedBy` is the plan's one reverse exception, and it is load-bearing.** `turnDiff` and `plugins` are honestly `none` on the protocol, and the three `/api/turn-diff` and ten `/api/plugins` endpoints still work on the default acp transport, because they project the in-process local-runtime-v2 host through `getEngineCatalogueHost()` and are gated on no provider declaration. Reading the level alone would eventually 501 two working features the moment a frontend consulted the transport's provider instead of the default one. `summarizeCapabilityHosting(capabilities)` and `resolveCapabilityHostProvider(providerId, key)` expose the routing fact; the hosted keys deliberately stay in `summarizeUnavailableCapabilities`, because the provider really has none and that `{none, partial}` shape is already on the wire. The `exec` provider carries the same two fields for the same structural reason, which is what makes `servedBy` a per-key declaration field rather than an acp special case.
 
@@ -1648,6 +1661,27 @@ implementation accident:
 The `mermaid` dependency (11.12.1, MIT) is recorded in
 `release/dependency-licenses.json`.
 
+### Raw HTML in Markdown is text, never markup (P17)
+
+HTML written into a Markdown source — an assistant message, an activity
+group, a `.md` file preview — is **shown as the source text**. It is never
+parsed into DOM elements. That is the whole contract; the rest is how it is
+kept, and how you would notice a regression.
+
+| Aspect | Contract | Backed by |
+| --- | --- | --- |
+| Author HTML | Inline and block HTML are escaped, so a pasted `<svg><path …/></svg>`, a `<div onclick=…>`, or a `<script>` block appears verbatim as text. The prose around it is unaffected — one snippet does not blank the message | `webapp/lib/markdown.ts` (the `renderer.html` override) |
+| Why the parser and not the sanitiser | `marked` has no "no raw HTML" option: without the override the snippet reached the tag allowlist, which admits `svg`/`path` for KaTeX geometry, and `components/markdown-html.tsx` then called `createElement("path")` — an unknown host element, and one `The tag <path> is unrecognized in this browser` console error per occurrence (nine in a single UAT round; `doc/uat/2026-10-03-16-master-sub-agent-comm-redline1.md`, anomaly #2) | `webapp/lib/markdown.ts`, `components/markdown-html.tsx` (`htmlToReact`) |
+| Generated HTML is exempt | Markup this app *generates* never passes through that override: KaTeX arrives from the `webuiMath` inline extension and every fenced language from `registerLanguageRenderer`, both of which return their HTML directly. Formula geometry — real `<svg>`/`<path>` — therefore still renders | `webapp/lib/math-renderer.ts`, `webapp/lib/markdown.ts` (`safeLanguageRenderer`) |
+| Line structure | A block snippet keeps its original line breaks; escaping never collapses a multi-line paste onto one line | `webapp/lib/markdown.ts`, `webapp/test/markdown-raw-html.test.ts` |
+| How to tell it works | The regression suite asserts the React tree, not just the string: no `svg`/`g`/`path` element is ever created for author HTML, and a formula still creates `svg` + `path`. A change that lets a tag through turns the suite red, and so does one that over-tightens and kills formula geometry | `webapp/test/markdown-raw-html.test.ts` |
+
+Rejected alternatives: **rendering model-authored SVG** (an XSS surface — an
+`<svg>` can carry `<foreignObject>`, animation and event handlers, and the
+product intent is a transcript, not a renderer); **adding DOMPurify** (a
+multi-megabyte dependency to defend markup the app never needs, when the
+parser can refuse it outright).
+
 ### Code block wrapping and scrollbars (ticket 52)
 
 Every markdown codeblock — chat messages, activity groups and markdown
diff --git a/docs/webui.zh-CN.md b/docs/webui.zh-CN.md
index c02c180d..f701112b 100644
--- a/docs/webui.zh-CN.md
+++ b/docs/webui.zh-CN.md
@@ -255,7 +255,7 @@ host 对象（子进程没有对象可反射），而是线路表 `MCODE_ACP_CAP
 | sessionCrud | partial——缺 `createSession`、`listSessions`、`getSession`、`updateSession`、`renameSession`、`archiveSession`、`deleteSession`、`forkSession`、`getSessionForkOptions`、`loadSession`、`activateSession`。只有 `--session` / `--continue`，而它们是「重新进入」一个会话而非「挑选」一个 |
 | streamingSend | full（`--input -` 加上 `stream-json` 事件流） |
 | interrupt | none——接口无：没有可调的东西。`packages/tui/src/cli/run-exec-command.ts` 里的 SIGINT/SIGTERM/SIGHUP 是 webui 发给**自己 spawn 的**子进程的信号，即 webui 自己的 kill 级联，不是传输提供的能力 |
-| toolSkillInvocation | partial——缺 `listSkills`、`listRuntimeSkills`、`listPendingPermissions`、`replyPermission`、`setMode`。传输**产出** `tool_call` 项而 webui 不读它们；且 `--permission` 在 spawn 时就定死（CLI 明说 `ask` 需要 TUI/ACP），所以没有权限请求/应答对 |
+| toolSkillInvocation | partial——缺 `listSkills`、`listRuntimeSkills`、`listPendingPermissions`、`replyPermission`、`setMode`。传输**产出** `tool_call` 项而 webui 消费了它们却不渲染；且 `--permission` 在 spawn 时就定死（CLI 明说 `ask` 需要 TUI/ACP），所以没有权限请求/应答对 |
 | turnDiff | none——接口无，**servedBy `local-runtime-v2`** |
 | turnRewindRedo | none——接口无（`mcode exec review` 审阅本地 git 变更、不带回合坐标，所以不是 rewind 面） |
 | plugins | none——接口无，**servedBy `local-runtime-v2`** |
@@ -274,14 +274,34 @@ RPC 方法，exec 没有通道）。反向例外是同样两个键、同样一
 复制：`/api/turn-diff*` 与 `/api/plugins*` 投影的是进程内 v2 host，且**完全不按
 传输门控**，所以每条传输都继承它。
 
-**这条审计查出的一处错配，选择记录而非隐藏。** `collectExecResult` 匹配的三个
+**这条审计查出的一处错配，以及它的代价。** `collectExecResult` 匹配的三个
 事件名——`delta`、`message`、`exec.result`——是 **supervisor 内部**的流事件名。
 而 `--output-format stream-json` 只写 `ExecEventProjector` 的产出（`packages/tui/src/headless/output.ts`
-在没有 projector 时直接拒绝该格式，`packages/tui/src/headless/runner.ts` 总会提供一个），所以线路上跑的是
-那十个 `ExecEvent` 类型，两个名字族并不相交。这是 exec 数据面上的真实缺口。
-M4-2 不修它——本批只注册声明、不改路由——但它被钉在
-`EXEC_INTERFACE.consumedEvents`，并由一条「相交集一旦在任一方向变为非空就转红」
-的测试守住。
+在没有 projector 时直接拒绝该格式，`packages/tui/src/headless/runner.ts` 总会提供一个，
+且编码器的 `result()` 那条腿走 `projector.complete()` 而非直接写出 `ExecResult` 本身），
+所以线路上跑的是
+那十个 `ExecEvent` 类型，两个名字族并不相交。
+
+这不只是「少一个功能」，而是**一整条死掉的数据面**。值得把用户在
+`MCODE_USE_ACP=0` 下会看到什么写清楚——以及在每一种非 `Full access` 的权限模式下，
+因为那会静默改道到 exec：思考与回答的文本流进来却从不落地，回合结束时连一行回答
+都没有，上下文计数从不走动，而下一轮会另起一个全新的引擎会话，因为会话 id 从未被读回。
+D1 把消费面改回线路本身：
+
+| 线路事件 | 消费为 |
+| --- | --- |
+| 每一行都带的 `sessionId` | 本次运行进入的引擎会话，写回 `cs.mcodeSessionId`，使下一轮能续接 |
+| `item.started` / `item.updated` | `item.contentDelta` 追加进回答／思考累加器，并以 `●` / `▲` 行流式呈现 |
+| `item.completed` | `item.content`，仅对从未流出增量的 item 采纳 |
+| `turn.completed` | 每轮 `usage` 与 `durationMs` |
+| `turn.failed` | `status` 与 `error` |
+| `exec.completed` | 终态 `ExecResult`，以及 `finalize()` 的调用 |
+
+`EXEC_INTERFACE.consumedEvents` 现在正好点名这六个，`EXEC_INTERFACE.baseOnlyEvents`
+点名除 `ExecEventBase` 外无内容的另外四个，并由一条测试断言二者恰好划分整个联合、
+解析器的 `switch` 分支与之是同一集合、且每个被消费的名字都是线路真能发出的名字。
+`tool_call` item 会被消费但不会被渲染——它携带的是 `toolCall` 负载而非文本——
+这正是 `toolSkillInvocation` 停在 `partial` 的原因。
 
 **`servedBy` 是计划里唯一的反向例外，且有承重意义。** `turnDiff` 与 `plugins`
 在协议上如实 `none`，而那三个 `/api/turn-diff` 与十个 `/api/plugins` 端点在缺省
@@ -1220,6 +1240,39 @@ flowchart LR
 
 依赖：`mermaid` 11.12.1（MIT），已登记于 `release/dependency-licenses.json`。
 
+### Markdown 里的裸 HTML：按代码文本显示（P17）
+
+Markdown 源里写的 HTML——助手回复、活动组、`.md` 文件预览——一律**当作
+源码文本显示**，绝不会被解析成页面元素。这就是全部契约；下面是它靠什么
+维持、以及怎么发现它坏了。
+
+**你会看到什么**
+
+- 模型在推理或正文里贴 `<svg><path …/></svg>`，屏幕上是这段源码本身，
+  不是一张图，浏览器控制台也不会因为 `<path>` 报警。
+- `<div onclick=…>`、`<script>` 之类的片段同理：原样显示成文字。周围的
+  正文不受影响，一段 HTML 不会让整条消息消失。
+
+**为什么不是"把 SVG 画出来"**
+
+`<svg>` 能携带 `<foreignObject>`、动画与事件属性，渲染模型输出的 SVG
+等于开一个 XSS 面；而这个产品的定位是会话记录，不是渲染器。所以选择
+"安全显示为文本"，也没有为此引入 DOMPurify 这类重型依赖——问题出在解析
+层允许裸 HTML 透传，在解析层拒绝即可（`webapp/lib/markdown.ts`）。
+
+**为什么不影响公式**
+
+本应用**自己生成**的 HTML 不走这条规则：KaTeX 由行内扩展产出、各代码围栏
+由语言渲染器注册表产出，两者都直接返回自己的 HTML。因此公式的几何图形
+（真正的 `<svg>`/`<path>`）照常渲染（`webapp/lib/math-renderer.ts`）。
+
+**怎么发现它坏了**
+
+回归用例断言的是 React 树而不只是字符串：作者写的 HTML 永远不会生成
+`svg`/`g`/`path` 元素，公式仍然生成 `svg` + `path`。往松了改（放行标签）
+或往紧了改（连公式几何一起转义）都会让用例变红
+（`webapp/test/markdown-raw-html.test.ts`）。
+
 ### 代码块的换行与滚动条（工单 52）
 
 所有 markdown 代码块——聊天消息、活动组、markdown 文件预览——都经同一
diff --git a/packages/webui/docs/API.md b/packages/webui/docs/API.md
index a6add1dc..5dd62045 100644
--- a/packages/webui/docs/API.md
+++ b/packages/webui/docs/API.md
@@ -470,6 +470,177 @@ of truth for the mcode-side result.
 **Response 404** `{"ok": false, "error": "session not found"}` — id
 matches neither a webui session nor an `mvs_*` pattern.
 
+### The session context actions
+
+Four endpoints behind the session row's right-click menu (归档 / 置顶 /
+复制为新会话). They are grouped here because they share one facade
+(`server/engine/session-context-actions.js`) and one error vocabulary; the
+individual sections follow.
+
+| Endpoint | Body / query | What it does |
+|---|---|---|
+| `POST /api/sessions/:id/archive` | `{ "archived": boolean }` | Archive or unarchive **one** session. |
+| `POST /api/sessions/:id/pin` | `{ "pinned": boolean }` | Pin or unpin one session. |
+| `GET /api/sessions/:id/fork-options` | `?assistantMessageId=` | Describe what a duplicate would be, before making one. |
+| `POST /api/sessions/:id/fork` | `{ "assistantMessageId"? }` | Duplicate the conversation as a new session in the same workspace. |
+
+#### `POST /api/sessions/:id/archive`
+
+Sets the engine's `archived` flag on one session. One method covers both
+directions (`lifecycle-application.ts#archiveSession` reads
+`req.archived !== false`), so `archived` **selects** the direction rather
+than separating two endpoints. The archived-tasks settings page restores a
+row by calling this same endpoint with `archived: false`.
+
+`archived` defaults to `true` and is **not** type-checked, deliberately: the
+engine's own rule is "anything that is not literally `false` archives", and
+a validator that disagreed with it would make the HTTP layer and the engine
+answer differently about the same request.
+
+The sidebar reads `WHERE archived = 0`, so an archived session leaves the
+tree on the next read and an unarchived one returns. The response also
+invalidates the tree cache, so the change is visible immediately rather than
+after the 15 s TTL.
+
+Not gated by the `authorize()` modal, unlike `DELETE /api/sessions/:id`:
+archive is **reversible** — the conversation is intact on the engine and the
+same call restores the row. A confirm dialog on a reversible action is a
+dialog the user learns to dismiss.
+
+**Request** `{ "archived": true }` — `archived` optional, defaults to `true`.
+
+**Response 200** `{ "ok": true, "id": "mvs_…", "archived": true }`
+
+**Errors** — 400 missing id; 501 the provider cannot archive
+(`engine_capability_not_supported`); 502 the engine was asked and failed
+(`engine_archive_failed`); 503 no runtime booted
+(`engine_host_unavailable`).
+
+#### `POST /api/sessions/:id/pin`
+
+Pins or unpins one session through the engine's `PinService`, and returns
+the engine's whole pinned set in its own order so a client can re-render
+without a second tree read.
+
+`pinned` is **required** and is not defaulted. The engine's
+`pinSession(sessionId, pinned, insertIndex?)` takes the flag positionally
+and branches on it, so `{}` is not a defaultable request: defaulting it
+would move the row in a direction the user did not choose. This asymmetry
+with `archive` is the engine's, not the route's.
+
+This endpoint is the family's only member read through the **PB-8
+host-services window** rather than through `host.cliService`, and it is
+therefore the only one whose absence cases are all three distinct:
+
+| State | `code` | Status | Meaning |
+|---|---|---|---|
+| no runtime booted | `engine_host_unavailable` | 503 | The process is not running its runtime. |
+| host with no owner graph | `engine_services_unavailable` | 501 | This transport carries no V2 `services`. |
+| owner graph without `pinService` | `engine_member_unavailable` | 501 | The member this endpoint needs is not composed. |
+
+None of the three produces a success payload. A pin that "succeeded" without
+writing anything is the fake-success shape this repository refuses.
+
+**Request** `{ "pinned": true }`
+
+**Response 200**
+```json
+{ "ok": true, "id": "mvs_…", "pinned": true, "pinnedIds": ["mvs_a", "mvs_b"] }
+```
+
+**Errors** — 400 missing id or non-boolean `pinned`; 501 / 503 as tabled
+above; 502 the engine was asked and failed (`engine_pin_failed`).
+
+#### `GET /api/sessions/:id/fork-options`
+
+Answers "what would duplicating this session be?" before the user commits to
+one. The duplicate dialog is this read, rendered: the engine's own `canFork`
+decides whether the confirm button is live, and its `suggestedTitle` is shown
+so the user sees the title the fork will use.
+
+`?assistantMessageId=` narrows the preview to a fork POINT. Omitted, the
+preview describes forking the whole conversation — which is what the menu
+item means when the user has not picked a message.
+
+Every field is present on every answer, so a partially-shaped engine response
+renders an empty row rather than `undefined`. The `worktree` triple is
+carried through **untouched and unread**: the worktree variant of this menu
+has no desktop reference to build against, so it stays an honest placeholder
+and the fields travel for the batch that unblocks it.
+
+**Response 200**
+```json
+{
+  "ok": true,
+  "id": "mvs_…",
+  "canFork": true,
+  "unavailableReason": null,
+  "suggestedTitle": "Copy of Refactor the parser",
+  "nextForkOrdinal": 2,
+  "sourceTitle": "Refactor the parser",
+  "worktree": { "visible": true, "eligible": false, "unavailableReason": "not a git repository" }
+}
+```
+
+A read that fails is **propagated**, not turned into `canFork: false`. A
+default-shaped options object would put "canFork: false" on screen as if the
+engine had refused a fork it was never asked about; the client has to be able
+to tell "the engine said no" from "we could not ask".
+
+**Errors** — 400 missing id; 501 / 503 as above; 502
+(`engine_fork_options_failed`).
+
+#### `POST /api/sessions/:id/fork`
+
+Duplicates the conversation as a new session in the same workspace.
+
+Two fields are **forced server-side** and cannot be set by the caller:
+
+- `useSuggestedTitle: true` — the fork's title comes from the engine's own
+  suggestion. The dialog SHOWS that suggestion, so the user sees exactly the
+  title that will be used. A caller-supplied `title` is dropped: this
+  endpoint has one title contract.
+- `createIsolatedWorktree: false` — the worktree variant of the menu is a
+  placeholder, so the reachable action must be unable to create a worktree
+  the user was never asked about.
+
+`clientRequestId` is the engine's fork-deduplication key and is minted per
+request by the route, so a duplicate delivery of one POST does not create two
+forks while a user who genuinely duplicates twice gets two sessions.
+
+`assistantMessageId` is the fork POINT and is forwarded only when named; its
+absence is meaningful ("duplicate everything"), so the key is omitted rather
+than sent as `undefined`.
+
+**Request** `{ "assistantMessageId": "msg_…" }` — both body keys optional.
+
+**Response 200**
+```json
+{ "ok": true, "id": "mvs_new…", "sourceId": "mvs_…", "forkOriginMessageId": "msg_…" }
+```
+
+A resolved call that reported **no** session answers **502**
+`engine_fork_no_session` rather than a success with a null id — a success
+with no id would leave the user watching a list grow by one row with no way
+to name it.
+
+**Errors** — 400 missing id; 501 / 503 as above; 502 (`engine_fork_failed`,
+`engine_fork_no_session`).
+
+#### What this group deliberately does not have
+
+- **`复制到新工作树`** stays an honest placeholder with no route. The engine
+  method exists (`createIsolatedWorktree`) and `fork-options` already reports
+  `worktreeVisible` / `worktreeEligible` / `worktreeUnavailableReason`; what
+  is missing is a **reference** — no desktop screenshot of that menu's UI
+  exists. Inventing the dialog's shape, whether a branch is chosen, and what
+  happens to the source session are all unknown.
+- **Project-level `归档对话`** stays an honest placeholder with no route. The
+  engine archives ONE session per call and declares nothing project-wide, so
+  the item would have to fan out N single-session writes. Whether a partial
+  failure counts as success, and whether the user authorizes once or N times,
+  are product decisions no existing contract answers.
+
 ### `GET /api/acp-sessions`
 
 Raw mcode session list (from sqlite). No webui merge.
@@ -486,9 +657,42 @@ Get the title of an mcode session.
 
 Sidebar tree: workspaces with their sessions nested. Cached for
 15 s (`CACHE_TTL_MS` in `server/routes/sessions.js`). Mutations
-(`POST /api/sessions`, `/api/sessions/rename`, `DELETE /api/sessions/:id`)
-bust the cache automatically; clients that race the bust can pass
-`?refresh=1` to force a reread.
+(`POST /api/sessions`, `/api/sessions/rename`, `DELETE /api/sessions/:id`,
+and the context actions `/api/sessions/:id/archive`,
+`/api/sessions/:id/pin`, `/api/sessions/:id/fork`) bust the cache
+automatically; clients that race the bust can pass `?refresh=1` to force a
+reread.
+
+**The pin overlay.** Every session carries a `pinned` boolean and the
+payload carries a `pins` object saying how that boolean was resolved. The
+tree itself is read from the runtime db (`lib/session-tree.js`), and
+`local_runtime_sessions` has no pin column — the pin state lives in the
+preference store the engine's `PinService` owns. So the tree is read first
+and the pins are laid over it: pinned sessions move to the top of their
+directory **in the engine's own pin order**, and unpinned sessions keep the
+tree's `updatedAt` order among themselves. An empty pin set therefore leaves
+the payload's ordering byte-identical, which is what stops an unpinned
+sidebar from shuffling on every read.
+
+`pinned` is written on **every** session, `false` included, so a client
+reads a boolean and never has to know the id set exists. `pins.degraded` is
+what distinguishes "nothing is pinned" from "the engine could not be asked":
+when `degraded` is `true` every `pinned` is `false` because the answer is
+**unknown**, and the sidebar renders the tree it already has. That read
+degrades by design — failing the page's primary data source over a pin
+service that would not answer would be a worse failure than not showing
+pins. The four context-action endpoints do **not** degrade; a mutation that
+cannot confirm its write never claims success.
+
+**The pin read never boots a runtime.** It reaches the host through
+`peekEngineCatalogueHost()`, which returns the host only if one is already
+up. The ordinary `getEngineCatalogueHost()` is a *booting* getter — its
+first call constructs the whole runtime, which costs seconds — and a read
+that used it would turn the first tree request of a fresh process into a
+boot, charging the cost to whoever painted the page first while looking
+like an ordinary slow request. The rule: **a write may boot what it needs; a
+read may only use what is already there.** The four endpoints above are
+writes and do boot; the overlay does not.
 
 **Response 200**
 ```json
diff --git a/packages/webui/docs/API.zh-CN.md b/packages/webui/docs/API.zh-CN.md
index c47a1862..1a518588 100644
--- a/packages/webui/docs/API.zh-CN.md
+++ b/packages/webui/docs/API.zh-CN.md
@@ -440,6 +440,158 @@ mcode 会话 id，或尚无 webui 壳记录的裸 `mvs_…`（会自动建壳承
 **响应 404** `{"ok": false, "error": "session not found"}` —— id
 既不匹配任何 webui 会话，也不匹配 `mvs_*` 模式。
 
+### 会话右键操作族
+
+会话行右键菜单（归档 / 置顶 / 复制为新会话）背后的四个端点。之所以归为
+一节，是因为它们共用一个门面
+（`server/engine/session-context-actions.js`）与一套错误词汇表。
+
+| 端点 | 请求体 / 查询 | 作用 |
+|---|---|---|
+| `POST /api/sessions/:id/archive` | `{ "archived": boolean }` | 归档或取消归档**单个**会话。 |
+| `POST /api/sessions/:id/pin` | `{ "pinned": boolean }` | 置顶或取消置顶单个会话。 |
+| `GET /api/sessions/:id/fork-options` | `?assistantMessageId=` | 在真正复制之前，先描述这次复制会得到什么。 |
+| `POST /api/sessions/:id/fork` | `{ "assistantMessageId"? }` | 在同一工作区把对话复制为新会话。 |
+
+#### `POST /api/sessions/:id/archive`
+
+为单个会话设置引擎的 `archived` 标志。一个方法覆盖两个方向
+（`lifecycle-application.ts#archiveSession` 读的是
+`req.archived !== false`），因此 `archived` 是**选择**方向，而不是把动作
+拆成两个端点。设置页的「已归档任务」恢复一行时，调用的是同一个端点，
+只是传 `archived: false`。
+
+`archived` 默认 `true` 且**不做类型校验**，这是刻意的：引擎自己的规则是
+「凡不是字面量 `false` 一律归档」，一个与它不一致的校验器会让 HTTP 层与
+引擎对同一个请求给出不同答案。
+
+侧边栏读取 `WHERE archived = 0`，所以归档后会话在下次读取时离开列表，
+取消归档则回到列表。响应还会失效树缓存，因此该变化立即可见，而不必等
+15 秒的 TTL。
+
+与 `DELETE /api/sessions/:id` 不同，它**不经过** `authorize()` 弹窗：归档
+是**可逆的** —— 对话在引擎侧完整保留，同一个调用即可恢复。一个可逆动作
+上的确认弹窗，是一个用户会学会直接关掉的弹窗。
+
+**请求** `{ "archived": true }` —— `archived` 可选，默认 `true`。
+
+**响应 200** `{ "ok": true, "id": "mvs_…", "archived": true }`
+
+**错误** —— 400 缺 id；501 该 provider 无法归档
+（`engine_capability_not_supported`）；502 已请求引擎但失败
+（`engine_archive_failed`）；503 未启动运行时
+（`engine_host_unavailable`）。
+
+#### `POST /api/sessions/:id/pin`
+
+通过引擎的 `PinService` 置顶或取消置顶单个会话，并返回引擎自己的完整
+置顶集合（按引擎的顺序），使客户端无需二次读树即可重渲染。
+
+`pinned` 是**必填**且不给默认值。引擎的
+`pinSession(sessionId, pinned, insertIndex?)` 以位置参数接收该标志并据其
+分支，所以 `{}` 不是一个可以给默认值的请求：给默认值会把行移到用户并未
+选择的方向上。这与 `archive` 的不对称来自引擎，而非本路由。
+
+本端点是本族中**唯一**经 PB-8 host-services 窗口读取（而非
+`host.cliService`）的成员，因此也只有它的缺失情形是三种互不相同的：
+
+| 状态 | `code` | 状态码 | 含义 |
+|---|---|---|---|
+| 未启动运行时 | `engine_host_unavailable` | 503 | 进程没有跑它的运行时。 |
+| host 无 owner graph | `engine_services_unavailable` | 501 | 该传输不携带 V2 `services`。 |
+| owner graph 中无 `pinService` | `engine_member_unavailable` | 501 | 本端点所需的成员未装配。 |
+
+三者都不产生成功负载。一次什么也没写却「成功」的置顶，正是本仓拒绝的
+假成功形态。
+
+**请求** `{ "pinned": true }`
+
+**响应 200**
+```json
+{ "ok": true, "id": "mvs_…", "pinned": true, "pinnedIds": ["mvs_a", "mvs_b"] }
+```
+
+**错误** —— 400 缺 id 或 `pinned` 非布尔；501 / 503 见上表；502 已请求
+引擎但失败（`engine_pin_failed`）。
+
+#### `GET /api/sessions/:id/fork-options`
+
+在用户真正动手之前回答「复制这个会话会得到什么」。复制弹窗就是这次读取
+的渲染结果：由引擎自己的 `canFork` 决定确认按钮是否可用，并展示它的
+`suggestedTitle`，让用户看到复制后会用的标题。
+
+`?assistantMessageId=` 把预览收窄到某个分叉点。省略时，预览描述的是复制
+整个对话 —— 用户未指定消息时，这正是菜单项的含义。
+
+每个字段在任何回答下都存在，因此形状不完整的引擎响应会渲染出一空行，
+而不是 `undefined`。`worktree` 三元组**原样透传且无人读取**：该菜单的
+工作树变体没有可对照的桌面参照，故保持诚实占位，这三个字段为将来解锁它
+的那一批预留着。
+
+**响应 200**
+```json
+{
+  "ok": true,
+  "id": "mvs_…",
+  "canFork": true,
+  "unavailableReason": null,
+  "suggestedTitle": "「重构解析器」的副本",
+  "nextForkOrdinal": 2,
+  "sourceTitle": "重构解析器",
+  "worktree": { "visible": true, "eligible": false, "unavailableReason": "not a git repository" }
+}
+```
+
+读取失败是**向上传播**的，而不是变成 `canFork: false`。一个默认形状的
+options 对象会把「canFork: false」摆到屏幕上，仿佛引擎拒绝了一次它根本
+没被问到的复制；客户端必须能区分「引擎说不」与「我们没问成」。
+
+**错误** —— 400 缺 id；501 / 503 见上；502（`engine_fork_options_failed`）。
+
+#### `POST /api/sessions/:id/fork`
+
+在同一工作区把对话复制为新会话。
+
+有两个字段由**服务端强制**，调用方无法设置：
+
+- `useSuggestedTitle: true` —— 复制出的会话标题取自引擎自己的建议值。
+  弹窗**展示**该建议值，所以用户看到的正是将会被使用的标题。调用方传入的
+  `title` 会被丢弃：本端点只有一套标题契约。
+- `createIsolatedWorktree: false` —— 该菜单的工作树变体是占位，因此这个
+  可达动作必须无法创建一个用户从未被问过的工作树。
+
+`clientRequestId` 是引擎的分叉去重键，由路由按请求生成，因此同一次 POST
+的重复投递不会产生两个副本，而用户真的复制两次会得到两个会话。
+
+`assistantMessageId` 是分叉点，仅在被指定时透传；它的缺失本身有意义
+（「整体复制」），所以该键是被省略而非以 `undefined` 发送。
+
+**请求** `{ "assistantMessageId": "msg_…" }` —— 两个 body 键均可选。
+
+**响应 200**
+```json
+{ "ok": true, "id": "mvs_new…", "sourceId": "mvs_…", "forkOriginMessageId": "msg_…" }
+```
+
+已兑现但**没有**返回会话的调用回答 **502** `engine_fork_no_session`，
+而不是一个 id 为 null 的成功 —— 那种成功只会让用户看着列表多出一行，
+却无从知道是哪一行。
+
+**错误** —— 400 缺 id；501 / 503 见上；502（`engine_fork_failed`、
+`engine_fork_no_session`）。
+
+#### 本组刻意不提供的两项
+
+- **「复制到新工作树」** 保持诚实占位，**没有**对应端点。引擎侧方法是存在
+  的（`createIsolatedWorktree`），`fork-options` 也已返回
+  `worktreeVisible` / `worktreeEligible` / `worktreeUnavailableReason`；
+  缺的是**参照** —— 该菜单的界面没有任何桌面截图。弹窗形态、是否选分支、
+  源会话会如何，全都不知道。
+- **项目级「归档对话」** 保持诚实占位，**没有**对应端点。引擎一次只归档
+  一个会话，未声明任何项目级方法，因此该项需要对 N 个单会话写做扇出。
+  「部分失败算不算成功」与「用户授权一次还是 N 次」是没有任何现成契约
+  能回答的产品决策。
+
 ### `GET /api/acp-sessions`
 
 原始 mcode 会话列表（来自 sqlite）。不与 webui 合并。
@@ -457,9 +609,36 @@ mcode 会话 id，或尚无 webui 壳记录的裸 `mvs_…`（会自动建壳承
 侧边栏树：工作区及其下嵌套的会话。缓存 15 秒
 （`server/routes/sessions.js` 中的 `CACHE_TTL_MS`）。写操作
 （`POST /api/sessions`、`/api/sessions/rename`、
-`DELETE /api/sessions/:id`）会自动失效缓存；与失效抢跑的
+`DELETE /api/sessions/:id`，以及右键操作族的
+`/api/sessions/:id/archive`、`/api/sessions/:id/pin`、
+`/api/sessions/:id/fork`）会自动失效缓存；与失效抢跑的
 客户端可传 `?refresh=1` 强制重读。
 
+**置顶叠加层。** 每个会话都带一个 `pinned` 布尔值，负载里还有一个
+`pins` 对象说明这个布尔值是怎么得出的。树本身读自 runtime db
+（`lib/session-tree.js`），而 `local_runtime_sessions` 没有置顶列 ——
+置顶状态存放在引擎 `PinService` 所拥有的偏好存储里。因此先读树，再把
+置顶信息叠加上去：被置顶的会话按**引擎自己的置顶顺序**移到所在目录的
+顶部，未置顶的会话之间保持树的 `updatedAt` 顺序。所以置顶集合为空时，
+负载的顺序与之前逐字节相同 —— 这正是不置顶的侧边栏不会在每次读取时
+重新洗牌的原因。
+
+`pinned` 写在**每一个**会话上，`false` 也写，因此客户端读的是一个布尔
+值，永远不需要知道 id 集合的存在。`pins.degraded` 用来区分「没有会话被
+置顶」与「没能问到引擎」：当 `degraded` 为 `true` 时，每个 `pinned` 都是
+`false`，因为答案是**未知**的，而侧边栏就渲染它已有的那棵树。这条读取
+是刻意降级的 —— 为了一个不肯回答的置顶服务而让页面主数据源整体失败，
+比不显示置顶更糟。而上面那四个右键端点**不**降级：一次无法确认写入的
+变更绝不会声称成功。
+
+**置顶读取从不启动运行时。** 它经由 `peekEngineCatalogueHost()` 取 host，
+而该函数只在已有 host 时才返回。常规的 `getEngineCatalogueHost()` 是
+**会启动**的取值器 —— 首次调用会构造整个运行时，代价以秒计 —— 若读取
+走它，进程内第一次树请求就会变成一次运行时启动，把这笔开销记在恰好
+先渲染页面的那个人头上，而且看起来只是一次普通的慢请求。规则是：
+**写可以启动它需要的东西；读只能用已经存在的东西。** 上面四个端点是写，
+会启动；叠加层不会。
+
 **响应 200**
 ```json
 {
diff --git a/packages/webui/docs/ARCHITECTURE.md b/packages/webui/docs/ARCHITECTURE.md
index 07bd4a0f..bf4517f1 100644
--- a/packages/webui/docs/ARCHITECTURE.md
+++ b/packages/webui/docs/ARCHITECTURE.md
@@ -699,12 +699,13 @@ graph LR
     EXEC["mcode exec<br/>(one-shot subprocess)"]
     ARGS["argv<br/>applyExecCliContract<br/>packages/tui/src/cli/contract.ts"]
     WIRE["stream-json<br/>ExecEvent union<br/>packages/tui/src/headless/events.ts"]
-    PARSE["collectExecResult<br/>mcode-exec.js:221-294"]
+    PARSE["collectExecResult<br/>switch on the ExecEvent types<br/>mcode-exec.js"]
 
     EXEC -->|stdin: the prompt| ARGS
     EXEC -->|stdout| WIRE
-    WIRE -.->|"delta / message /<br/>exec.result — NOT wire names"| PARSE
-    PARSE --> GAP["KNOWN DEBT:<br/>the two name families<br/>do not intersect"]
+    WIRE -->|"item.* / turn.* / exec.completed"| PARSE
+    PARSE --> CHAT["cs.chat stream lines<br/>▲ reasoning · ● answer"]
+    PARSE --> SID["r.sessionId → cs.mcodeSessionId<br/>r.usage → context counters"]
 
     EXEC --> DECL["EXEC_CAPABILITIES<br/>full: streamingSend<br/>partial: 4 keys<br/>none: 8 keys"]
 ```
@@ -718,6 +719,22 @@ the CLI options the process is *told*, and the event types it *says
 back*. `EXEC_INTERFACE` records both, and the declaration is audited
 against them.
 
+| Wire type | Consumed as |
+| --- | --- |
+| `ExecEventBase.sessionId` (on every line) | the engine session this run entered, written back to `cs.mcodeSessionId` so the next turn can `--session` back into it |
+| `item.started` / `item.updated` | `item.contentDelta` appended to `r.answer` / `r.thinking` and streamed as a `●` / `▲` chat line |
+| `item.completed` | `item.content`, adopted only for an item that never streamed a delta |
+| `turn.completed` | `usage` and `durationMs` |
+| `turn.failed` | `status` and `error` |
+| `exec.completed` | the terminal `ExecResult` (status, error, duration, final `output`) and the call to `finalize()` |
+| `exec.started`, `session.started`, `session.resumed`, `turn.started` | nothing beyond the base fields — `EXEC_INTERFACE.baseOnlyEvents` |
+
+A `tool_call` item is consumed but not rendered: it carries a `toolCall`
+payload rather than text, so the tool surface is produced on this
+transport and stays invisible. That is what
+`EXEC_CAPABILITIES.toolSkillInvocation` records, and it is the reason
+the key stays `partial` rather than `full`.
+
 **`streamingSend` is the only `full`.** Sending a prompt is what the
 transport is. Everything else is a reduction, and the reductions are
 structural rather than unfinished work:
@@ -730,18 +747,26 @@ structural rather than unfinished work:
 | `usageStats` | `partial` | `partial` — and **stronger** | `turn.completed.usage` is emitted on the exec wire, so this transport has something under its three missing names and acp does not |
 | `sessionCrud` | `partial` | `partial` — weaker | `--session` / `--continue` re-enter an existing session; nothing lists, creates, loads, closes or deletes one |
 
-**A fact the audit found, recorded rather than hidden.** The names
-`collectExecResult` branches on — `delta`, `message`, `exec.result` —
-are the *supervisor's internal* stream-event names. The `stream-json`
-format writes only what `ExecEventProjector` produces (`packages/tui/src/headless/output.ts:34-36`
-refuses the format outright with no projector, and `packages/tui/src/headless/runner.ts:218-232`
-always supplies one), so the wire carries the ten `ExecEvent` types and
-**the two families do not intersect**. That is a real mismatch in the
-exec data plane, and M4-2 does not fix it: the batch registers a
-declaration and changes no routing. It is pinned in
-`EXEC_INTERFACE.consumedEvents`, asserted by a test that fails if the
-intersection ever becomes non-empty in either direction, and recorded as
-KNOWN DEBT.
+**A mismatch the audit found, and what was done about it.** Until D1,
+`collectExecResult` branched on `delta`, `message` and `exec.result` —
+the *supervisor's internal* stream-event names. The `stream-json`
+format writes only what `ExecEventProjector` produces
+(`packages/tui/src/headless/output.ts:34-36` refuses the format outright
+with no projector, `packages/tui/src/headless/runner.ts:218-232` always
+supplies one, and the encoder's `result()` leg goes through
+`projector.complete()` rather than writing the `ExecResult` itself —
+`packages/tui/src/headless/output.ts:47-53`), so the wire carries the ten `ExecEvent` types and
+**the two families did not intersect**. The consequence was not a
+missing feature but a dead data plane: no streaming delta, no session id,
+no usage and no terminal status, so every turn on this transport ended
+with `status: "unknown"` and an empty answer whatever the agent had
+actually said. D1 rewrote the consumer against the wire.
+`EXEC_INTERFACE.consumedEvents` now names the six payload-bearing types
+the parser dispatches on, and
+`test/lib/engine/capability-snapshot.test.js` asserts that this list and
+the parser's `switch` arms are the same set, that every name in it is a
+name the wire can emit, and that the complement is exactly
+`baseOnlyEvents` — the M4-2 pin, inverted.
 
 **The reverse exception is the two routes' property, not acp's.** `exec`
 declares `turnDiff` and `plugins` `none` with the same
diff --git a/packages/webui/docs/ARCHITECTURE.zh-CN.md b/packages/webui/docs/ARCHITECTURE.zh-CN.md
index 54c3748a..f898ce00 100644
--- a/packages/webui/docs/ARCHITECTURE.zh-CN.md
+++ b/packages/webui/docs/ARCHITECTURE.zh-CN.md
@@ -631,12 +631,13 @@ graph LR
     EXEC["mcode exec<br/>（一次性子进程）"]
     ARGS["argv<br/>applyExecCliContract<br/>packages/tui/src/cli/contract.ts"]
     WIRE["stream-json<br/>ExecEvent 联合<br/>packages/tui/src/headless/events.ts"]
-    PARSE["collectExecResult<br/>mcode-exec.js:221-294"]
+    PARSE["collectExecResult<br/>对 ExecEvent 类型做 switch<br/>mcode-exec.js"]
 
     EXEC -->|stdin：prompt| ARGS
     EXEC -->|stdout| WIRE
-    WIRE -.->|"delta / message /<br/>exec.result——非线路名"| PARSE
-    PARSE --> GAP["KNOWN DEBT：<br/>两个名字族<br/>不相交"]
+    WIRE -->|"item.* / turn.* / exec.completed"| PARSE
+    PARSE --> CHAT["cs.chat 流式行<br/>▲ 思考 · ● 回答"]
+    PARSE --> SID["r.sessionId → cs.mcodeSessionId<br/>r.usage → 上下文计数"]
 
     EXEC --> DECL["EXEC_CAPABILITIES<br/>full：streamingSend<br/>partial：4 键<br/>none：8 键"]
 ```
@@ -647,6 +648,21 @@ graph LR
 不成立。实际存在的是两个轴：进程被**告知**什么（CLI 选项），以及进程
 **回报**什么（事件类型）。`EXEC_INTERFACE` 记录两者，声明就对着它们审计。
 
+| 线路类型 | 消费为 |
+| --- | --- |
+| `ExecEventBase.sessionId`（每一行都带） | 本次运行进入的引擎会话，写回 `cs.mcodeSessionId`，使下一轮能用 `--session` 续接 |
+| `item.started` / `item.updated` | `item.contentDelta` 追加进 `r.answer` / `r.thinking`，并以 `●` / `▲` 流式行呈现 |
+| `item.completed` | `item.content`，仅对从未流出增量的 item 采纳 |
+| `turn.completed` | `usage` 与 `durationMs` |
+| `turn.failed` | `status` 与 `error` |
+| `exec.completed` | 终态 `ExecResult`（status、error、duration、最终 `output`）以及 `finalize()` 的调用 |
+| `exec.started`、`session.started`、`session.resumed`、`turn.started` | 除基类字段外无内容——即 `EXEC_INTERFACE.baseOnlyEvents` |
+
+`tool_call` item 会被消费但不会被渲染：它携带的是 `toolCall` 负载而非文本，
+所以工具面在这条传输上被生产出来、却始终不可见。这正是
+`EXEC_CAPABILITIES.toolSkillInvocation` 记录的事实，也是该键停在 `partial`
+而非 `full` 的原因。
+
 **`streamingSend` 是唯一的 `full`。** 发送 prompt 就是这条传输本身。其余全是
 削减，且这些削减是结构性的，不是没写完的活：
 
@@ -658,14 +674,19 @@ graph LR
 | `usageStats` | `partial` | `partial`——且**更强** | `turn.completed.usage` 会出现在 exec 线路上，所以这条传输在三个缺失名之下真有东西，acp 没有 |
 | `sessionCrud` | `partial` | `partial`——更弱 | `--session` / `--continue` 能重新进入已有会话；但没有列举、创建、加载、关闭或删除 |
 
-**审计查出的一条事实，选择记录而非隐藏。** `collectExecResult` 匹配的三个名字
-——`delta`、`message`、`exec.result`——是**supervisor 内部**的流事件名。
+**审计查出的一处错配，以及最终的处理。** 在 D1 之前，`collectExecResult` 匹配的
+三个名字——`delta`、`message`、`exec.result`——是**supervisor 内部**的流事件名。
 `stream-json` 格式只写 `ExecEventProjector` 产出的东西（`packages/tui/src/headless/output.ts:34-36`
-在没有 projector 时直接拒绝该格式，而 `packages/tui/src/headless/runner.ts:218-232` 总会提供一个），
-因此线路上跑的是那十个 `ExecEvent` 类型，而**两个名字族并不相交**。这是
-exec 数据面上的真实错配，而 M4-2 不修它：本批只注册声明、不改路由。它被钉在
-`EXEC_INTERFACE.consumedEvents`，由一条「相交集一旦在任一方向变为非空就转红」
-的测试守住，并记为 KNOWN DEBT。
+在没有 projector 时直接拒绝该格式，`packages/tui/src/headless/runner.ts:218-232` 总会提供一个，
+而编码器的 `result()` 那条腿走的是 `projector.complete()` 而非直接写出 `ExecResult`
+本身——`packages/tui/src/headless/output.ts:47-53`），因此线路上跑的是那十个 `ExecEvent` 类型，而
+**两个名字族并不相交**。后果不是缺一个功能，而是一整条死掉的数据面：没有流式
+增量、没有会话 id、没有用量、没有终态，于是这条传输上的每一轮都以
+`status: "unknown"` 和空回答收场，无论 agent 实际说了什么。D1 把消费面改回
+线路本身。`EXEC_INTERFACE.consumedEvents` 现在列出解析器 dispatch 的六个带负载
+的类型，`test/lib/engine/capability-snapshot.test.js` 断言该清单与解析器的
+`switch` 分支是同一集合、其中每个名字都是线路真能发出的名字、且补集恰好是
+`baseOnlyEvents`——也就是把 M4-2 那颗钉子反过来钉。
 
 **反向例外属于那两个路由，不属于 acp。** `exec` 同样把 `turnDiff` 与
 `plugins` 声明为 `none` 并带上同样的 `servedBy: "local-runtime-v2"`，而这是
diff --git a/packages/webui/docs/CAPABILITIES.md b/packages/webui/docs/CAPABILITIES.md
index 8f34fdf0..5e73380d 100644
--- a/packages/webui/docs/CAPABILITIES.md
+++ b/packages/webui/docs/CAPABILITIES.md
@@ -141,6 +141,11 @@ single index that satisfies the check.
 | Cleanup orphaned mcode sessions | ✅ | `/api/sessions/cleanup-orphans` lists mcode sessions not referenced by any webui session, then deletes them (scope: `orphans` or `all`) |
 | Resume an mcode session opened in the TUI | ❌ | the acp session has a single owner; the webui shows a read-only banner when it detects a foreign owner |
 | Cross-workspace session search | ✅ | the sidebar search input calls `GET /api/sessions/search` which aggregates matches across every workspace with a title (case-insensitive fuzzy match + per-workspace dedup). B03-gated. |
+| Pin / unpin a session | ✅ | `POST /api/sessions/:id/pin` → the engine's `PinService#pinSession`. `pinned` is required — the engine takes it positionally and branches on it, so a defaulted flag would move the row in a direction the user did not pick. The sidebar's pin state is an OVERLAY on `GET /api/session-tree`: `local_runtime_sessions` has no pin column, so the engine's own order is laid over the tree read. Unlike the three writes, that read degrades — an engine that cannot answer leaves the tree as it was and says so in `pins.degraded`. |
+| Archive / unarchive a session | ✅ | `POST /api/sessions/:id/archive` → `archiveSession({id, archived})`, which covers both directions in one method. `archived` defaults to `true` and is deliberately NOT type-checked, so that the route and the engine can never disagree about the same body (the engine's own rule is `req.archived !== false`). Reversible, so unlike delete it carries no `authorize()` modal. The tree's `WHERE archived = 0` is what makes an archived row leave the sidebar. |
+| Duplicate a session as a new session | ✅ | `GET /api/sessions/:id/fork-options` previews it — the dialog IS that read, rendered, and the engine's own `canFork` decides whether the confirm button is live — and `POST /api/sessions/:id/fork` performs it. `useSuggestedTitle` and `createIsolatedWorktree` are forced server-side; the worktree flag is forced **off** because the worktree variant of the menu is still a placeholder. |
+| Duplicate to a new worktree | ❌ | the ENGINE side is present and unused: `ForkSessionInput.createIsolatedWorktree` exists, and `fork-options` already returns `worktreeVisible` / `worktreeEligible` / `worktreeUnavailableReason` — all three carried through untouched so the batch that unblocks it needs no second round trip. What is missing is a REFERENCE: no desktop screenshot of this menu's UI exists, so the dialog's shape, whether a branch is chosen, and what happens to the source session are unknown. It stays an honest placeholder rather than a self-authored form. |
+| Archive every conversation under a project | ❌ | the project context menu's 归档对话. v2 declares `archiveSession({id, archived})` for ONE session and nothing project-scoped, so the item would have to fan out N single-session writes. Whether a partial failure counts as success, and whether the user authorizes once or N times, are product decisions no existing contract answers. |
 | Export a session to Markdown / JSON | ✅ | `GET /api/sessions/:id/export?format=md|json[&download=true]` (v2.0.0, lease C06) reads `$WEBUI_DATA_DIR/sessions.json` (primary) + `runtime-state.sqlite` (best-effort secondary). B03 authorize-gated. `server/routes/export.js` + `test/routes/export.check.mjs`. |
 
 ## 8. Token usage & quota
diff --git a/packages/webui/docs/CAPABILITIES.zh-CN.md b/packages/webui/docs/CAPABILITIES.zh-CN.md
index 4233eb63..f31775ed 100644
--- a/packages/webui/docs/CAPABILITIES.zh-CN.md
+++ b/packages/webui/docs/CAPABILITIES.zh-CN.md
@@ -138,6 +138,11 @@ CI 会对上述每一个名称是否出现在本文档中进行断言
 | 清理孤立的 mcode 会话 | ✅ | `/api/sessions/cleanup-orphans` 列出未被任何 webui 会话引用的 mcode 会话，然后删除它们（范围：`orphans` 或 `all`） |
 | 恢复在 TUI 中打开的 mcode 会话 | ❌ | acp 会话只有一个所有者；webui 在检测到外部所有者时显示只读横幅 |
 | 跨工作区会话搜索 | ✅ | 侧边栏搜索输入调用 `GET /api/sessions/search`，它跨所有工作区聚合有标题的匹配项（不区分大小写的模糊匹配 + 按工作区去重）。由 B03 门禁控制。 |
+| 置顶 / 取消置顶会话 | ✅ | `POST /api/sessions/:id/pin` → 引擎的 `PinService#pinSession`。`pinned` 为必填 —— 引擎以位置参数接收它并据其分支，给默认值会把行移到用户并未选择的方向上。侧边栏的置顶状态是对 `GET /api/session-tree` 的**叠加层**：`local_runtime_sessions` 没有置顶列，因此引擎自己的顺序被叠加到树读取之上。与那三个写操作不同，这条读取是降级的 —— 答不上来的引擎会让树保持原样，并在 `pins.degraded` 中说明。 |
+| 归档 / 取消归档会话 | ✅ | `POST /api/sessions/:id/archive` → `archiveSession({id, archived})`，一个方法同时覆盖两个方向。`archived` 默认 `true` 且刻意**不做**类型校验，好让路由与引擎对同一个请求体永远不会给出不同答案（引擎自己的规则是 `req.archived !== false`）。该动作可逆，因此与删除不同，不带 `authorize()` 弹窗。归档后会话离开侧边栏，靠的是树的 `WHERE archived = 0`。 |
+| 复制会话为新会话 | ✅ | `GET /api/sessions/:id/fork-options` 负责预览 —— 弹窗**就是**这次读取的渲染结果，确认按钮是否可用由引擎自己的 `canFork` 决定 —— `POST /api/sessions/:id/fork` 负责执行。`useSuggestedTitle` 与 `createIsolatedWorktree` 由服务端强制；工作树标志被强制**关闭**，因为该菜单的工作树变体仍是占位。 |
+| 复制到新工作树 | ❌ | 引擎侧是现成且未被使用的：`ForkSessionInput.createIsolatedWorktree` 存在，`fork-options` 也已返回 `worktreeVisible` / `worktreeEligible` / `worktreeUnavailableReason` —— 三者原样透传，因此将来解锁它的那一批无需二次往返。缺的是**参照**：该菜单的界面没有任何桌面截图，所以弹窗形态、是否选分支、源会话会如何，全都不知道。它保持诚实占位，而不是自创形态。 |
+| 归档项目下的全部对话 | ❌ | 项目右键菜单的「归档对话」。v2 只为**单个**会话声明了 `archiveSession({id, archived})`，没有任何项目级方法，因此该项需要对 N 个单会话写做扇出。「部分失败算不算成功」与「用户授权一次还是 N 次」是没有任何现成契约能回答的产品决策。 |
 | 将会话导出为 Markdown / JSON | ✅ | `GET /api/sessions/:id/export?format=md|json[&download=true]`（v2.0.0，lease C06）读取 `$WEBUI_DATA_DIR/sessions.json`（主）+ `runtime-state.sqlite`（尽力而为的次选）。由 B03 授权门禁控制。`server/routes/export.js` + `test/routes/export.check.mjs`。 |
 
 ## 8. 令牌用量与配额
diff --git a/packages/webui/server/app.js b/packages/webui/server/app.js
index f701b7ee..2cfe75ed 100644
--- a/packages/webui/server/app.js
+++ b/packages/webui/server/app.js
@@ -100,6 +100,23 @@ export const OWNED_ROUTES = new Set([
   "GET /api/sessions/search",
   "POST /api/sessions/cleanup-orphans",
   "DELETE /api/sessions/:id",
+  // PB-1: the session right-click action family. Three of the four
+  // greyed rows in `session-tree.tsx` became live here — archive,
+  // pin, duplicate-as-new-session — plus the options read that drives
+  // the duplicate dialog. The worktree variant of the menu and the
+  // project-level "archive conversations" item stay honest placeholders
+  // and have no route; see `engine/session-context-actions.js` KNOWN
+  // DEBT 1 and 2 for why each is a decision rather than a window.
+  //
+  // The route ORDER below matters in one direction: `/api/sessions/:id`
+  // is a DELETE-only Hono pattern, and these are POST/GET on longer
+  // paths, so no pattern is shadowed by another. Each handler slices its
+  // own id out of `ctx.pathname` and 400s when the shape is wrong, which
+  // is the same discipline `handleDeleteSession` uses.
+  "POST /api/sessions/:id/archive",
+  "POST /api/sessions/:id/pin",
+  "GET /api/sessions/:id/fork-options",
+  "POST /api/sessions/:id/fork",
   // Sidebar session tree, served from mcode's runtime db.
   "GET /api/session-tree",
   // ACP session list + title helpers.
@@ -470,6 +487,26 @@ export function createHonoApp() {
     invokeHandler(c, c.get(CAPTURE_KEY), sessionsRoute.handleDeleteSession),
   );
 
+  // ----- PB-1: session right-click actions (archive / pin / fork) -----
+  // Registered AFTER `DELETE /api/sessions/:id` and before the session
+  // tree, in the same order as `OWNED_ROUTES`. `:id` is Hono's parameter
+  // marker; each handler resolves the id from `ctx.pathname` by slicing
+  // the prefix and the trailing verb, and answers 400 when the path does
+  // not have that shape — the same rule `handleDeleteSession` follows, and
+  // it is why `/api/sessions//archive` cannot be read as an empty id.
+  app.post("/api/sessions/:id/archive", (c) =>
+    invokeHandler(c, c.get(CAPTURE_KEY), sessionsRoute.handleArchiveSession),
+  );
+  app.post("/api/sessions/:id/pin", (c) =>
+    invokeHandler(c, c.get(CAPTURE_KEY), sessionsRoute.handlePinSession),
+  );
+  app.get("/api/sessions/:id/fork-options", (c) =>
+    invokeHandler(c, c.get(CAPTURE_KEY), sessionsRoute.handleSessionForkOptions),
+  );
+  app.post("/api/sessions/:id/fork", (c) =>
+    invokeHandler(c, c.get(CAPTURE_KEY), sessionsRoute.handleForkSession),
+  );
+
   // ----- Sidebar session tree (mcode runtime db) -----
   app.get("/api/session-tree", (c) =>
     invokeHandler(c, c.get(CAPTURE_KEY), sessionsRoute.handleSessionTree),
diff --git a/packages/webui/server/engine/host.js b/packages/webui/server/engine/host.js
index 3050d1e4..aa4dc252 100644
--- a/packages/webui/server/engine/host.js
+++ b/packages/webui/server/engine/host.js
@@ -38,3 +38,38 @@ export async function getEngineCatalogueHost() {
   const { getCatalogueHost } = await import("../lib/acp-client.js");
   return getCatalogueHost();
 }
+
+/**
+ * The catalogue host IF one is already up — never booting one.
+ *
+ * Why this exists, and why it is not an optimisation. `getCatalogueHost()`
+ * is a BOOTING getter: on its first call it `await import`s
+ * `runtime-host.js` and constructs the whole runtime, which takes seconds
+ * (the real-host suites in `test/server/` measure ~5 s for a cold boot).
+ * That is correct for a WRITE — the user asked for an action, and M4-3a's
+ * delete has always booted what it needed — and it is wrong for a READ.
+ * A read that can boot a runtime can turn the page's first paint into a
+ * multi-second stall, and it does so silently: the request looks like an
+ * ordinary one.
+ *
+ * PB-1 hit exactly this. `GET /api/session-tree` had to consult the
+ * engine's `PinService` for the pin overlay, and reaching it through
+ * `getEngineCatalogueHost()` meant the FIRST sidebar read of a fresh
+ * process booted a runtime. The symptom was a 10 s `/api/state` timeout
+ * in the router-boot integration suite under the `runtime` transport, not
+ * an assertion about pins at all.
+ *
+ * So the rule this encodes is: **a write may boot what it needs; a read
+ * may only use what is already there.** A caller that gets `null` here is
+ * being told "no host is up yet", and the honest response is to answer
+ * without the engine — never to trigger the boot as a side effect of
+ * asking.
+ *
+ * @returns {Promise<object|null>} The already-booted host, or `null` when
+ *   none is up (including when a boot is IN PROGRESS — a read does not
+ *   wait for someone else's boot to finish either).
+ */
+export async function peekEngineCatalogueHost() {
+  const { peekCatalogueHost } = await import("../lib/acp-client.js");
+  return peekCatalogueHost();
+}
diff --git a/packages/webui/server/engine/providers/exec.capabilities.js b/packages/webui/server/engine/providers/exec.capabilities.js
index ba8ef56f..3f14c5ba 100644
--- a/packages/webui/server/engine/providers/exec.capabilities.js
+++ b/packages/webui/server/engine/providers/exec.capabilities.js
@@ -138,7 +138,8 @@ import { ENGINE_CAPABILITY_KEYS, validateEngineCapabilities } from "../capabilit
  *
  * @typedef {{cliOptions: readonly string[], streamEvents: readonly string[],
  *            itemKinds: readonly string[], processSignals: readonly string[],
- *            consumedEvents: readonly string[]}} ExecInterface
+ *            consumedEvents: readonly string[],
+ *            baseOnlyEvents: readonly string[]}} ExecInterface
  */
 export const EXEC_INTERFACE = Object.freeze({
   // `applyExecCliContract` options, contract.ts:104-152. `--file`,
@@ -188,34 +189,50 @@ export const EXEC_INTERFACE = Object.freeze({
   // are signals webui delivers to its own child, not a method the
   // transport answers.
   processSignals: Object.freeze(["SIGINT", "SIGTERM", "SIGHUP"]),
-  // The stream-json types `collectExecResult` actually branches on
-  // (mcode-exec.js:259, 278, 284) — recorded because they are NOT the
-  // types the transport emits, and that fact is load-bearing rather
-  // than a curiosity.
+  // The stream-json types `collectExecResult` dispatches on. As of D1
+  // these ARE the wire's names: `mcode exec --output-format stream-json`
+  // writes exactly what `ExecEventProjector` produces and nothing else
+  // (`output.ts:34-36` refuses the format outright with no projector,
+  // `runner.ts:218-232` always supplies one, and the encoder's
+  // `result()` leg goes through `projector.complete()` rather than
+  // writing the `ExecResult` — output.ts:47-53). So the intersection with
+  // `streamEvents` is now the full payload surface rather than empty.
   //
-  // `--output-format stream-json` writes exactly what
-  // `ExecEventProjector` produces and nothing else: `output.ts:34-36`
-  // refuses the format outright when no projector is supplied, and
-  // `runner.ts:218-232` always supplies one. So the wire carries
-  // `streamEvents` and nothing else — and `consumedEvents` has an EMPTY
-  // intersection with it. `delta`, `message` and `exec.result` are the
-  // supervisor's INTERNAL stream-event names (packages/tui/src/headless/
-  // supervisor.ts:189 and the family around it), not the projected wire
-  // names.
+  // What it was before D1: `["delta", "message", "exec.result"]`, the
+  // SUPERVISOR's internal `TuiStreamEvent` names, none of which the wire
+  // can emit. The two families have an empty intersection, which is what
+  // made the exec transport's streaming data plane dead: no delta, no
+  // session id, no usage, and no terminal status — every turn ended with
+  // `status: "unknown"` and an empty answer. M4-2 recorded the mismatch
+  // as KNOWN DEBT; D1 fixed the consumer to the wire.
   //
-  // This is recorded rather than papered over for three reasons. It caps
-  // what the declaration may claim: every level below is justified by
-  // the WIRE, and the `consumedEvents` note is what stops a reader from
-  // believing webui currently reads any of it. It explains the
-  // `toolSkillInvocation` reason, which is otherwise puzzling: the
-  // transport produces `tool_call` items and webui has no branch for
-  // them. And it is pinned by a test in capability-snapshot.test.js that
-  // fails if the intersection ever becomes non-empty in either
-  // direction, so the two families cannot drift into each other by
-  // accident. M4-2 does NOT fix it: the mismatch is in the exec DATA
-  // PLANE, and this batch registers a declaration and changes no
-  // routing. See KNOWN DEBT in the M4-2 report.
-  consumedEvents: Object.freeze(["delta", "message", "exec.result"]),
+  // These six are the events that carry a payload `collectExecResult`
+  // acts on. The remaining four — `baseOnlyEvents` below — carry nothing
+  // beyond `ExecEventBase` and land in the parser's `default` arm. The
+  // live cross-check in `test/lib/engine/capability-snapshot.test.js`
+  // asserts that this list and the parser's switch arms are the same set,
+  // that every name here is a name the wire can emit, and that the
+  // complement is exactly `baseOnlyEvents` — so dropping a type here
+  // without dropping it there, or vice versa, goes red.
+  consumedEvents: Object.freeze([
+    "item.started",
+    "item.updated",
+    "item.completed",
+    "turn.completed",
+    "turn.failed",
+    "exec.completed",
+  ]),
+  // The `ExecEvent` union minus `consumedEvents`: the four events whose
+  // only field is `ExecEventBase` (events.ts:10-17). The parser adopts
+  // `ExecEventBase.sessionId` from every line, so `session.started` /
+  // `session.resumed` are not inert — they are just the first lines that
+  // hand it over, and they have nothing else to say.
+  baseOnlyEvents: Object.freeze([
+    "exec.started",
+    "session.started",
+    "session.resumed",
+    "turn.started",
+  ]),
 });
 
 /**
@@ -271,7 +288,7 @@ export const EXEC_CAPABILITIES = Object.freeze({
     level: "partial",
     missing: ["listSkills", "listRuntimeSkills", "listPendingPermissions", "replyPermission", "setMode"],
     reason:
-      "the transport PRODUCES `tool_call` items (packages/tui/src/headless/events.ts:21) and webui does not read them: `collectExecResult` branches on delta/message/exec.result (mcode-exec.js:259-291), none of which is a name the stream-json wire can emit — see EXEC_INTERFACE.consumedEvents for the full account. So on this transport the tool surface exists and is invisible, which is a different fact from acp's, where the events are produced AND parsed. There is no permission request/reply pair either: `--permission` is fixed at spawn time and the CLI says so itself — 'permission policy: smart, full, or off (ask requires TUI/ACP)' (contract.ts:130) — and no skill enumeration method exists",
+      "the transport PRODUCES `tool_call` items (packages/tui/src/headless/events.ts:21) and webui does not RENDER them: `collectExecResult` (mcode-exec.js) consumes the wire's item events since D1, but only maps `reasoning` and `agent_message` to a streaming line — a `tool_call` item carries a `toolCall` payload instead of text and is dropped, so on this transport the tool surface exists and stays invisible, which is a different fact from acp's, where the events are produced AND parsed. There is no permission request/reply pair either: `--permission` is fixed at spawn time and the CLI says so itself — 'permission policy: smart, full, or off (ask requires TUI/ACP)' (contract.ts:130) — and no skill enumeration method exists",
   },
   // none, AND served in process: the same reverse exception acp carries,
   // because the property belongs to the route, not to the transport.
@@ -320,7 +337,7 @@ export const EXEC_CAPABILITIES = Object.freeze({
     level: "partial",
     missing: ["getSessionUsage", "getSessionUsageSummary", "watchSessionUsageCommits"],
     reason:
-      "per-turn token usage crosses the wire — `turn.completed.usage` (events.ts:36) is emitted by ExecEventProjector.complete and folded into the conversation counters by webui (mcode-exec.js:362-376) — so this transport is genuinely STRONGER than acp here, whose declaration has nothing underneath its three missing names. What is still absent is every per-session projection: a one-shot process cannot answer a query about a session it is not currently running. Read the level as a claim about the INTERFACE; whether webui's exec parser currently receives that event is a separate fact, recorded in EXEC_INTERFACE.consumedEvents",
+      "per-turn token usage crosses the wire — `turn.completed.usage` (events.ts:36) is emitted by ExecEventProjector.complete and, since D1, is actually folded into the conversation counters by webui's `collectExecResult`, which dispatches on the wire's event names (mcode-exec.js#consumeItemText/#finalize) — so this transport is genuinely STRONGER than acp here, whose declaration has nothing underneath its three missing names. What is still absent is every per-session projection: a one-shot process cannot answer a query about a session it is not currently running",
   },
   // none, unlike acp's partial, and this is the second place where exec
   // is structurally behind rather than merely unimplemented.
diff --git a/packages/webui/server/engine/session-context-actions.js b/packages/webui/server/engine/session-context-actions.js
new file mode 100644
index 00000000..35e05322
--- /dev/null
+++ b/packages/webui/server/engine/session-context-actions.js
@@ -0,0 +1,982 @@
+// webui/server/engine/session-context-actions.js
+//
+// Placeholder batch PB-1: the four session right-click actions
+// (会话右键菜单四项).
+//
+//   归档   POST /api/sessions/:id/archive         → archiveSession
+//   置顶   POST /api/sessions/:id/pin             → pinService.pinSession
+//   复制   GET  /api/sessions/:id/fork-options    → getSessionForkOptions
+//   复制   POST /api/sessions/:id/fork            → forkSession
+//
+// What this batch unlocks, and what it deliberately does not.
+//
+//   UNLOCKED (3): 归档 / 置顶 / 复制为新会话. Each of the three had a
+//   complete engine method behind it the whole time
+//   (local-runtime-v2/src/local/cli-service.ts `archiveSession` :183,
+//   `getSessionForkOptions` :214, `forkSession` :224, plus
+//   `service/pin/service.ts#pinSession` :61) and no HTTP window.
+//   session-tree.tsx rendered them as permanently greyed rows with the
+//   comment "no … contract yet" — which was true about the ROUTE and
+//   false about the CAPABILITY. That distinction is the whole batch.
+//
+//   STILL GREY (2), and the reason each one is still grey is recorded at
+//   its own `disabled` site rather than left to be re-derived:
+//
+//   - 复制到新工作树 (`fork-worktree`). The engine's fork request HAS the
+//     flag — `ForkSessionInput.createIsolatedWorktree: boolean` — and
+//     `getSessionForkOptions` already reports `worktreeVisible` /
+//     `worktreeEligible` / `worktreeUnavailableReason`. What is missing
+//     is a REFERENCE: no desktop screenshot of this menu exists in
+//     design-ref/, so the shape of the worktree variant (does it prompt?
+//     which branch? what does it do to the source session?) is unknown.
+//     Inventing one would be self-authored UI. See `session-tree.tsx`
+//     and KNOWN DEBT 1.
+//
+//   - 项目右键「归档对话」(`session-tree.tsx:575`). The semantics are
+//     BULK archive of every session under a project. v2 declares
+//     `archiveSession({id, archived})` — a single session — and no
+//     project-level equivalent. A batch endpoint would have to fan out
+//     N single-session writes, which is a product decision (partial
+//     failure semantics, authorization once or N times) and not a
+//     window. See KNOWN DEBT 2.
+//
+// The gate, and why it is not the same gate as the write family's.
+//
+// Three of the four endpoints (`archive`, `fork-options`, `fork`) read
+// and write through `host.cliService`, the surface
+// `local-runtime-v2.capabilities.js` declares `sessionCrud: full` over.
+// Those get a DECLARATION gate, exactly as
+// `engine/session-writes.js` does: `sessionCrud` plus the exact sub-item
+// name, so a provider that drops `archiveSession` goes 501 rather than
+// answering `{ok:true}` and changing nothing.
+//
+// `pin` is the odd one out and the oddness is load-bearing. `pinSession`
+// is NOT on `cliService` — it is on `host.services.pinService`, the V2
+// owner graph that PB-8 opened a window onto. Two consequences:
+//
+//   1. There is no capability key for it. `ENGINE_CAPABILITY_KEYS` is a
+//      fixed 14-key audited matrix
+//      (`server/engine/capabilities.js:44`), and adding a 15th key for
+//      this batch would restate three provider declarations and the
+//      snapshot audit for one method. The honest answer for THIS batch
+//      is the presence gate PB-8's own header prescribes for exactly
+//      this situation: "Consumers that need cron must gate on its
+//      presence rather than assume it."
+//
+//   2. The presence gate is the three-state `getHostServices()` answer,
+//      and all three states are distinct failures with distinct codes:
+//        null      → no runtime booted          → 503 engine_host_unavailable
+//        undefined → a host with no owner graph → 501 engine_services_unavailable
+//        object    → but no `pinService` member → 501 pin_service_unavailable
+//      None of them may fall through to a success payload. A pin that
+//      "succeeded" without writing anything is the fake-success shape
+//      #110 fixed and this repository refuses to reintroduce.
+//
+// Pin and the tree read.
+//
+// A pin that cannot be seen is not a pin. `lib/session-tree.js` sorts
+// the sidebar by `updated_at_ms` and has no column for pin state, so
+// `readEnginePinnedSessionOrder()` below reads the engine's own order
+// and `GET /api/session-tree` overlays it. That read DEGRADES rather
+// than fails: a host that cannot answer leaves the tree exactly as it
+// was, because a sidebar that will not render because the pin service
+// is absent is a worse failure than a sidebar whose pins are not
+// currently shown. That asymmetry is deliberate and is the only soft
+// gate in this file; the four endpoints themselves never degrade.
+//
+// Boot-path discipline, unchanged from `host-services.js`: nothing heavy
+// is imported statically. The engine facade and the tree cache are
+// reached through `await import()` inside the functions.
+
+import { assertEngineCapability } from "./capabilities.js";
+import { DEFAULT_ENGINE_PROVIDER_ID, getEngineProvider } from "./index.js";
+
+// ---------------------------------------------------------------------------
+// The declaration
+// ---------------------------------------------------------------------------
+
+/**
+ * The declaration each endpoint of this family needs.
+ *
+ * `gate` names HOW the row is enforced, and it takes three values
+ * because the family genuinely has three shapes:
+ *
+ *   - `"capability"` — the standard `capability` + `subItem`
+ *     declaration, enforced through `assertEngineCapability`. A provider
+ *     that lacks the sub-item throws `EngineCapabilityNotSupportedError`
+ *     and `app.js#invokeHandler` turns it into 501.
+ *   - `"host-services"` — the PB-8 presence gate. `capability` is
+ *     `null` because no key covers it; the row is enforced by the
+ *     three-state member read below, which throws for `undefined` and
+ *     returns a typed failure for `null`.
+ *   - `"none"` — declared for uniformity so that adding a row is a
+ *     table edit rather than a change to this module's shape. No row
+ *     uses it today; the field exists because a `null` hole in the
+ *     middle of a uniform table is the kind of shape a later edit
+ *     mistakes for "not filled in yet" (`session-writes.js` records the
+ *     same reasoning for its own `capability: null` rename row).
+ *
+ * `member` is the host path the call is made through, so the resolution
+ * helper is data-driven and a fifth row needs no new branch.
+ *
+ * @typedef {{gate: "capability"|"host-services"|"none", capability: string|null, subItem: string|null, member: "cliService"|"services.pinService", method: string}} SessionContextActionDeclaration
+ * @type {Readonly<Record<string, SessionContextActionDeclaration>>}
+ */
+export const SESSION_CONTEXT_ACTION_ENDPOINTS = Object.freeze({
+  "POST /api/sessions/:id/archive": Object.freeze({
+    gate: "capability",
+    capability: "sessionCrud",
+    subItem: "archiveSession",
+    member: "cliService",
+    method: "archiveSession",
+  }),
+  "GET /api/sessions/:id/fork-options": Object.freeze({
+    gate: "capability",
+    capability: "sessionCrud",
+    subItem: "getSessionForkOptions",
+    member: "cliService",
+    method: "getSessionForkOptions",
+  }),
+  "POST /api/sessions/:id/fork": Object.freeze({
+    gate: "capability",
+    capability: "sessionCrud",
+    subItem: "forkSession",
+    member: "cliService",
+    method: "forkSession",
+  }),
+  "POST /api/sessions/:id/pin": Object.freeze({
+    gate: "host-services",
+    capability: null,
+    subItem: null,
+    member: "services.pinService",
+    method: "pinSession",
+  }),
+});
+
+/**
+ * The capability key the `cliService` rows are declared under, for the
+ * degradation summary the frontend reads. A pure re-export of the one
+ * string, so a future key migration is one edit.
+ */
+export const SESSION_CONTEXT_ACTION_CAPABILITY = "sessionCrud";
+
+/** The endpoint keys of this family, in `OWNED_ROUTES` order. */
+export const SESSION_CONTEXT_ACTION_ROUTES = Object.freeze(
+  Object.keys(SESSION_CONTEXT_ACTION_ENDPOINTS),
+);
+
+function providerByTransport() {
+  // Built per call, never frozen at module scope: `engine/index.js`
+  // re-exports this module, so a module-level table would read
+  // `DEFAULT_ENGINE_PROVIDER_ID` while that binding is still in its
+  // temporal dead zone on a cold `import("./engine/index.js")`. Same
+  // reason, same wording as `session-writes.js#providerByTransport`.
+  return Object.freeze({ runtime: DEFAULT_ENGINE_PROVIDER_ID });
+}
+
+/**
+ * Resolve the provider that answers session context actions on
+ * `transport`, or `null` when none is registered yet.
+ *
+ * `null` means "no provider claims this transport", which is NOT the
+ * same answer as "the provider lacks the capability" — the first lets
+ * the call proceed to the in-process host (the M4-3a shape: under
+ * `acp` there is no registered provider, and the work still runs on the
+ * process-local `local-runtime-v2` host reached through
+ * `getEngineCatalogueHost()`), the second must 501. Collapsing the two
+ * would delete a working endpoint on a statement about nothing.
+ *
+ * @param {string} transport
+ * @returns {{id: string, transport: string, capabilities: object}|null}
+ */
+export function resolveSessionContextActionProvider(transport) {
+  const providerId = providerByTransport()[transport];
+  if (!providerId) return null;
+  return getEngineProvider(providerId);
+}
+
+/**
+ * Check one endpoint of this family against the active provider's
+ * declaration. Throws `EngineCapabilityNotSupportedError` (→ 501) when
+ * a `"capability"` row's capability or exact sub-item is absent.
+ *
+ * A `"host-services"` row returns without consulting the provider at
+ * all: its enforcement is the member read, which happens at dispatch
+ * time against the live host and not against a static declaration.
+ *
+ * @param {string} endpoint A key of `SESSION_CONTEXT_ACTION_ENDPOINTS`.
+ * @param {string} transport The active transport.
+ * @returns {{endpoint: string, gate: string, provider: string|null, capability: string|null, subItem: string|null, enforcement: string}}
+ */
+export function assertSessionContextActionCapability(endpoint, transport) {
+  const need = SESSION_CONTEXT_ACTION_ENDPOINTS[endpoint];
+  if (need === undefined) {
+    // Caller confusion, not an engine limitation — a plain Error, so the
+    // HTTP layer never answers 501 for a typo in webui's own code.
+    const err = new Error(
+      `assertSessionContextActionCapability: "${endpoint}" is not part of the session context action family ` +
+        `(known: ${SESSION_CONTEXT_ACTION_ROUTES.join(", ")})`,
+    );
+    err.code = "unknown_session_context_action_endpoint";
+    throw err;
+  }
+  const provider = resolveSessionContextActionProvider(transport);
+  const base = {
+    endpoint,
+    provider: provider ? provider.id : null,
+    capability: need.capability,
+    subItem: need.subItem,
+    enforcement: need.gate,
+  };
+  if (need.gate === "host-services" || need.gate === "none") {
+    return { ...base, gate: need.gate };
+  }
+  if (!provider) {
+    return { ...base, gate: "unregistered-transport" };
+  }
+  assertEngineCapability(provider.capabilities, need.capability, provider.id, need.subItem);
+  return { ...base, gate: "checked" };
+}
+
+// ---------------------------------------------------------------------------
+// Member resolution — the three-state rule, once
+// ---------------------------------------------------------------------------
+
+/**
+ * A resolved engine member, or a typed failure. Exactly one of the two
+ * shapes is returned; there is no third answer in which the member is
+ * absent and the call proceeds.
+ *
+ * @typedef {{ok: true, member: Function, host: object, window: object}} ResolvedContextActionMember
+ * @typedef {{ok: false, code: "engine_host_unavailable"|"engine_services_unavailable"|"engine_member_unavailable", status: 503|501, error: string}} ResolvedContextActionFailure
+ */
+
+/**
+ * Read one member off a booted catalogue host, honouring the three-state
+ * `getHostServices()` contract from PB-8 without collapsing any of its
+ * three answers.
+ *
+ * Why the distinction survives here. `getHostServices()` returns
+ * `null` for "no runtime booted" and `undefined` for "a host that
+ * carries no owner graph"; the two have different HTTP meanings
+ * (503 vs 501) and, more importantly, different OPERATOR meanings: the
+ * first is a boot failure to look at, the second is a transport that
+ * simply has no V2 slice. A caller that mapped both to "unavailable"
+ * would have made the first look like the second.
+ *
+ * The `cliService` member does not go through `getHostServices()` at
+ * all — it is on the host itself — but it is resolved through the same
+ * helper so both halves of the family produce the same failure shape and
+ * the route has exactly one error branch.
+ *
+ * @param {object} options
+ * @param {string} options.endpoint   Endpoint key, for the error text.
+ * @param {string} options.member     `"cliService"` or `"services.pinService"`.
+ * @param {string} options.method     Method name, for the failure text.
+ * @param {object} [options.deps]     Injection seams; see each function.
+ * @returns {Promise<ResolvedContextActionMember|ResolvedContextActionFailure>}
+ */
+async function resolveContextActionMember(options) {
+  const { endpoint, member, method, deps = {} } = options;
+  const getHost = deps.getHost || (await import("./host.js")).getEngineCatalogueHost;
+  let host;
+  try {
+    host = await getHost();
+  } catch (e) {
+    // A throwing host getter propagates through `getEngineCatalogueHost`
+    // unchanged everywhere else in the facade; here it is caught so the
+    // route can answer 503 with a body instead of an unhandled rejection.
+    return {
+      ok: false,
+      code: "engine_host_unavailable",
+      status: 503,
+      error: e && e.message ? e.message : String(e),
+    };
+  }
+  if (!host) {
+    return {
+      ok: false,
+      code: "engine_host_unavailable",
+      status: 503,
+      error: `${endpoint}: the engine catalogue host is not available`,
+    };
+  }
+
+  let window = host;
+  if (member === "cliService") {
+    if (typeof host.cliService?.[method] !== "function") {
+      return {
+        ok: false,
+        code: "engine_member_unavailable",
+        status: 501,
+        error: `${endpoint}: host.cliService.${method} is not a function`,
+      };
+    }
+    return { ok: true, member: host.cliService[method].bind(host.cliService), host, window };
+  }
+
+  // `services.*` — the PB-8 window. Read as-is, never `??`-folded, so
+  // "no owner graph" and "owner graph without this member" stay apart.
+  window = host.services;
+  if (window === null) {
+    return {
+      ok: false,
+      code: "engine_host_unavailable",
+      status: 503,
+      error: `${endpoint}: the engine catalogue host is not available`,
+    };
+  }
+  if (window === undefined) {
+    return {
+      ok: false,
+      code: "engine_services_unavailable",
+      status: 501,
+      error: `${endpoint}: this engine host carries no services owner graph`,
+    };
+  }
+  // The dotted path is rooted at the HOST, not at the window: `member` is
+  // written the way it reads on the host (`services.pinService`), so it is
+  // walked from `host` after the window's own three states have been
+  // checked. Walking it from `window` would look for `window.services` —
+  // a path that does not exist — and answer 501 for a member that is
+  // right there.
+  const resolved = member.split(".").reduce((node, key) => (node == null ? undefined : node[key]), host);
+  if (typeof resolved?.[method] !== "function") {
+    return {
+      ok: false,
+      code: "engine_member_unavailable",
+      status: 501,
+      error: `${endpoint}: host.${member}.${method} is not a function`,
+    };
+  }
+  return { ok: true, member: resolved[method].bind(resolved), host, window };
+}
+
+/**
+ * A typed failure rendered as this module's failure payload. The route
+ * turns it into a status; this module never decides one on its own,
+ * because `status` is the HTTP layer's concern and `code` is the
+ * contract.
+ *
+ * @param {ResolvedContextActionFailure} failure
+ * @returns {{ok: false, code: string, error: string, status: number}}
+ */
+function failurePayload(failure) {
+  return { ok: false, code: failure.code, error: failure.error, status: failure.status };
+}
+
+// ---------------------------------------------------------------------------
+// Pure derivations — exported and tested on their INPUTS
+// ---------------------------------------------------------------------------
+
+/**
+ * Whether an archive request is a well-formed `POST
+ * /api/sessions/:id/archive` body.
+ *
+ * `archived` is BOOLEAN-COERCED rather than type-checked, and the reason
+ * matters: `lifecycle-application.ts#archiveSession` reads
+ * `req.archived !== false`, so anything that is not literally `false`
+ * archives. A validator that demanded `typeof === "boolean"` would
+ * 400 a body the engine would have accepted, and a validator that
+ * passed `undefined` straight through would archive a session whose
+ * caller meant to unarchive. Defaulting to `true` and comparing against
+ * `false` reproduces the engine's own rule exactly, so the two can
+ * never disagree about the same request.
+ *
+ * @param {unknown} body
+ * @returns {{ok: true, archived: boolean}|{ok: false, error: string}}
+ */
+export function parseArchiveRequestBody(body) {
+  const raw = body && typeof body === "object" ? body.archived : undefined;
+  if (raw === undefined) return { ok: true, archived: true };
+  if (raw === null) return { ok: true, archived: true };
+  return { ok: true, archived: raw !== false };
+}
+
+/**
+ * Whether a pin request is a well-formed `POST
+ * /api/sessions/:id/pin` body.
+ *
+ * Unlike archive, `PinService#pinSession(sessionId, pinned, …)` takes
+ * the flag as a required positional and branches on it, so this one IS
+ * type-checked: a body of `{}` means "the caller did not say", and the
+ * menu item is a TOGGLE, so guessing either way would move the row in
+ * the direction the user did not ask for. `parsePinRequestBody` exists
+ * as a named predicate rather than an inline `body.pinned === true`
+ * so the "unpin" direction is a tested case and not an accident.
+ *
+ * @param {unknown} body
+ * @returns {{ok: true, pinned: boolean}|{ok: false, error: string}}
+ */
+export function parsePinRequestBody(body) {
+  const raw = body && typeof body === "object" ? body.pinned : undefined;
+  if (typeof raw !== "boolean") {
+    return { ok: false, error: "pinned must be a boolean" };
+  }
+  return { ok: true, pinned: raw };
+}
+
+/**
+ * The `ForkSessionInput` this endpoint sends, as a PURE function of the
+ * validated request fields.
+ *
+ * Three fields are FORCED rather than forwarded, and each forcing is a
+ * decision this batch made:
+ *
+ *   - `useSuggestedTitle: true` — the fork's title comes from the
+ *     engine's own suggestion (`getSessionForkOptions` returns
+ *     `suggestedTitle` and `nextForkOrdinal`). Letting the client
+ *     override it is a second title contract; the menu item is
+ *     "duplicate", and a duplicate keeps the source's name shape.
+ *     The suggestion is still SHOWN in the preview dialog — the user
+ *     sees exactly the title that will be used.
+ *   - `createIsolatedWorktree: false` — the worktree variant is the
+ *     honest placeholder described in this file's header. The field
+ *     exists on the protocol and is deliberately left `false` here, so
+ *     the "duplicate as new session" action can never accidentally
+ *     create a worktree the UI never asked the user about.
+ *   - `clientRequestId` — the protocol requires it, and it is the
+ *     engine's fork-deduplication key. It is minted per REQUEST, so a
+ *     retried POST of the same user intent creates a second fork while
+ *     a duplicate delivery of one POST does not. The route mints it;
+ *     this function takes it as a parameter so the value is visible at
+ *     the call site rather than buried in a `randomUUID()` here.
+ *
+ * `assistantMessageId` is the fork POINT and is forwarded as given: an
+ * absent value forks the whole conversation, which is what the menu
+ * item means when the user has not picked a message.
+ *
+ * @param {object} fields
+ * @param {string} fields.id                   Source session id.
+ * @param {string} fields.clientRequestId      Per-request fork key.
+ * @param {string} [fields.assistantMessageId] Fork point; absent = whole session.
+ * @returns {{id: string, clientRequestId: string, useSuggestedTitle: true, createIsolatedWorktree: false, assistantMessageId?: string}}
+ */
+export function buildForkRequest(fields) {
+  const request = {
+    id: fields.id,
+    clientRequestId: fields.clientRequestId,
+    useSuggestedTitle: true,
+    createIsolatedWorktree: false,
+  };
+  if (fields.assistantMessageId) request.assistantMessageId = fields.assistantMessageId;
+  return request;
+}
+
+/**
+ * The fork-options projection the preview dialog renders, as a PURE
+ * narrowing of whatever the engine returned.
+ *
+ * The narrowing is total on purpose: every field the dialog reads has a
+ * defined value for every answer, so a partially-shaped engine response
+ * renders an empty option row rather than `undefined` in the DOM. The
+ * worktree triple is carried through VERBATIM and unread — this batch
+ * gates the worktree variant on absence of a reference, not on the
+ * engine's opinion of eligibility, so the fields travel so that PB
+ * worktree can consume them without another round trip.
+ *
+ * @param {object} options The engine's `GetSessionForkOptionsResult`.
+ * @returns {{canFork: boolean, unavailableReason: string|null, suggestedTitle: string|null, nextForkOrdinal: number|null, sourceTitle: string|null, worktree: {visible: boolean, eligible: boolean, unavailableReason: string|null}}}
+ */
+export function projectForkOptions(options) {
+  const src = options && typeof options === "object" ? options : {};
+  return {
+    canFork: src.canFork === true,
+    unavailableReason: typeof src.unavailableReason === "string" ? src.unavailableReason : null,
+    suggestedTitle: typeof src.suggestedTitle === "string" ? src.suggestedTitle : null,
+    nextForkOrdinal: typeof src.nextForkOrdinal === "number" ? src.nextForkOrdinal : null,
+    sourceTitle: typeof src.sourceTitle === "string" ? src.sourceTitle : null,
+    worktree: {
+      visible: src.worktreeVisible === true,
+      eligible: src.worktreeEligible === true,
+      unavailableReason:
+        typeof src.worktreeUnavailableReason === "string" ? src.worktreeUnavailableReason : null,
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// The four endpoint bodies
+// ---------------------------------------------------------------------------
+
+async function resolveTransport(options) {
+  if (options.transport) return options.transport;
+  const config = await import("../lib/config.js");
+  return config.MCODE_WEBUI_TRANSPORT;
+}
+
+/**
+ * Drop the sidebar tree cache, and load the modules that own it.
+ *
+ * Every action in this family changes what `GET /api/session-tree`
+ * returns — archive removes a row, fork adds one, pin reorders them —
+ * so all four invalidate. The drop is a pure cache clear with no I/O;
+ * it is dynamic-imported with the rest so this module keeps the boot
+ * path it was written with.
+ *
+ * @returns {Promise<void>}
+ */
+async function invalidateTree() {
+  const tree = await import("../lib/session-tree.js");
+  tree.invalidateSessionTree();
+}
+
+/**
+ * `POST /api/sessions/:id/archive` — archive OR unarchive one session.
+ *
+ * The method covers both directions (`req.archived !== false` in
+ * `lifecycle-application.ts#archiveSession`), so one endpoint serves
+ * both and the direction travels in the body. PB-2's archived-tasks
+ * page will call the same endpoint with `archived: false` to restore a
+ * row; that is why the flag is honoured rather than pinned to `true`.
+ *
+ * @param {object} options
+ * @param {string} options.id
+ * @param {boolean} options.archived
+ * @param {string} [options.endpoint]  Endpoint key for the declaration check.
+ * @param {string} [options.transport] Transport override.
+ * @param {object} [options.deps]      Injection seams for tests.
+ * @returns {Promise<{ok: boolean, archived: boolean, code?: string, error?: string, status?: number, payload?: object, gate?: object, transport: string}>}
+ */
+export async function applyEngineSessionArchive(options = {}) {
+  const endpoint = options.endpoint || "POST /api/sessions/:id/archive";
+  const transport = await resolveTransport(options);
+  const gate = assertSessionContextActionCapability(endpoint, transport);
+  const resolved = await resolveContextActionMember({
+    endpoint,
+    member: "cliService",
+    method: "archiveSession",
+    deps: options.deps,
+  });
+  if (!resolved.ok) {
+    return { ok: false, archived: options.archived === true, ...failurePayload(resolved), gate, transport };
+  }
+  try {
+    await resolved.member({ id: options.id, archived: options.archived });
+  } catch (e) {
+    return {
+      ok: false,
+      archived: options.archived === true,
+      code: "engine_archive_failed",
+      status: 502,
+      error: e && e.message ? e.message : String(e),
+      gate,
+      transport,
+    };
+  }
+  // The tree's SQL filter is `WHERE archived = 0`, so an archived row
+  // leaves the sidebar on the next read and an unarchived one returns.
+  // The cache would otherwise serve the pre-write assembly for 15s.
+  await invalidateTree();
+  return {
+    ok: true,
+    archived: options.archived === true,
+    payload: { ok: true, id: options.id, archived: options.archived === true },
+    gate,
+    transport,
+  };
+}
+
+/**
+ * `GET /api/sessions/:id/fork-options` — the preview the duplicate
+ * dialog renders.
+ *
+ * A READ, and the only one in this family. It is not gated on
+ * `assertEngineContextActionCapability` for archive's reasons but for a
+ * read's own: a provider that cannot fork cannot describe forking, and
+ * answering a default-shaped options object would put "canFork: false"
+ * on screen as if the engine had said it. The failure is propagated
+ * instead, so the dialog reports the same 501 the fork itself would.
+ *
+ * @param {object} options
+ * @param {string} options.id
+ * @param {string} [options.assistantMessageId]
+ * @param {string} [options.transport]
+ * @param {object} [options.deps]
+ * @returns {Promise<{ok: boolean, options?: object, code?: string, error?: string, status?: number, gate?: object, transport: string}>}
+ */
+export async function readEngineSessionForkOptions(options = {}) {
+  const endpoint = options.endpoint || "GET /api/sessions/:id/fork-options";
+  const transport = await resolveTransport(options);
+  const gate = assertSessionContextActionCapability(endpoint, transport);
+  const resolved = await resolveContextActionMember({
+    endpoint,
+    member: "cliService",
+    method: "getSessionForkOptions",
+    deps: options.deps,
+  });
+  if (!resolved.ok) {
+    return { ok: false, ...failurePayload(resolved), gate, transport };
+  }
+  const request = { id: options.id };
+  if (options.assistantMessageId) request.assistantMessageId = options.assistantMessageId;
+  try {
+    const raw = await resolved.member(request);
+    return { ok: true, options: projectForkOptions(raw), gate, transport };
+  } catch (e) {
+    return {
+      ok: false,
+      code: "engine_fork_options_failed",
+      status: 502,
+      error: e && e.message ? e.message : String(e),
+      gate,
+      transport,
+    };
+  }
+}
+
+/**
+ * `POST /api/sessions/:id/fork` — duplicate the conversation as a new
+ * session in the SAME workspace (no worktree; see the header).
+ *
+ * The response carries the created session's id so the frontend can
+ * switch to it. A fork that succeeded but reported no id would leave
+ * the user looking at a list that grew by one row with no indication
+ * of which, so a missing id is reported as a failure of the CALL rather
+ * than a success with a null id — the engine's `ForkSessionResult` has
+ * `session?` optional, and the optionality is about a session with no
+ * view shape, not about a fork that did not happen.
+ *
+ * @param {object} options
+ * @param {string} options.id
+ * @param {string} options.clientRequestId
+ * @param {string} [options.assistantMessageId]
+ * @param {string} [options.transport]
+ * @param {object} [options.deps]
+ * @returns {Promise<{ok: boolean, sessionId?: string, code?: string, error?: string, status?: number, payload?: object, gate?: object, transport: string}>}
+ */
+export async function applyEngineSessionFork(options = {}) {
+  const endpoint = options.endpoint || "POST /api/sessions/:id/fork";
+  const transport = await resolveTransport(options);
+  const gate = assertSessionContextActionCapability(endpoint, transport);
+  const resolved = await resolveContextActionMember({
+    endpoint,
+    member: "cliService",
+    method: "forkSession",
+    deps: options.deps,
+  });
+  if (!resolved.ok) {
+    return { ok: false, ...failurePayload(resolved), gate, transport };
+  }
+  let raw;
+  try {
+    raw = await resolved.member(
+      buildForkRequest({
+        id: options.id,
+        clientRequestId: options.clientRequestId,
+        assistantMessageId: options.assistantMessageId,
+      }),
+    );
+  } catch (e) {
+    return {
+      ok: false,
+      code: "engine_fork_failed",
+      status: 502,
+      error: e && e.message ? e.message : String(e),
+      gate,
+      transport,
+    };
+  }
+  const sessionId = raw && typeof raw === "object" ? raw.session?.id : undefined;
+  if (typeof sessionId !== "string" || sessionId === "") {
+    // Reached only when the engine's call resolved without a session.
+    // Reported, not swallowed: the sidebar refresh below would
+    // otherwise show a row appearing with no way to name it.
+    return {
+      ok: false,
+      code: "engine_fork_no_session",
+      status: 502,
+      error: "the engine reported no forked session",
+      gate,
+      transport,
+    };
+  }
+  await invalidateTree();
+  return {
+    ok: true,
+    sessionId,
+    payload: {
+      ok: true,
+      id: sessionId,
+      sourceId: options.id,
+      forkOriginMessageId: raw.forkOriginMessageId ?? null,
+    },
+    gate,
+    transport,
+  };
+}
+
+/**
+ * `POST /api/sessions/:id/pin` — pin or unpin a session.
+ *
+ * The only endpoint of the family that reads the PB-8 window rather
+ * than `host.cliService`, and the one whose absence cases are the most
+ * interesting. All three of `getHostServices()`'s states are handled
+ * with their own code, and none of them produces a success payload:
+ *
+ *   null      → 503 engine_host_unavailable     (no runtime booted)
+ *   undefined → 501 engine_services_unavailable (host without owner graph)
+ *   object    → 501 engine_member_unavailable   (no `pinService` on it)
+ *
+ * @param {object} options
+ * @param {string} options.id
+ * @param {boolean} options.pinned
+ * @param {string} [options.transport]
+ * @param {object} [options.deps]
+ * @returns {Promise<{ok: boolean, pinned: boolean, pinnedIds?: string[], code?: string, error?: string, status?: number, payload?: object, gate?: object, transport: string}>}
+ */
+export async function applyEngineSessionPin(options = {}) {
+  const endpoint = options.endpoint || "POST /api/sessions/:id/pin";
+  const transport = await resolveTransport(options);
+  const gate = assertSessionContextActionCapability(endpoint, transport);
+  const resolved = await resolveContextActionMember({
+    endpoint,
+    member: "services.pinService",
+    method: "pinSession",
+    deps: options.deps,
+  });
+  if (!resolved.ok) {
+    return { ok: false, pinned: options.pinned === true, ...failurePayload(resolved), gate, transport };
+  }
+  let mutation;
+  try {
+    // No `insertIndex`: the engine appends, and this batch does not offer
+    // an ordering control the desktop has no reference for.
+    mutation = await resolved.member(options.id, options.pinned === true);
+  } catch (e) {
+    return {
+      ok: false,
+      pinned: options.pinned === true,
+      code: "engine_pin_failed",
+      status: 502,
+      error: e && e.message ? e.message : String(e),
+      gate,
+      transport,
+    };
+  }
+  const pinnedIds = projectPinnedSessionIds(mutation);
+  await invalidateTree();
+  return {
+    ok: true,
+    pinned: options.pinned === true,
+    pinnedIds,
+    payload: { ok: true, id: options.id, pinned: options.pinned === true, pinnedIds },
+    gate,
+    transport,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// The pin read the sidebar needs — and the one soft gate in this file
+// ---------------------------------------------------------------------------
+
+/**
+ * The session ids currently pinned, in the engine's own order.
+ *
+ * A `PinMutation` and a `PinItem[]` are accepted because `pinSession`
+ * returns the former and `getOrder()` the latter; both carry the same
+ * `items`, and the dialog/tree only ever needs the ids. Non-session
+ * refs (agents, projects) are dropped — they are ordered in a different
+ * surface that this batch does not render.
+ *
+ * @param {object} value A `PinMutation` or a `readonly PinItem[]`.
+ * @returns {string[]}
+ */
+export function projectPinnedSessionIds(value) {
+  const items = Array.isArray(value) ? value : value && typeof value === "object" ? value.items : null;
+  if (!Array.isArray(items)) return [];
+  const ids = [];
+  for (const item of items) {
+    const ref = item && typeof item === "object" ? item.ref : null;
+    if (ref && ref.type === "session" && typeof ref.id === "string" && ref.id !== "") {
+      ids.push(ref.id);
+    }
+  }
+  return ids;
+}
+
+/**
+ * The pinned session ids for the sidebar overlay, or `[]` when the
+ * engine cannot answer.
+ *
+ * THIS FUNCTION DEGRADES, and it is the only member of this file that
+ * does. The reasoning is that the alternative is a sidebar that will
+ * not render: `GET /api/session-tree` is the page's primary data
+ * source, and a pin service that failed to answer is not a reason to
+ * fail the whole tree. An empty answer means "no pins are currently
+ * shown", which is a cosmetic loss; a failed tree is a broken page.
+ *
+ * The contrast with the four endpoints above is the point: those
+ * MUTATE, and a mutation that cannot confirm its write must not claim
+ * success. This one only reads an ordering, and an ordering has no
+ * truth to falsify — the worst a wrong answer can do is show a row in
+ * the wrong place, and the next successful read corrects it.
+ *
+ * IT USES THE NON-BOOTING HOST GETTER, and that is not a detail. The
+ * ordinary `getEngineCatalogueHost()` boots the runtime on its first
+ * call — seconds of construction — so a READ that reached for it would
+ * turn the first `GET /api/session-tree` of a fresh process into a
+ * runtime boot, and the cost would land on whoever painted the page
+ * first while looking like an ordinary slow request. `peekEngineCatalogueHost()`
+ * answers `null` when no host is up, which this function reports as a
+ * degraded read. The rule it encodes: a write may boot what it needs; a
+ * read may only use what is already there.
+ *
+ * @param {object} [deps]
+ * @param {() => Promise<object|null|undefined>} [deps.getHost] Host getter
+ *        seam; defaults to the NON-BOOTING peek.
+ * @returns {Promise<{pinnedIds: string[], degraded: boolean, reason: string|null}>}
+ */
+export async function readEnginePinnedSessionOrder(deps = {}) {
+  const getHost =
+    deps.getHost || (await import("./host.js")).peekEngineCatalogueHost;
+  let host;
+  try {
+    host = await getHost();
+  } catch {
+    return { pinnedIds: [], degraded: true, reason: "engine_host_unavailable" };
+  }
+  if (!host) return { pinnedIds: [], degraded: true, reason: "engine_host_unavailable" };
+  const services = host.services;
+  if (services === undefined) {
+    return { pinnedIds: [], degraded: true, reason: "engine_services_unavailable" };
+  }
+  if (services === null) {
+    return { pinnedIds: [], degraded: true, reason: "engine_host_unavailable" };
+  }
+  const pinService = services.pinService;
+  if (typeof pinService?.getOrder !== "function") {
+    return { pinnedIds: [], degraded: true, reason: "pin_service_unavailable" };
+  }
+  try {
+    return { pinnedIds: projectPinnedSessionIds(await pinService.getOrder()), degraded: false, reason: null };
+  } catch {
+    return { pinnedIds: [], degraded: true, reason: "engine_pin_read_failed" };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// The sidebar overlay
+// ---------------------------------------------------------------------------
+
+/**
+ * Mark the pinned sessions in a `GET /api/session-tree` payload and move
+ * them to the top of their directory, in the engine's own pin order.
+ *
+ * Why this is a PURE overlay and not a change to the SQL. The tree's
+ * rows come from `lib/session-tree.js`, which scans
+ * `local_runtime_sessions` — a table with no pin column, because the pin
+ * state lives in the preference store the `PinService` owns. Making the
+ * read aware of pins would mean either joining two stores inside one
+ * query or teaching the tree module about a second owner; the overlay
+ * keeps `lib/session-tree.js` exactly as it was and puts the second
+ * store's contribution at the edge, where a failure can be dropped
+ * without taking the tree with it.
+ *
+ * The ordering is `pinned → not pinned`, and WITHIN each group the
+ * existing `updatedAt` order is left untouched. Two rules that are
+ * load-bearing in both directions:
+ *
+ *   - The comparator is STABLE in the sense that matters here: it never
+ *     reorders two sessions that are both pinned or both unpinned, so a
+ *     tree with no pins at all is byte-identical to the tree before this
+ *     batch. A sort that reordered equal keys would make every unpinned
+ *     sidebar shuffle on every read.
+ *   - Pinned sessions are ordered by the ENGINE's pin order, not by
+ *     `updatedAt`. The engine owns that order (`PinService` persists it
+ *     under `pinned-items-order`), and a webui-side re-sort would fight
+ *     it on the next write. An id the overlay was given but the tree
+ *     does not contain is simply absent from the output — the two stores
+ *     are read at different instants and this is the window KNOWN DEBT 3
+ *     records.
+ *
+ * `pinned: true` is written onto a session that is pinned and
+ * `pinned: false` onto one that is not, so the frontend reads a boolean
+ * and never has to know the id set exists. The field is added to EVERY
+ * session, including in the untouched unpinned case, because a field
+ * that appears only sometimes is a field the client has to guard.
+ *
+ * @param {object} tree The `getSessionTree` payload, verbatim.
+ * @param {string[]} pinnedIds Session ids, in engine pin order.
+ * @returns {object} A new payload. The input is not mutated.
+ */
+export function applyPinnedSessionOverlay(tree, pinnedIds) {
+  if (!tree || typeof tree !== "object" || !Array.isArray(tree.projects)) return tree;
+  const order = new Map();
+  const ids = Array.isArray(pinnedIds) ? pinnedIds : [];
+  for (const id of ids) {
+    if (typeof id === "string" && id !== "" && !order.has(id)) order.set(id, order.size);
+  }
+  const rank = (id) => (order.has(id) ? order.get(id) : Number.MAX_SAFE_INTEGER);
+  return {
+    ...tree,
+    projects: tree.projects.map((project) => {
+      if (!project || !Array.isArray(project.directories)) return project;
+      return {
+        ...project,
+        directories: project.directories.map((directory) => {
+          if (!directory || !Array.isArray(directory.sessions)) return directory;
+          return {
+            ...directory,
+            sessions: directory.sessions
+              .map((session) => ({
+                ...session,
+                pinned: order.has(session?.id),
+              }))
+              // `rank` already puts every unpinned session after every
+              // pinned one, and both groups keep their input order
+              // because `Array.prototype.sort` is stable in every engine
+              // this project supports (ES2019 guarantees it).
+              .sort((a, b) => rank(a?.id) - rank(b?.id)),
+          };
+        }),
+      };
+    }),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// KNOWN DEBT
+// ---------------------------------------------------------------------------
+//
+// Recorded rather than fixed, because each is a decision that belongs
+// to a human and not to a window:
+//
+//   1. 「复制到新工作树」stays an honest placeholder. The engine side is
+//      present and unused: `ForkSessionInput.createIsolatedWorktree`
+//      exists, and `getSessionForkOptions` already returns
+//      `worktreeVisible` / `worktreeEligible` /
+//      `worktreeUnavailableReason` — `projectForkOptions` carries all
+//      three through untouched so nothing has to be re-derived. What is
+//      absent is a REFERENCE: design-ref/ holds no screenshot of this
+//      menu, so the dialog's shape, whether a branch is chosen, and
+//      what happens to the source session are all unknown. Per §3.4 of
+//      doc/placeholder-batch-plan.md, this batch does not self-author
+//      that form.
+//
+//   2. 项目右键「归档对话」stays an honest placeholder. v2 declares
+//      `archiveSession({id, archived})` and nothing project-scoped. A
+//      batch endpoint would fan out N single-session writes, and the
+//      semantics that fan-out needs — is a partial failure a success?
+//      is the user authorized once or N times? does one engine error
+//      roll the rest back? — are product decisions that no existing
+//      contract answers.
+//
+//   3. The pin overlay on `GET /api/session-tree` is added in
+//      `session-tree-reads.js`, and it reads pin state from the ENGINE
+//      while the rest of that read comes from the runtime db. The two
+//      stores are not in a transaction, so a pin written between the
+//      db scan and the pin read can produce one render that disagrees
+//      with itself. The window is 15s and self-correcting; closing it
+//      means a single engine query that returns sessions ordered.
+//
+//   4. `archiveSession` and `forkSession` are declared against
+//      `sessionCrud` and therefore inherit that key's meaning on every
+//      provider. The `acp` declaration lists `archiveSession` in
+//      `missing` (acp.capabilities.js:123) — correct for the PROTOCOL,
+//      and the reason this family resolves through the in-process host
+//      under that transport is the M4-3a shape, not an oversight. If a
+//      future audit finds a provider that declares `sessionCrud: full`
+//      without these two methods on its `cliService`, the snapshot test
+//      (test/lib/engine/capability-snapshot.test.js:345) is where it
+//      goes red.
diff --git a/packages/webui/server/lib/acp-client.js b/packages/webui/server/lib/acp-client.js
index 9c721e7c..cd805845 100644
--- a/packages/webui/server/lib/acp-client.js
+++ b/packages/webui/server/lib/acp-client.js
@@ -84,6 +84,33 @@ export async function getCatalogueHost() {
   return _catalogueHostInitPromise;
 }
 
+/**
+ * The catalogue host IF one is already up — `null` otherwise. Never boots.
+ *
+ * The distinction from `getCatalogueHost()` is the whole point: that one is
+ * a BOOTING getter, and a first call costs seconds because it constructs
+ * the runtime. A read that needs the engine must not pay that, because the
+ * cost lands on whoever happened to make the request first — usually the
+ * page's first paint — and it looks like an ordinary slow request rather
+ * than a boot.
+ *
+ * A boot that is ALREADY IN PROGRESS also answers `null` here. Waiting on
+ * it would make a read pay for a write's boot anyway, and would make two
+ * concurrent first reads serialise behind one another's latency. The read
+ * answers without the engine, and the next read — by then the host is up —
+ * gets the full answer. That is the same degrade-on-read contract the pin
+ * overlay uses, one level down.
+ *
+ * Added by PB-1 for `engine/session-context-actions.js#readEnginePinnedSessionOrder`,
+ * which reached the `PinService` through the booting getter and turned the
+ * first `GET /api/session-tree` of a fresh process into a runtime boot.
+ * The WRITE half of that family still uses the booting getter on purpose:
+ * the user asked for an action, and it may bring up what it needs.
+ */
+export function peekCatalogueHost() {
+  return _catalogueHost ?? null;
+}
+
 function transportWantsCatalogue() {
   return MCODE_WEBUI_TRANSPORT === "runtime";
 }
diff --git a/packages/webui/server/lib/mcode-exec.js b/packages/webui/server/lib/mcode-exec.js
index d2e7bf8c..376b879f 100644
--- a/packages/webui/server/lib/mcode-exec.js
+++ b/packages/webui/server/lib/mcode-exec.js
@@ -216,6 +216,54 @@ export function runMcodeExec(prompt, opts = {}) {
   return { child, args, label, model, workspace, sessionId, cs, cid };
 }
 
+// ---------------------------------------------------------------------------
+// THE WIRE (D1)
+// ---------------------------------------------------------------------------
+//
+// `mcode exec --output-format stream-json` writes EXACTLY the projected
+// `ExecEvent` union (packages/tui/src/headless/events.ts:27-48), one JSON
+// object per line, and nothing else:
+//
+//   - `output.ts:34-36` refuses `stream-json` outright when no
+//     `ExecEventProjector` was supplied, so there is no unprojected path;
+//   - `runner.ts:218-232` always supplies one for this format;
+//   - the encoder's `result()` leg, for `stream-json`, goes through
+//     `projector.complete()` (output.ts:47-53) rather than writing the
+//     `ExecResult` itself — `exec.result` is the `json` format's line
+//     (contract.ts:42), so it is a PAYLOAD the wire carries inside
+//     `exec.completed`, never a line the wire writes.
+//
+// The three names this parser used to branch on — `delta`, `message`,
+// `exec.result` — are the SUPERVISOR's internal `TuiStreamEvent` names
+// (packages/tui/src/runtime/stream-events.ts, consumed by
+// `ExecEventProjector.project`). They never reach stdout. The two name
+// families have an empty intersection, which is why the exec transport
+// produced no streaming delta, no session id, no usage and no terminal
+// status: every turn on this transport ended with `status: "unknown"` and
+// an empty answer, whatever the agent had actually said.
+//
+// The switch below is therefore keyed on the WIRE's names. Every one of
+// them is listed in `EXEC_INTERFACE.consumedEvents`
+// (server/engine/providers/exec.capabilities.js), and
+// `test/lib/engine/capability-snapshot.test.js` keeps that list and this
+// switch equal by reading both.
+//
+// `exec.started`, `session.started`, `session.resumed` and `turn.started`
+// carry no payload beyond `ExecEventBase` and fall into `default`. The one
+// thing every line does carry is `sessionId` (events.ts:12-17), which is
+// adopted below the switch for exactly that reason.
+// ---------------------------------------------------------------------------
+
+// The `ExecItem.type` → the webui streaming marker. `tool_call` has no
+// marker and is not rendered: the exec transport's tool surface is
+// produced but invisible, which EXEC_CAPABILITIES.toolSkillInvocation
+// records. Naming the mapping in one place keeps the two switch arms
+// (delta and completed) from disagreeing.
+const ITEM_STREAM_MARKER = Object.freeze({
+  reasoning: "▲",
+  agent_message: "●",
+});
+
 // collectExecResult: 解析 stream-json + 累加 result。
 // 完成后会 pushStateFor(cid)，调用方不需要再 push。
 export function collectExecResult(childPromise) {
@@ -234,6 +282,15 @@ export function collectExecResult(childPromise) {
     let buf = "";
     const t0 = Date.now();
     const { child, label, model, cs, cid, sessionId } = childPromise;
+    // Per-item streaming state. `streamItem` is the item whose text the
+    // current `▲`/`●` line is accumulating, so a new item (or a switch
+    // between reasoning and answer) starts a fresh line instead of
+    // gluing two unrelated texts together — the same reset mcode-acp's
+    // `lastChunkKind` performs. `streamedItemIds` records which items
+    // already delivered their text as deltas, so the authoritative
+    // `item.completed` copy of that same text is not appended twice.
+    let streamItem = null;
+    const streamedItemIds = new Set();
     cs.running = {
       active: true,
       prompt: label,
@@ -256,38 +313,40 @@ export function collectExecResult(childPromise) {
         if (!line) continue;
         try {
           const m = JSON.parse(line);
-          if (m.type === "delta") {
-            if (typeof m.thinking === "string") {
-              r.thinking = (r.thinking || "") + m.thinking;
-              const oneLine = r.thinking.replace(/\n+/g, " ").trim();
-              streamUpdateLine(cs.chat, "▲", oneLine);
-            }
-            if (typeof m.content === "string") {
-              r.answer = (r.answer || "") + m.content;
-              const oneLine = r.answer.replace(/\n+/g, " ").trim();
-              streamUpdateLine(cs.chat, "●", oneLine);
-            }
-            const now = Date.now();
-            if (cs.running.lastDeltaAt) {
-              const dt = (now - cs.running.lastDeltaAt) / 1000;
-              if (dt > 0) cs.running.tps = Math.round(1 / dt);
-            }
-            cs.running.lastDeltaAt = now;
-            cs.context.tps = cs.running.tps;
-            pushStateFor(cid);
-          } else if (m.type === "message" && m.message) {
-            if (m.message.usage) r.usage = m.message.usage;
-            if (typeof m.message.content === "string" && !r.answer)
-              r.answer = m.message.content;
-            if (typeof m.message.thinking === "string" && !r.thinking)
-              r.thinking = m.message.thinking;
-          } else if (m.type === "exec.result") {
-            if (m.sessionId) r.sessionId = m.sessionId;
-            if (typeof m.durationMs === "number") r.durationMs = m.durationMs;
-            if (m.answer) r.answer = m.answer;
-            r.status = m.status || "unknown";
-            if (m.error) r.error = m.error;
-            finalize();
+          if (!m || typeof m !== "object") continue;
+          adoptSessionId(m);
+          switch (m.type) {
+            case "item.started":
+            case "item.updated":
+              consumeItemText(m.item, m.item && m.item.contentDelta);
+              break;
+            case "item.completed":
+              // The authoritative full text. Adopted only for an item
+              // that never streamed — a turn whose whole message arrived
+              // in one `message` event emits no delta, and dropping it
+              // would leave `answer` empty for a turn that did produce
+              // output.
+              if (m.item && !streamedItemIds.has(m.item.id)) {
+                consumeItemText(m.item, m.item.content);
+              }
+              break;
+            case "turn.completed":
+              if (m.usage) r.usage = m.usage;
+              if (typeof m.durationMs === "number") r.durationMs = m.durationMs;
+              break;
+            case "turn.failed":
+              r.status = m.status || "failed";
+              if (m.error) r.error = m.error;
+              if (typeof m.durationMs === "number") r.durationMs = m.durationMs;
+              break;
+            case "exec.completed":
+              finishFromResult(m.result);
+              break;
+            default:
+              // exec.started / session.started / session.resumed /
+              // turn.started — `ExecEventBase` only; `sessionId` was
+              // already adopted above.
+              break;
           }
         } catch {}
       }
@@ -295,6 +354,68 @@ export function collectExecResult(childPromise) {
     child.stderr.setEncoding("utf8");
     child.stderr.on("data", () => {}); // swallow; usage stats can land here
 
+    // `ExecEventBase.sessionId` (events.ts:12-17) is on EVERY line, so the
+    // engine session this run entered is known from the first event —
+    // which is what lets the turn be continued next time, and what the
+    // old parser could never learn (it read `sessionId` off an
+    // `exec.result` line the wire never wrote).
+    function adoptSessionId(m) {
+      if (typeof m.sessionId === "string" && m.sessionId) r.sessionId = m.sessionId;
+    }
+
+    // Fold one chunk of an item's text into the accumulator and the
+    // streaming line. `text` is `item.contentDelta` on the started/
+    // updated arms and `item.content` on the completed arm; both are
+    // "append this much text to this item".
+    function consumeItemText(item, text) {
+      if (!item || typeof text !== "string" || !text) return;
+      const marker = ITEM_STREAM_MARKER[item.type];
+      if (!marker) return; // tool_call — produced, not rendered
+      if (item.id !== undefined) streamedItemIds.add(item.id);
+      if (item.type === "reasoning") r.thinking = (r.thinking || "") + text;
+      else r.answer = (r.answer || "") + text;
+      if (streamItem && streamItem.id === item.id && streamItem.marker === marker) {
+        streamItem.text += text;
+      } else {
+        streamItem = { id: item.id, marker, text };
+      }
+      streamUpdateLine(cs.chat, marker, streamItem.text.replace(/\n+/g, " ").trim());
+      noteStreamActivity();
+    }
+
+    // The idle watchdog's clock and the front-end's tps readout both
+    // move on every text chunk — the exec transport's equivalent of the
+    // acp runner's per-event `lastDeltaAt` refresh.
+    function noteStreamActivity() {
+      const now = Date.now();
+      if (cs.running.lastDeltaAt) {
+        const dt = (now - cs.running.lastDeltaAt) / 1000;
+        if (dt > 0) cs.running.tps = Math.round(1 / dt);
+      }
+      cs.running.lastDeltaAt = now;
+      cs.context.tps = cs.running.tps;
+      pushStateFor(cid);
+    }
+
+    // `exec.completed` is the terminal wire event and carries the whole
+    // `ExecResult` (contract.ts:39-55) under `result` — including the
+    // `exec.result` payload shape the old parser was reaching for, and
+    // the final `output` for a turn that produced text without ever
+    // streaming a delta.
+    function finishFromResult(result) {
+      if (result && typeof result === "object") {
+        if (typeof result.sessionId === "string" && result.sessionId) {
+          r.sessionId = result.sessionId;
+        }
+        if (result.status) r.status = result.status;
+        if (result.error) r.error = result.error;
+        if (typeof result.durationMs === "number") r.durationMs = result.durationMs;
+        if (!r.usage && result.usage) r.usage = result.usage;
+        if (!r.answer && typeof result.output === "string") r.answer = result.output;
+      }
+      finalize();
+    }
+
     // v2.3: idle watchdog (see mcode-acp.js) — stream lines refresh
     //   cs.running.lastDeltaAt; only a silent stream trips this.
     const idleSeconds = Math.round(PROMPT_IDLE_TIMEOUT_MS / 1000);
@@ -343,6 +464,18 @@ export function collectExecResult(childPromise) {
           `§§ processed_duration=${Math.round(r.durationMs)}ms`,
         ];
       }
+      // Strip the streaming cursor ▍ from every line — streamUpdateLine
+      // adds it on every push, and finalize must clear it or the exec
+      // transport's answer line stays marked as streaming forever. Same
+      // rule mcode-acp's finalize applies.
+      if (Array.isArray(cs.chat)) {
+        for (let i = 0; i < cs.chat.length; i += 1) {
+          const line = cs.chat[i];
+          if (typeof line === "string" && line.endsWith(" ▍")) {
+            cs.chat[i] = line.slice(0, -2);
+          }
+        }
+      }
       if (r._stopped) r.status = "stopped";
       // Scoped to this turn's engine session — a sibling conversation's
       // child in the same tab survives.
diff --git a/packages/webui/server/routes/sessions.js b/packages/webui/server/routes/sessions.js
index fc941a77..6c054690 100644
--- a/packages/webui/server/routes/sessions.js
+++ b/packages/webui/server/routes/sessions.js
@@ -99,6 +99,26 @@ import { applyEngineSessionSwitch } from "../engine/session-switch.js";
 // protocol cannot drift onto two different notions of "is this the gate's
 // error".
 import { isEngineCapabilityNotSupportedError } from "../engine/index.js";
+// PB-1 (session context actions): the four right-click endpoints —
+// archive / pin / fork-options / fork. Same split as every other engine
+// family above: the gate, the member resolution, the three-state host
+// handling and the response bodies live in the facade; what stays here
+// is the request parse, the status code and the audit. The pin endpoint
+// is the family's only one that reads the PB-8 `getHostServices()`
+// window rather than `host.cliService`, and its three absence codes
+// (503 / 501 / 501) each get their own branch below — see the facade's
+// KNOWN DEBT for why a presence gate is honest here where a capability
+// key would be a 15th audited matrix entry for one method.
+import {
+  applyEngineSessionArchive,
+  applyEngineSessionFork,
+  applyEngineSessionPin,
+  applyPinnedSessionOverlay,
+  parseArchiveRequestBody,
+  parsePinRequestBody,
+  readEnginePinnedSessionOrder,
+  readEngineSessionForkOptions,
+} from "../engine/session-context-actions.js";
 import { authorize } from "../lib/authorize.js";
 import { pushAlert } from "../lib/alerts.js";
 import { append as _eventsAppend } from "../lib/events.js";
@@ -616,6 +636,26 @@ export async function handleSessionTree(req, res, _ctx) {
       detail: String(cause && cause.message ? cause.message : cause),
     };
   }
+  // PB-1: the pin overlay. `lib/session-tree.js` reads
+  // `local_runtime_sessions`, which has no pin column — the pin state
+  // lives in the preference store the engine's `PinService` owns — so
+  // the tree is read first and the pins are laid over it. The overlay is
+  // applied ONLY to a successful tree: a soft-failed payload has no
+  // `projects` to mark, and `applyPinnedSessionOverlay` returns such a
+  // payload unchanged, which is one fewer branch to get wrong.
+  //
+  // The pin read DEGRADES by design (see
+  // `readEnginePinnedSessionOrder`'s own header): a host that cannot
+  // answer yields `pinnedIds: []`, and the sidebar renders the tree it
+  // already has. The reason travels in `pins` so the response says
+  // whether the absence is a fact ("nothing is pinned") or a failure
+  // ("the engine could not tell us") — a client that cannot tell those
+  // apart would show an empty pin section during an outage and read it
+  // as "the user has no pins".
+  if (payload && payload.ok === true) {
+    const pins = await readEnginePinnedSessionOrder();
+    payload = { ...applyPinnedSessionOverlay(payload, pins.pinnedIds), pins };
+  }
   // Always 200: a soft failure (`ok:false` + `reason`, e.g. the runtime db is
   // missing) is a normal state the sidebar handles, not a transport error. The
   // client's `request()` helper turns any non-2xx into a thrown `HTTP <status>`,
@@ -968,3 +1008,234 @@ export async function handleCleanupOrphans(req, res, ctx) {
     decidedAt: authResult.decidedAt,
   }));
 }
+
+// ---------------------------------------------------------------------------
+// PB-1 — the session right-click action family
+// ---------------------------------------------------------------------------
+//
+// Four endpoints, one per menu item, and the file's own rule applies to
+// all of them: parse here, decide the status here, cross the engine seam
+// through `engine/session-context-actions.js`. What the facade does NOT
+// know is what an HTTP status is, so every failure it returns carries
+// `code` + `status` and the mapping happens in the one helper below.
+//
+// The helper exists because the family's failure space is wider than the
+// rest of this file's and getting it right four times is how one of them
+// would drift:
+//
+//   400  the request itself is wrong (missing id, `pinned` not boolean)
+//   501  the engine cannot do it — the capability gate's throw, a host
+//        with no owner graph, or a host whose owner graph has no
+//        `pinService`
+//   502  the engine was asked and failed
+//   503  no runtime is booted at all
+//
+// The distinction between 501 and 503 is the one an operator needs and
+// the one a route that collapsed them would lose: 501 means "this
+// transport cannot", 503 means "the process is not running its
+// runtime", and they have different fixes.
+
+/** Map a facade failure onto the wire. The `ok:true` case never arrives. */
+function _contextActionFail(res, result) {
+  const status = Number.isInteger(result.status) ? result.status : 500;
+  res.writeHead(status, { "Content-Type": "application/json; charset=utf-8" });
+  return res.end(
+    JSON.stringify({
+      ok: false,
+      code: result.code || "engine_call_failed",
+      error: result.error || "the engine call failed",
+    }),
+  );
+}
+
+/**
+ * The `:id` of a `POST|GET /api/sessions/:id/<verb>` path, sliced from
+ * `ctx.pathname` the way `handleDeleteSession` does.
+ *
+ * Named because four handlers would otherwise each re-derive the same
+ * two `indexOf` pair, and the copy that drifts is the one that starts
+ * accepting `/api/sessions//archive` as a session id.
+ *
+ * @param {string} pathname
+ * @param {string} verb The trailing path segment, e.g. `"archive"`.
+ * @returns {string} The id, or `""` when the path does not end in `verb`.
+ */
+function _contextActionSessionId(pathname, verb) {
+  const prefix = "/api/sessions/";
+  const suffix = `/${verb}`;
+  if (typeof pathname !== "string") return "";
+  if (!pathname.startsWith(prefix) || !pathname.endsWith(suffix)) return "";
+  return pathname.slice(prefix.length, pathname.length - suffix.length);
+}
+
+// POST /api/sessions/:id/archive — archive (or unarchive) one session.
+//
+// `body.archived` selects the direction and defaults to `true`. The
+// method covers both directions in the engine
+// (`lifecycle-application.ts#archiveSession` reads `req.archived !==
+// false`), so one endpoint serves both and PB-2's archived-tasks page
+// restores a row by calling it with `archived: false`.
+//
+// No `authorize()` modal, and the reason is worth stating because
+// `DELETE /api/sessions/:id` has one: archive is not destruction. The
+// conversation is intact on the engine, the row leaves the sidebar and
+// can be restored by the same call. A confirm dialog on a reversible
+// action is a dialog the user learns to dismiss.
+export async function handleArchiveSession(req, res, ctx) {
+  const cid = ctx.cid;
+  const id = _contextActionSessionId(ctx.pathname, "archive");
+  if (!id) {
+    res.writeHead(400, { "Content-Type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ ok: false, error: "id required" }));
+  }
+  const payload = await readJson(req);
+  const parsed = parseArchiveRequestBody(payload);
+  if (!parsed.ok) {
+    res.writeHead(400, { "Content-Type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ ok: false, error: parsed.error }));
+  }
+  const result = await applyEngineSessionArchive({ id, archived: parsed.archived });
+  if (!result.ok) return _contextActionFail(res, result);
+  // Write-ahead audit: a state change the user cannot see in the engine's
+  // own UI is exactly the kind that needs a durable record, and it lands
+  // after the engine confirmed the write rather than before — unlike
+  // #7's delete, where the ordering protects an irreversible step.
+  try {
+    _eventsAppend(result.archived ? "session.archive" : "session.unarchive", {
+      target: id,
+      cid,
+      actor: "user",
+      payload: { archived: result.archived, mcodeSessionId: "" },
+    });
+  } catch (e) {
+    return _auditFail(res, e, result.archived ? "session.archive" : "session.unarchive");
+  }
+  console.log(
+    `[archive] cid=${cid} OK id=${id.substring(0, 8)}… archived=${result.archived}`,
+  );
+  res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
+  return res.end(JSON.stringify(result.payload));
+}
+
+// POST /api/sessions/:id/pin — pin or unpin a session.
+//
+// The `pinned` flag is REQUIRED here, unlike `archived`. The engine's
+// `pinSession(sessionId, pinned, insertIndex?)` takes it as a
+// positional and branches on it, so `{}` is not a defaultable request:
+// defaulting it would move the row in a direction the user did not
+// choose. `parsePinRequestBody` owns that rule and is unit-tested on
+// both directions.
+export async function handlePinSession(req, res, ctx) {
+  const cid = ctx.cid;
+  const id = _contextActionSessionId(ctx.pathname, "pin");
+  if (!id) {
+    res.writeHead(400, { "Content-Type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ ok: false, error: "id required" }));
+  }
+  const payload = await readJson(req);
+  const parsed = parsePinRequestBody(payload);
+  if (!parsed.ok) {
+    res.writeHead(400, { "Content-Type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ ok: false, error: parsed.error }));
+  }
+  const result = await applyEngineSessionPin({ id, pinned: parsed.pinned });
+  if (!result.ok) return _contextActionFail(res, result);
+  try {
+    _eventsAppend(result.pinned ? "session.pin" : "session.unpin", {
+      target: id,
+      cid,
+      actor: "user",
+      payload: { pinned: result.pinned, mcodeSessionId: "" },
+    });
+  } catch (e) {
+    return _auditFail(res, e, result.pinned ? "session.pin" : "session.unpin");
+  }
+  console.log(`[pin] cid=${cid} OK id=${id.substring(0, 8)}… pinned=${result.pinned}`);
+  res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
+  return res.end(JSON.stringify(result.payload));
+}
+
+// GET /api/sessions/:id/fork-options — what a fork of this session would
+// be, before the user commits to one.
+//
+// The optional `?assistantMessageId=` narrows the preview to a fork
+// POINT. Absent, the preview describes forking the whole conversation,
+// which is what the menu item means when the user has not picked a
+// message. The response is the facade's `projectForkOptions` narrowing
+// — every field present on every answer, so the dialog never renders
+// `undefined` — and the worktree triple travels through untouched for
+// the batch that will consume it (see the facade's KNOWN DEBT 1).
+export async function handleSessionForkOptions(req, res, ctx) {
+  const id = _contextActionSessionId(ctx.pathname, "fork-options");
+  if (!id) {
+    res.writeHead(400, { "Content-Type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ ok: false, error: "id required" }));
+  }
+  // Read the query off `req.url` rather than `ctx.pathname`, matching
+  // `handleDeleteSession`'s `?dryRun` parse: the Hono context carries
+  // the path, the query is still on the Node request.
+  let assistantMessageId;
+  try {
+    const qIdx = (req.url || "").indexOf("?");
+    if (qIdx >= 0) {
+      assistantMessageId = new URLSearchParams(req.url.slice(qIdx + 1)).get("assistantMessageId") || undefined;
+    }
+  } catch {}
+  const result = await readEngineSessionForkOptions({ id, assistantMessageId });
+  if (!result.ok) return _contextActionFail(res, result);
+  res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
+  return res.end(JSON.stringify({ ok: true, id, ...result.options }));
+}
+
+// POST /api/sessions/:id/fork — duplicate this conversation as a new
+// session in the same workspace.
+//
+// `clientRequestId` is minted HERE rather than in the facade, so the
+// per-request key is visible at the call site that owns the request. It
+// is the engine's fork-deduplication key, which means a duplicate
+// delivery of one POST does not create two forks while a user who
+// genuinely duplicates twice gets two sessions — the distinction the
+// menu item's meaning depends on.
+//
+// `createIsolatedWorktree` is forced `false` in the facade. The
+// worktree variant of this menu has no desktop reference, so it stays
+// an honest placeholder rather than becoming reachable by a flag.
+export async function handleForkSession(req, res, ctx) {
+  const cid = ctx.cid;
+  const id = _contextActionSessionId(ctx.pathname, "fork");
+  if (!id) {
+    res.writeHead(400, { "Content-Type": "application/json; charset=utf-8" });
+    return res.end(JSON.stringify({ ok: false, error: "id required" }));
+  }
+  const payload = await readJson(req);
+  const assistantMessageId =
+    typeof payload.assistantMessageId === "string" && payload.assistantMessageId
+      ? payload.assistantMessageId
+      : undefined;
+  const result = await applyEngineSessionFork({
+    id,
+    assistantMessageId,
+    clientRequestId: randomUUID(),
+  });
+  if (!result.ok) return _contextActionFail(res, result);
+  try {
+    _eventsAppend("session.fork", {
+      target: id,
+      cid,
+      actor: "user",
+      payload: {
+        sourceId: id,
+        newSessionId: result.sessionId,
+        forkOriginMessageId: result.payload.forkOriginMessageId || "",
+        createIsolatedWorktree: false,
+      },
+    });
+  } catch (e) {
+    return _auditFail(res, e, "session.fork");
+  }
+  console.log(
+    `[fork] cid=${cid} OK source=${id.substring(0, 8)}… new=${result.sessionId.substring(0, 8)}…`,
+  );
+  res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
+  return res.end(JSON.stringify(result.payload));
+}
diff --git a/packages/webui/test/lib/engine/capabilities.test.js b/packages/webui/test/lib/engine/capabilities.test.js
index 93e73a4e..100d1da5 100644
--- a/packages/webui/test/lib/engine/capabilities.test.js
+++ b/packages/webui/test/lib/engine/capabilities.test.js
@@ -641,23 +641,43 @@ describe("EXEC_CAPABILITIES", () => {
   });
 
   // toolSkillInvocation is the one key where the transport PRODUCES the
-  // events and webui cannot READ them — a fact strong enough that the
-  // reason has to carry it, because a reader who only saw "partial,
-  // tool_call is present" would conclude the tool surface is consumed.
-  test("toolSkillInvocation admits the tool_call events are never consumed", () => {
+  // events and webui consumes them but RENDERS none of them — a fact
+  // strong enough that the reason has to carry it, because a reader who
+  // only saw "partial, tool_call is present" would conclude the tool
+  // surface is shown. D1 moved half of this: the parser reads the item
+  // stream now, so the claim is "not RENDERED", not "not read".
+  test("toolSkillInvocation admits the tool_call events are consumed but not rendered", () => {
     assert.equal(EXEC_CAPABILITIES.toolSkillInvocation.level, "partial");
     assert.match(EXEC_CAPABILITIES.toolSkillInvocation.reason, /tool_call/);
     assert.match(EXEC_CAPABILITIES.toolSkillInvocation.reason, /mcode-exec\.js/);
-    assert.match(EXEC_CAPABILITIES.toolSkillInvocation.reason, /does not read them/);
+    assert.match(EXEC_CAPABILITIES.toolSkillInvocation.reason, /does not RENDER them/);
     // `consumedEvents` is the machine-checkable half of the same fact,
-    // and the suite below proves the two halves agree: the three names
-    // webui branches on are not names the wire can emit.
-    assert.deepEqual(EXEC_INTERFACE.consumedEvents, ["delta", "message", "exec.result"]);
+    // and the suite below proves the two halves agree. Since D1 the
+    // consumed list IS the wire's payload surface — the reverse of the
+    // M4-2 pin, which asserted none of these names could be emitted.
+    // `tool_call` is an ITEM kind, not an event, and is absent here
+    // because no event carries it in a form the parser renders.
+    assert.deepEqual(
+      [...EXEC_INTERFACE.consumedEvents].sort(),
+      [
+        "exec.completed",
+        "item.completed",
+        "item.started",
+        "item.updated",
+        "turn.completed",
+        "turn.failed",
+      ],
+    );
+    assert.equal(
+      [...EXEC_INTERFACE.consumedEvents].some((t) => EXEC_INTERFACE.itemKinds.includes(t)),
+      false,
+      "an item kind was listed as a consumed EVENT — items travel inside the item.* events",
+    );
     for (const type of EXEC_INTERFACE.consumedEvents) {
       assert.equal(
         EXEC_INTERFACE.streamEvents.includes(type),
-        false,
-        `${type} is consumed but is not an ExecEvent type — the KNOWN DEBT is gone, re-audit the reason`,
+        true,
+        `${type} is consumed but is not an ExecEvent type — the parser reads a name the wire cannot emit`,
       );
     }
     // And the permission half: `ask` is a TUI/ACP policy, so there is no
diff --git a/packages/webui/test/lib/engine/capability-snapshot.test.js b/packages/webui/test/lib/engine/capability-snapshot.test.js
index 5d277e61..956ba116 100644
--- a/packages/webui/test/lib/engine/capability-snapshot.test.js
+++ b/packages/webui/test/lib/engine/capability-snapshot.test.js
@@ -1093,41 +1093,70 @@ describe("M4-2 exec interface — the transcribed table matches the real sources
     assert.deepEqual(registered, [...EXEC_INTERFACE.processSignals].sort());
   });
 
-  // The direction that protects the declaration, and the finding it
-  // records. `mcode exec --output-format stream-json` writes exactly
-  // what `ExecEventProjector` produces — `output.ts:34-36` refuses the
-  // format outright with no projector, and `runner.ts:218-232` always
-  // supplies one — so the wire carries `streamEvents` and nothing else.
-  // The names webui's `collectExecResult` branches on are the
-  // SUPERVISOR'S INTERNAL stream-event names, and the intersection with
-  // the wire is empty.
+  // The direction that protects the declaration, INVERTED by D1.
   //
-  // That is a real mismatch in the exec data plane, not a test artifact.
-  // It is pinned as a KNOWN DEBT rather than hidden, and this assertion
-  // is what makes it visible: if the two families ever start overlapping
-  // — because tui emits both, or because webui is fixed to parse the
-  // projected names — the intersection becomes non-empty and this goes
-  // red with a message that says which side moved.
-  test("the exec parser's branch names and the wire's event names do not overlap", async () => {
+  // M4-2 pinned the opposite: `collectExecResult`'s branch names
+  // (`delta`, `message`, `exec.result` — the supervisor's internal
+  // `TuiStreamEvent` names) and the wire's event names had an EMPTY
+  // intersection, which is why the exec transport's streaming data plane
+  // was dead. D1 fixed the consumer to the wire, and this test now pins
+  // the fixed state: the parser's dispatch arms must be a SUBSET of what
+  // the stream-json line can carry, and together with `baseOnlyEvents`
+  // they must account for the whole `ExecEvent` union.
+  //
+  // Three assertions, each aimed at a specific way this can rot again:
+  //   1. the parser's arms and `consumedEvents` are the same set (the
+  //      declaration cannot claim a consumption the parser does not make,
+  //      or the reverse);
+  //   2. every consumed name is one the wire can emit — the M4-2 pin,
+  //      flipped from "must not overlap" to "must overlap", so a
+  //      supervisor-internal name coming back is red;
+  //   3. the un-consumed complement is exactly `baseOnlyEvents`, so
+  //      dropping `turn.failed` (or any payload-bearing type) from the
+  //      parser without recording it is red.
+  test("the exec parser dispatches on the wire's event names, and the table says so", async () => {
     const { readFileSync: read } = await import("node:fs");
     const src = read(
       fileURLToPath(new URL("../../../server/lib/mcode-exec.js", import.meta.url)),
       "utf8",
     );
+    // The parser is a `switch (m.type)` over the projected `ExecEvent`
+    // union, so the arms are `case "<name>":`. Matching the arm label —
+    // not any quoted string in the file — is what keeps prose and
+    // comment text from being counted as consumption.
     const consumed = [
-      ...new Set([...src.matchAll(/m\.type === "([^"]+)"/g)].map((m) => m[1])),
+      ...new Set([...src.matchAll(/^\s*case "([^"]+)":$/gm)].map((m) => m[1])),
     ].sort();
     assert.deepEqual(
       consumed,
       [...EXEC_INTERFACE.consumedEvents].sort(),
-      "the branches in collectExecResult and EXEC_INTERFACE.consumedEvents have drifted",
+      "the dispatch arms in collectExecResult and EXEC_INTERFACE.consumedEvents have drifted",
     );
-    const overlap = consumed.filter((type) => EXEC_INTERFACE.streamEvents.includes(type));
+    const notOnTheWire = consumed.filter((type) => !EXEC_INTERFACE.streamEvents.includes(type));
     assert.deepEqual(
-      overlap,
+      notOnTheWire,
       [],
-      "exec parser branch names now overlap the wire event names — one of the two sides moved, " +
-        "so EXEC_INTERFACE.consumedEvents and the toolSkillInvocation / usageStats reasons must be re-audited",
+      "collectExecResult dispatches on " +
+        notOnTheWire.join(", ") +
+        ", which the stream-json wire can never emit — a supervisor-internal name has come back",
+    );
+    // The complement is pinned rather than derived: `streamEvents` and
+    // `consumedEvents` are both frozen, so a NEW event type on the tui
+    // side is caught by the union test above; this one catches a payload
+    // type quietly ceasing to be consumed.
+    const unconsumed = EXEC_INTERFACE.streamEvents
+      .filter((type) => !EXEC_INTERFACE.consumedEvents.includes(type))
+      .sort();
+    assert.deepEqual(
+      unconsumed,
+      [...EXEC_INTERFACE.baseOnlyEvents].sort(),
+      "the events collectExecResult does not dispatch on are no longer exactly the base-only ones — " +
+        "a payload-bearing type stopped being consumed, or a base-only type started being listed as consumed",
+    );
+    assert.deepEqual(
+      [...new Set([...EXEC_INTERFACE.consumedEvents, ...EXEC_INTERFACE.baseOnlyEvents])].sort(),
+      [...EXEC_INTERFACE.streamEvents].sort(),
+      "consumedEvents and baseOnlyEvents must partition the ExecEvent union",
     );
   });
 
diff --git a/packages/webui/test/lib/engine/session-context-actions.test.js b/packages/webui/test/lib/engine/session-context-actions.test.js
new file mode 100644
index 00000000..52ebbd4e
--- /dev/null
+++ b/packages/webui/test/lib/engine/session-context-actions.test.js
@@ -0,0 +1,814 @@
+// webui/test/lib/engine/session-context-actions.test.js
+//
+// The session right-click action family (placeholder batch PB-1) — the
+// gate, the three-state host handling, and the pure derivations.
+//
+// What is NOT here, and why. Every test in this file drives the facade
+// through an INJECTED host (`deps.getHost`), so no runtime boots and no
+// tmp directory is needed. The real-host evidence — that
+// `host.cliService.archiveSession` / `forkSession` /
+// `getSessionForkOptions` and `host.services.pinService.pinSession` are
+// really there and really callable — belongs in
+// `test/server/session-context-actions-host.test.js`, which boots one
+// host, for the same reason `host-services-window.test.js` exists next
+// door to `host-services.test.js`.
+//
+// The "改坏必红" discipline. Every assertion below is about what the
+// module DOES or what it NAMES, never a restatement of its own
+// implementation. The seven mutations at the bottom each turn at least
+// one of them red, and each names the specific test that catches it —
+// the point being that a mutation going undetected is a gap in the
+// suite, not an accident of which test happened to run.
+
+import { test, describe } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import {
+  SESSION_CONTEXT_ACTION_ENDPOINTS,
+  SESSION_CONTEXT_ACTION_ROUTES,
+  applyEngineSessionArchive,
+  applyEngineSessionFork,
+  applyEngineSessionPin,
+  applyPinnedSessionOverlay,
+  assertSessionContextActionCapability,
+  buildForkRequest,
+  parseArchiveRequestBody,
+  parsePinRequestBody,
+  projectForkOptions,
+  projectPinnedSessionIds,
+  readEnginePinnedSessionOrder,
+  readEngineSessionForkOptions,
+} from "../../../server/engine/session-context-actions.js";
+
+const packageDir = join(import.meta.dirname, "..", "..", "..");
+const serverDir = join(packageDir, "server");
+
+/** A host whose cliService records what it was asked and answers `reply`. */
+function fakeHost(options = {}) {
+  const calls = [];
+  const cliService = {};
+  for (const name of ["archiveSession", "getSessionForkOptions", "forkSession"]) {
+    if (options.omit === name) continue;
+    cliService[name] = async (req) => {
+      calls.push({ method: name, req });
+      if (options.throwOn === name) throw new Error(`${name} blew up`);
+      return options.reply;
+    };
+  }
+  const host = { cliService };
+  if (options.services !== undefined) host.services = options.services;
+  else {
+    host.services = {
+      pinService: {
+        async pinSession(id, pinned) {
+          calls.push({ method: "pinSession", req: { id, pinned } });
+          if (options.throwOn === "pinSession") throw new Error("pinSession blew up");
+          return options.reply;
+        },
+        async getOrder() {
+          calls.push({ method: "getOrder" });
+          return options.reply;
+        },
+      },
+    };
+  }
+  return { host, calls };
+}
+
+const asHost = (h) => ({ getHost: async () => h });
+
+/** Strip comments — this file's prose legitimately names the guarded code. */
+const codeOf = (source) =>
+  source
+    .replace(/\/\*[\s\S]*?\*\//g, "")
+    .split("\n")
+    .map((line) => line.replace(/^\s*\/\/.*$/, ""))
+    .join("\n");
+
+// --- 1. the declaration table ----------------------------------------------
+
+describe("SESSION_CONTEXT_ACTION_ENDPOINTS — the declaration", () => {
+  test("covers exactly the four menu actions, and nothing else", () => {
+    // The four rows are the four endpoints `app.js` registers. A fifth row
+    // here without a route would be an action the server can perform and
+    // the user cannot reach; a route without a row would 400 on its own
+    // gate with `unknown_session_context_action_endpoint`.
+    assert.deepEqual(
+      [...SESSION_CONTEXT_ACTION_ROUTES].sort(),
+      [
+        "GET /api/sessions/:id/fork-options",
+        "POST /api/sessions/:id/archive",
+        "POST /api/sessions/:id/fork",
+        "POST /api/sessions/:id/pin",
+      ],
+    );
+  });
+
+  test("the three cliService rows declare the exact engine sub-items they call", () => {
+    // These names are the CONTRACT with `local-runtime-v2.capabilities.js`:
+    // `assertEngineCapability` throws 501 when a provider lists the sub-item
+    // in `missing`. Renaming one here without renaming it there would turn a
+    // working endpoint into a silent pass-through, because a `full` key
+    // passes any sub-item the gate is handed.
+    assert.equal(SESSION_CONTEXT_ACTION_ENDPOINTS["POST /api/sessions/:id/archive"].subItem, "archiveSession");
+    assert.equal(SESSION_CONTEXT_ACTION_ENDPOINTS["GET /api/sessions/:id/fork-options"].subItem, "getSessionForkOptions");
+    assert.equal(SESSION_CONTEXT_ACTION_ENDPOINTS["POST /api/sessions/:id/fork"].subItem, "forkSession");
+  });
+
+  test("pin is gated on the host-services window, not on a capability key", () => {
+    // The distinction is the design, not an accident. `pinSession` is on
+    // `host.services.pinService`, not on `cliService`, and there is no
+    // `ENGINE_CAPABILITY_KEYS` entry for it — a 15th audited matrix key for
+    // one method would restate three provider declarations. The row must
+    // therefore say so, and `capability` must be `null` so no future edit
+    // can quietly attach a key that does not describe where the method is.
+    const pin = SESSION_CONTEXT_ACTION_ENDPOINTS["POST /api/sessions/:id/pin"];
+    assert.equal(pin.gate, "host-services");
+    assert.equal(pin.capability, null);
+    assert.equal(pin.member, "services.pinService");
+  });
+
+  test("every row names a member this module can actually resolve", () => {
+    // `resolveContextActionMember` branches on `member === "cliService"`
+    // and otherwise walks a dotted path. A third spelling would fall into
+    // the dotted-path branch and resolve to `undefined` at dispatch time —
+    // a 501 with no test pointing at the typo.
+    for (const [endpoint, row] of Object.entries(SESSION_CONTEXT_ACTION_ENDPOINTS)) {
+      assert.ok(
+        row.member === "cliService" || row.member === "services.pinService",
+        `${endpoint} has member ${row.member}, which the resolver does not know`,
+      );
+      assert.equal(typeof row.method, "string");
+      assert.notEqual(row.method, "");
+    }
+  });
+});
+
+// --- 2. the gate -----------------------------------------------------------
+
+describe("assertSessionContextActionCapability — the gate", () => {
+  test("a typo in the endpoint key is a plain Error, never a 501", () => {
+    // A caller-confusion error must not be dressed as an engine
+    // limitation: `app.js#invokeHandler` maps
+    // `EngineCapabilityNotSupportedError` to 501, and a webui typo
+    // answered 501 would point an operator at the provider for a bug in
+    // webui's own code.
+    assert.throws(
+      () => assertSessionContextActionCapability("POST /api/sessions/:id/nope", "runtime"),
+      (err) => {
+        assert.ok(!(err.name === "EngineCapabilityNotSupportedError"));
+        assert.equal(err.code, "unknown_session_context_action_endpoint");
+        // The message must LIST the real keys — a caller who typos needs
+        // to be told what the right spelling is, not just that it is wrong.
+        assert.match(err.message, /archive/);
+        return true;
+      },
+    );
+  });
+
+  test("an unregistered transport proceeds rather than refusing", () => {
+    // `acp` has no registered provider. M4-3a established that this means
+    // "no provider claims this transport", NOT "cannot do it": the work
+    // still runs on the process-local host reached through
+    // `getEngineCatalogueHost()`. Collapsing the two would delete a
+    // working endpoint on a statement about nothing.
+    const gate = assertSessionContextActionCapability("POST /api/sessions/:id/archive", "acp");
+    assert.equal(gate.gate, "unregistered-transport");
+    assert.equal(gate.provider, null);
+  });
+
+  test("the runtime transport's provider is resolved and checked", () => {
+    const gate = assertSessionContextActionCapability("POST /api/sessions/:id/archive", "runtime");
+    assert.equal(gate.gate, "checked");
+    assert.equal(gate.provider, "local-runtime-v2");
+    assert.equal(gate.capability, "sessionCrud");
+  });
+
+  test("the pin row never consults the provider, under any transport", () => {
+    // If this row ever grew a `capability`, the gate would start answering
+    // from a static declaration while the method actually lives on a member
+    // the declaration does not describe — the exact "gated on a statement
+    // about something it does not depend on" that `session-writes.js`
+    // declined for rename.
+    for (const transport of ["runtime", "acp", "tui"]) {
+      const gate = assertSessionContextActionCapability("POST /api/sessions/:id/pin", transport);
+      assert.equal(gate.gate, "host-services");
+      assert.equal(gate.capability, null);
+    }
+  });
+});
+
+// --- 3. the three-state host resolution ------------------------------------
+
+describe("applyEngineSessionArchive — the three cliService answers", () => {
+  test("no host is 503, not a success and not a 501", async () => {
+    // 503 vs 501 is the operator-facing distinction this module exists to
+    // keep: 501 means "this transport cannot", 503 means "the process is
+    // not running its runtime", and they have different fixes.
+    const result = await applyEngineSessionArchive({ id: "mvs_1", archived: true, transport: "acp", deps: asHost(null) });
+    assert.equal(result.ok, false);
+    assert.equal(result.status, 503);
+    assert.equal(result.code, "engine_host_unavailable");
+  });
+
+  test("a host with no archiveSession is 501 with the member named", async () => {
+    const { host } = fakeHost({ omit: "archiveSession" });
+    const result = await applyEngineSessionArchive({ id: "mvs_1", archived: true, transport: "acp", deps: asHost(host) });
+    assert.equal(result.status, 501);
+    assert.equal(result.code, "engine_member_unavailable");
+    // The error text must name the METHOD: an operator reading a 501 needs
+    // to know which method is missing, not that "something" is.
+    assert.match(result.error, /cliService\.archiveSession/);
+  });
+
+  test("a throwing engine becomes 502 and never an ok payload", async () => {
+    const { host } = fakeHost({ throwOn: "archiveSession" });
+    const result = await applyEngineSessionArchive({ id: "mvs_1", archived: true, transport: "acp", deps: asHost(host) });
+    assert.equal(result.ok, false);
+    assert.equal(result.status, 502);
+    assert.equal(result.code, "engine_archive_failed");
+    assert.equal(result.payload, undefined);
+  });
+
+  test("a successful archive sends the id and the direction to the engine", async () => {
+    // The direction is the whole point of one endpoint serving both: a
+    // request that always sent `archived: true` would make PB-2's
+    // "unarchive" button archive the row it was meant to restore.
+    const { host, calls } = fakeHost({ reply: { success: true } });
+    const result = await applyEngineSessionArchive({ id: "mvs_abc", archived: false, transport: "acp", deps: asHost(host) });
+    assert.equal(result.ok, true);
+    assert.equal(result.archived, false);
+    assert.equal(result.payload.archived, false);
+    assert.equal(calls.length, 1);
+    assert.equal(calls[0].req.id, "mvs_abc");
+    assert.equal(calls[0].req.archived, false);
+  });
+});
+
+describe("applyEngineSessionPin — the three PB-8 states", () => {
+  test("null services is 503: there is no runtime", async () => {
+    const { host } = fakeHost({ services: null });
+    const result = await applyEngineSessionPin({ id: "mvs_1", pinned: true, transport: "acp", deps: asHost(host) });
+    assert.equal(result.status, 503);
+    assert.equal(result.code, "engine_host_unavailable");
+  });
+
+  test("undefined services is 501: a host with no owner graph", async () => {
+    // The answer PB-8's header exists to keep distinct, and it is one `??`
+    // away from collapsing into the row above. A caller that mapped both to
+    // "unavailable" would make a boot failure look like a transport that
+    // simply has no V2 slice.
+    const { host } = fakeHost({ services: undefined });
+    delete host.services;
+    const result = await applyEngineSessionPin({ id: "mvs_1", pinned: true, transport: "acp", deps: asHost(host) });
+    assert.equal(result.status, 501);
+    assert.equal(result.code, "engine_services_unavailable");
+  });
+
+  test("an owner graph without pinService is 501 and names the member", async () => {
+    const { host } = fakeHost({ services: {} });
+    const result = await applyEngineSessionPin({ id: "mvs_1", pinned: true, transport: "acp", deps: asHost(host) });
+    assert.equal(result.status, 501);
+    assert.equal(result.code, "engine_member_unavailable");
+    assert.match(result.error, /services\.pinService\.pinSession/);
+  });
+
+  test("no absence answer ever produces an ok payload", async () => {
+    // The fake-success shape: a pin that "succeeded" without writing
+    // anything tells the user their session is pinned and it is not.
+    for (const services of [null, undefined, {}, { pinService: {} }]) {
+      const host = { cliService: {}, services };
+      if (services === undefined) delete host.services;
+      const result = await applyEngineSessionPin({ id: "mvs_1", pinned: true, transport: "acp", deps: asHost(host) });
+      assert.equal(result.ok, false);
+      assert.equal(result.payload, undefined);
+    }
+  });
+
+  test("a successful pin passes the id and the boolean positionally", async () => {
+    // `PinService#pinSession(sessionId, pinned, insertIndex?)` takes them
+    // positionally and branches on the second. A call that passed an
+    // options object would pin nothing and report success.
+    const { host, calls } = fakeHost({
+      reply: { items: [{ ref: { type: "session", id: "mvs_abc" } }] },
+    });
+    const result = await applyEngineSessionPin({ id: "mvs_abc", pinned: true, transport: "acp", deps: asHost(host) });
+    assert.equal(result.ok, true);
+    assert.deepEqual(calls[0].req, { id: "mvs_abc", pinned: true });
+    assert.deepEqual(result.pinnedIds, ["mvs_abc"]);
+  });
+
+  test("a throwing pinService is 502", async () => {
+    const { host } = fakeHost({ throwOn: "pinSession" });
+    const result = await applyEngineSessionPin({ id: "mvs_1", pinned: true, transport: "acp", deps: asHost(host) });
+    assert.equal(result.status, 502);
+    assert.equal(result.code, "engine_pin_failed");
+  });
+});
+
+// --- 4. fork ---------------------------------------------------------------
+
+describe("applyEngineSessionFork", () => {
+  test("forces createIsolatedWorktree false and useSuggestedTitle true", async () => {
+    // `createIsolatedWorktree: true` would create a worktree the UI never
+    // asked the user about — the worktree variant of the menu has no
+    // desktop reference and stays an honest placeholder, so the reachable
+    // action must be unable to reach it. `useSuggestedTitle: true` keeps
+    // the title contract single-sourced on the engine's suggestion, which
+    // the dialog SHOWS before the user commits.
+    const { host, calls } = fakeHost({ reply: { session: { id: "mvs_new" } } });
+    await applyEngineSessionFork({ id: "mvs_src", clientRequestId: "req-1", transport: "acp", deps: asHost(host) });
+    assert.equal(calls[0].req.createIsolatedWorktree, false);
+    assert.equal(calls[0].req.useSuggestedTitle, true);
+  });
+
+  test("forwards the fork point only when one was named", async () => {
+    // An absent fork point means "duplicate the whole conversation", which
+    // is what the menu item means. Sending `assistantMessageId: undefined`
+    // explicitly would be the same on the wire but would make a test that
+    // asserts on the key's presence wrong, and the key's presence is the
+    // difference between "no point" and "an empty point".
+    const { host, calls } = fakeHost({ reply: { session: { id: "mvs_new" } } });
+    await applyEngineSessionFork({ id: "mvs_src", clientRequestId: "r", transport: "acp", deps: asHost(host) });
+    assert.ok(!("assistantMessageId" in calls[0].req));
+    const second = fakeHost({ reply: { session: { id: "mvs_new2" } } });
+    await applyEngineSessionFork({
+      id: "mvs_src",
+      clientRequestId: "r2",
+      assistantMessageId: "msg_1",
+      transport: "acp",
+      deps: asHost(second.host),
+    });
+    assert.equal(second.calls[0].req.assistantMessageId, "msg_1");
+  });
+
+  test("a fork that reported no session is a failure, not a success with a null id", async () => {
+    // `ForkSessionResult.session?` is optional. Optionality there is about
+    // a session with no view shape — not about a fork that did not happen.
+    // Reporting success with a null id would leave the user looking at a
+    // list that grew by one row with no way to name it.
+    const { host } = fakeHost({ reply: {} });
+    const result = await applyEngineSessionFork({ id: "mvs_src", clientRequestId: "r", transport: "acp", deps: asHost(host) });
+    assert.equal(result.ok, false);
+    assert.equal(result.code, "engine_fork_no_session");
+    assert.equal(result.status, 502);
+  });
+
+  test("returns the new session's id so the client can switch to it", async () => {
+    const { host } = fakeHost({ reply: { session: { id: "mvs_forked" }, forkOriginMessageId: "msg_9" } });
+    const result = await applyEngineSessionFork({ id: "mvs_src", clientRequestId: "r", transport: "acp", deps: asHost(host) });
+    assert.equal(result.sessionId, "mvs_forked");
+    assert.equal(result.payload.forkOriginMessageId, "msg_9");
+    assert.equal(result.payload.sourceId, "mvs_src");
+  });
+});
+
+describe("readEngineSessionForkOptions", () => {
+  test("projects the engine's answer into the dialog's shape", async () => {
+    const { host } = fakeHost({
+      reply: {
+        canFork: true,
+        suggestedTitle: "Copy of X",
+        nextForkOrdinal: 2,
+        sourceTitle: "X",
+        worktreeVisible: true,
+        worktreeEligible: false,
+        worktreeUnavailableReason: "no git",
+      },
+    });
+    const result = await readEngineSessionForkOptions({ id: "mvs_x", transport: "acp", deps: asHost(host) });
+    assert.equal(result.ok, true);
+    assert.equal(result.options.canFork, true);
+    assert.equal(result.options.suggestedTitle, "Copy of X");
+    // The worktree triple travels UNTOUCHED. Nothing in this batch reads
+    // it — the batch that unblocks the worktree variant must not have to
+    // re-derive it, and a narrowing that dropped it would make that batch
+    // change this file's projection.
+    assert.deepEqual(result.options.worktree, {
+      visible: true,
+      eligible: false,
+      unavailableReason: "no git",
+    });
+  });
+
+  test("a read failure is propagated, not turned into canFork:false", async () => {
+    // A default-shaped options object would put "canFork: false" on screen
+    // as if the engine had REFUSED a fork it was never asked about. The
+    // dialog has to be able to tell "the engine said no" from "we could
+    // not ask", and only the propagated failure carries that.
+    const { host } = fakeHost({ throwOn: "getSessionForkOptions" });
+    const result = await readEngineSessionForkOptions({ id: "mvs_x", transport: "acp", deps: asHost(host) });
+    assert.equal(result.ok, false);
+    assert.equal(result.options, undefined);
+    assert.equal(result.status, 502);
+  });
+});
+
+// --- 5. the pure derivations -----------------------------------------------
+
+describe("parseArchiveRequestBody", () => {
+  test("anything that is not literally false archives", () => {
+    // `lifecycle-application.ts#archiveSession` reads
+    // `req.archived !== false`, so a validator that disagreed about any
+    // other value would make the HTTP layer and the engine answer
+    // differently about the same request.
+    for (const body of [{}, { archived: undefined }, { archived: null }, { archived: true }, { archived: 0 }, { archived: "yes" }]) {
+      assert.equal(parseArchiveRequestBody(body).archived, true, JSON.stringify(body));
+    }
+  });
+
+  test("only literal false unarchives", () => {
+    assert.equal(parseArchiveRequestBody({ archived: false }).archived, false);
+    // A `null` is not `false`, so it archives. That is the engine's rule,
+    // and the point of the test is that this module does not "fix" it.
+    assert.equal(parseArchiveRequestBody({ archived: null }).archived, true);
+  });
+
+  test("a non-object body is treated as absent, not as an error", () => {
+    // `readJson` answers `{}` for an empty body, but a caller that passed a
+    // string through would get a crash without this, and the default
+    // direction (archive) is the one the endpoint name implies.
+    for (const body of [null, undefined, "x", 42, []]) {
+      assert.equal(parseArchiveRequestBody(body).ok, true);
+    }
+  });
+});
+
+describe("parsePinRequestBody", () => {
+  test("requires a real boolean, in BOTH directions", () => {
+    // Unlike archive, the flag is a required positional on
+    // `pinSession(sessionId, pinned, …)`. Defaulting it would move the row
+    // in a direction the user did not choose, so the "unpin" direction is
+    // pinned by its own test rather than left to an accident of `=== true`.
+    for (const body of [{}, { pinned: undefined }, { pinned: null }, { pinned: 1 }, { pinned: "true" }, null, "x"]) {
+      const parsed = parsePinRequestBody(body);
+      assert.equal(parsed.ok, false, JSON.stringify(body));
+    }
+    assert.deepEqual(parsePinRequestBody({ pinned: true }), { ok: true, pinned: true });
+    assert.deepEqual(parsePinRequestBody({ pinned: false }), { ok: true, pinned: false });
+  });
+});
+
+describe("buildForkRequest", () => {
+  test("the forced fields cannot be overridden by the caller", () => {
+    // Both are FORCED by this function rather than defaulted, so a future
+    // edit that spreads the caller's options in would have to delete the
+    // explicit assignment above it to reintroduce the risk.
+    const request = buildForkRequest({
+      id: "mvs_1",
+      clientRequestId: "r",
+      assistantMessageId: "msg",
+      title: "hijacked",
+      useSuggestedTitle: false,
+      createIsolatedWorktree: true,
+    });
+    assert.equal(request.useSuggestedTitle, true);
+    assert.equal(request.createIsolatedWorktree, false);
+    assert.equal(request.id, "mvs_1");
+    assert.equal(request.clientRequestId, "r");
+    // A caller-supplied `title` is DROPPED, not forwarded: the endpoint
+    // has one title contract and it is the engine's suggestion.
+    assert.equal(request.title, undefined);
+  });
+});
+
+describe("projectForkOptions", () => {
+  test("every field is defined for an empty input", () => {
+    // Total on purpose: the dialog renders each field, and a missing one
+    // would put `undefined` in the DOM rather than an empty row.
+    const projected = projectForkOptions(undefined);
+    assert.equal(projected.canFork, false);
+    assert.equal(projected.unavailableReason, null);
+    assert.equal(projected.suggestedTitle, null);
+    assert.equal(projected.nextForkOrdinal, null);
+    assert.equal(projected.sourceTitle, null);
+    assert.deepEqual(projected.worktree, { visible: false, eligible: false, unavailableReason: null });
+  });
+
+  test("canFork is a strict true, not truthiness", () => {
+    // `canFork: "false"` from a provider that stringified its boolean must
+    // not read as an affirmative on a WRITE-gating field.
+    assert.equal(projectForkOptions({ canFork: "true" }).canFork, false);
+    assert.equal(projectForkOptions({ canFork: 1 }).canFork, false);
+    assert.equal(projectForkOptions({ canFork: true }).canFork, true);
+  });
+});
+
+describe("projectPinnedSessionIds", () => {
+  test("keeps only session refs, in the engine's order", () => {
+    // Agents and projects are ordered in a different surface this batch
+    // does not render; passing them through would put ids into the sidebar
+    // overlay that name nothing the tree contains.
+    const ids = projectPinnedSessionIds({
+      items: [
+        { ref: { type: "project", id: "p1" } },
+        { ref: { type: "session", id: "mvs_b" } },
+        { ref: { type: "agent", id: "reviewer" } },
+        { ref: { type: "session", id: "mvs_a" } },
+      ],
+    });
+    assert.deepEqual(ids, ["mvs_b", "mvs_a"]);
+  });
+
+  test("accepts a bare PinItem[] as well as a PinMutation", () => {
+    // `pinSession` returns the mutation and `getOrder()` the array; both
+    // carry `items`, and the overlay only ever needs the ids. Accepting
+    // both means the overlay never has to know which caller it is serving.
+    assert.deepEqual(projectPinnedSessionIds([{ ref: { type: "session", id: "mvs_a" } }]), ["mvs_a"]);
+    assert.deepEqual(projectPinnedSessionIds({ items: [{ ref: { type: "session", id: "mvs_a" } }] }), ["mvs_a"]);
+  });
+
+  test("junk in is an empty list, never a throw", () => {
+    for (const value of [null, undefined, {}, 42, { items: null }, { items: [null, {}, { ref: {} }] }]) {
+      assert.deepEqual(projectPinnedSessionIds(value), [], JSON.stringify(value));
+    }
+  });
+});
+
+// --- 6. the sidebar overlay -------------------------------------------------
+
+describe("applyPinnedSessionOverlay", () => {
+  const tree = (ids) => ({
+    ok: true,
+    projects: [
+      {
+        key: "p",
+        name: "p",
+        directories: [{ path: "/w", name: "w", latestAt: 0, sessions: ids.map((id) => ({ id, title: id, children: [] })) }],
+      },
+    ],
+  });
+  const order = (t) => t.projects[0].directories[0].sessions.map((s) => s.id);
+
+  test("an empty pin set leaves the order byte-identical", () => {
+    // The regression this guards: a comparator that reordered equal keys
+    // would shuffle every unpinned sidebar on every read. With no pins at
+    // all, the output must be the input.
+    const input = tree(["mvs_1", "mvs_2", "mvs_3"]);
+    assert.deepEqual(order(applyPinnedSessionOverlay(input, [])), ["mvs_1", "mvs_2", "mvs_3"]);
+  });
+
+  test("pinned sessions move to the top, in the engine's order", () => {
+    // By the engine's order, not by `updatedAt` — the engine persists that
+    // order under `pinned-items-order`, and a webui-side re-sort would
+    // fight it on the next write.
+    const out = applyPinnedSessionOverlay(tree(["mvs_1", "mvs_2", "mvs_3"]), ["mvs_3", "mvs_1"]);
+    assert.deepEqual(order(out), ["mvs_3", "mvs_1", "mvs_2"]);
+  });
+
+  test("marks EVERY session, so the client reads a boolean and never a missing field", () => {
+    // A field that appears only on pinned rows is a field the client has
+    // to guard, and the guard is where the "undefined means false" bug
+    // lives.
+    for (const session of applyPinnedSessionOverlay(tree(["mvs_1", "mvs_2"]), ["mvs_1"]).projects[0].directories[0].sessions) {
+      assert.equal(typeof session.pinned, "boolean");
+    }
+  });
+
+  test("a pinned id the tree does not contain is ignored, and the tree still renders", () => {
+    // The two stores are read at different instants (KNOWN DEBT 3), so this
+    // is a normal occurrence, not an error. A pin written after the db scan
+    // must not cost the user their sidebar.
+    const out = applyPinnedSessionOverlay(tree(["mvs_1"]), ["mvs_absent"]);
+    assert.deepEqual(order(out), ["mvs_1"]);
+  });
+
+  test("does not mutate its input", () => {
+    const input = tree(["mvs_1", "mvs_2"]);
+    applyPinnedSessionOverlay(input, ["mvs_2"]);
+    assert.deepEqual(order(input), ["mvs_1", "mvs_2"]);
+    assert.equal(input.projects[0].directories[0].sessions[0].pinned, undefined);
+  });
+
+  test("a soft-failed tree payload passes through unchanged", () => {
+    // `handleSessionTree` answers `{ok:false, reason}` for a missing db,
+    // and it has no `projects` to mark. Returning the payload as-is is one
+    // fewer branch to get wrong than guarding the call site.
+    const soft = { ok: false, reason: "mcode_db_not_found" };
+    assert.equal(applyPinnedSessionOverlay(soft, ["mvs_1"]), soft);
+  });
+});
+
+describe("readEnginePinnedSessionOrder — the one soft gate", () => {
+  test("degrades to an empty list with a reason, on every absence", async () => {
+    // The contrast with the four endpoints is the point: those MUTATE and a
+    // mutation that cannot confirm its write must not claim success; this
+    // one only reads an ordering, and failing the whole tree over it would
+    // be a worse failure than not showing pins. What it must NOT do is
+    // fail silently — `degraded`/`reason` is how a caller tells "nothing is
+    // pinned" from "we could not ask".
+    const cases = [
+      [null, "engine_host_unavailable"],
+      [{ cliService: {} }, "engine_services_unavailable"],
+      [{ cliService: {}, services: null }, "engine_host_unavailable"],
+      [{ cliService: {}, services: {} }, "pin_service_unavailable"],
+    ];
+    for (const [host, reason] of cases) {
+      const out = await readEnginePinnedSessionOrder({ getHost: async () => host });
+      assert.deepEqual(out.pinnedIds, [], JSON.stringify(host));
+      assert.equal(out.degraded, true);
+      assert.equal(out.reason, reason);
+    }
+  });
+
+  test("a throwing host getter degrades rather than propagating", async () => {
+    const out = await readEnginePinnedSessionOrder({
+      getHost: async () => {
+        throw new Error("boot failed");
+      },
+    });
+    assert.deepEqual(out, { pinnedIds: [], degraded: true, reason: "engine_host_unavailable" });
+  });
+
+  test("a live pinService answers without degrading", async () => {
+    const { host } = fakeHost({ reply: [{ ref: { type: "session", id: "mvs_a" } }] });
+    const out = await readEnginePinnedSessionOrder({ getHost: async () => host });
+    assert.deepEqual(out, { pinnedIds: ["mvs_a"], degraded: false, reason: null });
+  });
+
+  test("the default getter is the NON-BOOTING peek, not the booting one", async () => {
+    // This is the assertion that keeps a sidebar's first paint off the
+    // runtime-boot path. `getEngineCatalogueHost()` constructs the whole
+    // runtime on its first call (seconds — the `test/server/` real-host
+    // suites measure ~5 s cold), so a READ that reached for it would turn
+    // the first `GET /api/session-tree` of a fresh process into a runtime
+    // boot, and the cost would land on whoever painted the page first
+    // while looking like an ordinary slow request. The symptom when this
+    // regressed was not a pin assertion at all: a 10 s `/api/state`
+    // timeout in the router-boot integration suite under the `runtime`
+    // transport.
+    //
+    // Asserted on the SOURCE rather than by calling the default, because
+    // calling it would boot a real runtime into this suite's process —
+    // which is precisely what the rule forbids.
+    const code = codeOf(readFileSync(join(serverDir, "engine/session-context-actions.js"), "utf8"));
+    const start = code.indexOf("export async function readEnginePinnedSessionOrder");
+    assert.notEqual(start, -1, "readEnginePinnedSessionOrder is missing");
+    const body = code.slice(start, code.indexOf("\n}", start));
+    assert.ok(
+      body.includes("peekEngineCatalogueHost"),
+      "the pin READ must reach the host through the non-booting peek",
+    );
+    assert.ok(
+      !body.includes("getEngineCatalogueHost"),
+      "the pin READ must not reach the booting getter — that turns the first sidebar read into a runtime boot",
+    );
+  });
+
+  test("the four WRITE actions may boot, which is why the split is a rule", async () => {
+    // The complement of the assertion above. A write the user asked for
+    // may bring up what it needs — M4-3a's delete has always done exactly
+    // that — so the family is not "never boot", it is "only writes boot".
+    // Without this half, the fix above reads as a blanket caution and a
+    // later reader would apply it to the writes too, making every menu
+    // item wait on a boot it does not need.
+    const code = codeOf(readFileSync(join(serverDir, "engine/session-context-actions.js"), "utf8"));
+    for (const fn of [
+      "applyEngineSessionArchive",
+      "applyEngineSessionFork",
+      "applyEngineSessionPin",
+      "readEngineSessionForkOptions",
+    ]) {
+      const start = code.indexOf(`export async function ${fn}`);
+      assert.notEqual(start, -1, `${fn} is missing`);
+      const body = code.slice(start, start + 2000);
+      assert.ok(
+        body.includes("getEngineCatalogueHost") || body.includes("resolveContextActionMember"),
+        `${fn} must resolve the host through the booting getter or the shared resolver`,
+      );
+    }
+    // `peekCatalogueHost` exists at all, and returns rather than awaits —
+    // the shape that makes "no boot" checkable at the call site.
+    const acp = readFileSync(join(packageDir, "server/lib/acp-client.js"), "utf8");
+    assert.match(acp, /export function peekCatalogueHost\(\)/);
+    assert.ok(
+      !/export async function peekCatalogueHost/.test(acp),
+      "the peek must be synchronous — an async peek invites awaiting a boot",
+    );
+  });
+});
+
+// --- 7. source shape --------------------------------------------------------
+
+describe("source shape — the boot path and the wiring", () => {
+
+  const read = (rel) => readFileSync(join(serverDir, rel), "utf8");
+
+  test("the facade statically imports nothing that boots a runtime", () => {
+    // `app.js` loads `engine/index.js` at start, so a static import of the
+    // host or of a provider would put the whole `@mavis/*` TypeScript tree
+    // on the boot path — the regression M1 paid for once (209ms → 2700ms).
+    // `host-services.test.js` guards the same rule for the window; this
+    // file's own host access must obey it too.
+    const code = codeOf(read("engine/session-context-actions.js"));
+    for (const forbidden of ['from "./host.js"', 'from "./providers/', "from \"@mavis/", "from '@mavis/"]) {
+      assert.ok(!code.includes(forbidden), `static import of ${forbidden} would be on the boot path`);
+    }
+  });
+
+  test("the host getter is reached dynamically, and a real one exists", () => {
+    // Belt and braces on the rule above: the dynamic import is not
+    // optional, and it names the SAME getter every other facade uses
+    // rather than building a second runtime.
+    const code = codeOf(read("engine/session-context-actions.js"));
+    assert.ok(code.includes('await import("./host.js")'));
+    assert.ok(code.includes("getEngineCatalogueHost"));
+  });
+
+  test("all four endpoints are registered and owned", () => {
+    // Two lists that must not drift: `OWNED_ROUTES` is the ledger the
+    // router gate reads, and the `app.get/post` calls are the actual
+    // dispatch. A route registered but not owned is served and unaudited;
+    // an owned route with no registration is a 404 that reads as a
+    // capability that does not exist.
+    const app = read("app.js");
+    for (const [method, path] of [
+      ["post", "/api/sessions/:id/archive"],
+      ["post", "/api/sessions/:id/pin"],
+      ["get", "/api/sessions/:id/fork-options"],
+      ["post", "/api/sessions/:id/fork"],
+    ]) {
+      assert.ok(app.includes(`app.${method}("${path}"`), `${method.toUpperCase()} ${path} is not dispatched`);
+      assert.ok(app.includes(`"${method.toUpperCase()} ${path}"`), `${method.toUpperCase()} ${path} is not in OWNED_ROUTES`);
+    }
+  });
+
+  test("the route handlers resolve their id by SLICING, not by trusting the path", () => {
+    // `/api/sessions//archive` must 400, not be read as an empty session id
+    // and handed to the engine. The slice helper is what makes that true,
+    // and an id that reaches `archiveSession({id: ""})` would be a write
+    // against a session the caller did not name.
+    const code = codeOf(read("routes/sessions.js"));
+    assert.ok(code.includes("_contextActionSessionId"));
+    // Every one of the four must go through the helper rather than a
+    // hand-rolled slice, or the empty-id case only holds for the handler
+    // that was careful.
+    const uses = code.match(/_contextActionSessionId\(ctx\.pathname, "[a-z-]+"\)/g) ?? [];
+    assert.equal(uses.length, 4, `expected 4 handlers to use the id slicer, found ${uses.length}`);
+  });
+});
+
+// --- 8. the mutation table --------------------------------------------------
+//
+// Each row is a one-line break a plausible refactor could introduce, the
+// specific assertion above that turns red, and the reason that break
+// matters. They are recorded as tests rather than as a comment so that a
+// future edit which "fixes" one of them has to delete a test to do it
+// quietly, and the deletion shows in the diff.
+
+describe("mutation coverage — the seven ways to break this batch", () => {
+  const MUTATIONS = [
+    {
+      what: "collapse the three PB-8 states into one `if (!services)`",
+      breaks: "applyEngineSessionPin — undefined services is 501",
+      why: "a host with no owner graph would answer 503, making a transport limitation look like a boot failure",
+    },
+    {
+      what: "default `pinned` to true in parsePinRequestBody",
+      breaks: "parsePinRequestBody — requires a real boolean",
+      why: "an unpin request would PIN the row, the opposite of what the user clicked",
+    },
+    {
+      what: "let the caller override createIsolatedWorktree",
+      breaks: "applyEngineSessionFork — forces createIsolatedWorktree false",
+      why: "a reference-free worktree fork becomes reachable through a flag nobody set on purpose",
+    },
+    {
+      what: "sort the overlay by updatedAt instead of by pin rank",
+      breaks: "applyPinnedSessionOverlay — an empty pin set leaves the order byte-identical",
+      why: "equal keys get reordered, so every unpinned sidebar shuffles on every read",
+    },
+    {
+      what: "drop the `!== false` rule in parseArchiveRequestBody",
+      breaks: "parseArchiveRequestBody — anything that is not literally false archives",
+      why: "the HTTP layer and the engine would disagree about the same request body",
+    },
+    {
+      what: "treat a fork with no `session` as a success",
+      breaks: "applyEngineSessionFork — a fork that reported no session is a failure",
+      why: "the fake-success shape: a row appears with no id to switch to",
+    },
+    {
+      what: "narrow `worktree` out of projectForkOptions",
+      breaks: "readEngineSessionForkOptions — projects the engine's answer into the dialog's shape",
+      why: "the batch that unblocks the worktree menu item would have to re-derive three fields the engine already sent",
+    },
+  ];
+
+  test("every declared mutation names a real test in this file", () => {
+    // A mutation table that names nothing is a comment. This asserts the
+    // table is wired to the suite: each row must point at a `test(...)`
+    // title that actually exists, so renaming a test without updating the
+    // table turns this red.
+    const source = readFileSync(join(import.meta.dirname, "session-context-actions.test.js"), "utf8");
+    for (const mutation of MUTATIONS) {
+      assert.ok(
+        source.includes(mutation.breaks),
+        `mutation "${mutation.what}" names no assertion in this file (${mutation.breaks})`,
+      );
+      assert.ok(mutation.why.length > 20, `mutation "${mutation.what}" has no stated consequence`);
+    }
+  });
+});
diff --git a/packages/webui/test/lib/engine/session-tree-reads.test.js b/packages/webui/test/lib/engine/session-tree-reads.test.js
index 6e84ffe1..8edbac6c 100644
--- a/packages/webui/test/lib/engine/session-tree-reads.test.js
+++ b/packages/webui/test/lib/engine/session-tree-reads.test.js
@@ -678,11 +678,26 @@ describe("handleSessionTree — the route passes the facade payload through", ()
   // is load-bearing rather than decorative.
   let bust = 0;
 
-  test("a facade payload is written to the response byte-for-byte", async (t) => {
+  test("a facade payload is written to the response byte-for-byte, plus the pin overlay", async (t) => {
     // The payload is injected rather than produced, so this is about the
     // ROUTE's contract: it must not re-shape, re-count or re-derive
     // anything. The payload carries the exact key set the real tree
     // produces, `cached` included.
+    //
+    // PB-1 changed that contract in exactly one way, and the delta is
+    // asserted rather than waved at. `lib/session-tree.js` reads
+    // `local_runtime_sessions`, which has no pin column, so the route
+    // reads the engine's `PinService` order and lays it over the payload.
+    // Everything else — `cached`, `counts`, `generatedAt`, `truncated` —
+    // still passes through untouched, which is what this test is for.
+    //
+    // The pin read is MOCKED here, and mocked as DEGRADED, because that is
+    // the interesting case: the overlay must still be applied (every
+    // session gains `pinned: false`) and the response must still say the
+    // answer is unknown rather than empty. A route that skipped the
+    // overlay on a degraded read would leave the client reading a missing
+    // `pinned` field as `undefined`, which is the bug the always-write-
+    // the-boolean rule exists to prevent.
     const payload = {
       ok: true,
       generatedAt: 1750000000000,
@@ -738,6 +753,53 @@ describe("handleSessionTree — the route passes the facade payload through", ()
         }),
       },
     });
+    // PB-1: the pin overlay's engine read, answering DEGRADED. See the
+    // test's header for why the degraded case is the one worth pinning.
+    //
+    // `namedExports` REPLACES the module rather than merging into it, so
+    // every name `routes/sessions.js` imports from it has to appear here
+    // — the four action entry points and the two parsers are stubs that
+    // throw, because this test drives only `handleSessionTree` and their
+    // bodies are covered by the family suite. Omitting one is not a
+    // silent skip: the import throws at module instantiation, which is
+    // how a stale mock is caught instead of quietly passing.
+    t.mock.module(absPath("engine/session-context-actions.js"), {
+      namedExports: {
+        readEnginePinnedSessionOrder: async () => ({
+          pinnedIds: [],
+          degraded: true,
+          reason: "engine_host_unavailable",
+        }),
+        applyPinnedSessionOverlay: (tree, pinnedIds) => ({
+          ...tree,
+          projects: tree.projects.map((p) => ({
+            ...p,
+            directories: p.directories.map((d) => ({
+              ...d,
+              sessions: d.sessions.map((s) => ({ ...s, pinned: pinnedIds.includes(s.id) })),
+            })),
+          })),
+        }),
+        applyEngineSessionArchive: () => {
+          throw new Error("not exercised by this suite");
+        },
+        applyEngineSessionFork: () => {
+          throw new Error("not exercised by this suite");
+        },
+        applyEngineSessionPin: () => {
+          throw new Error("not exercised by this suite");
+        },
+        parseArchiveRequestBody: () => {
+          throw new Error("not exercised by this suite");
+        },
+        parsePinRequestBody: () => {
+          throw new Error("not exercised by this suite");
+        },
+        readEngineSessionForkOptions: () => {
+          throw new Error("not exercised by this suite");
+        },
+      },
+    });
     const sessionsRoute = await import(`${absPath("routes/sessions.js")}?bust=${bust++}`);
     const written = [];
     const res = {
@@ -748,7 +810,21 @@ describe("handleSessionTree — the route passes the facade payload through", ()
     await sessionsRoute.handleSessionTree({ url: "/api/session-tree" }, res, { cid: "t" });
     assert.equal(written[0].status, 200);
     assert.equal(written[0].headers["Cache-Control"], "no-store");
-    assert.deepEqual(JSON.parse(written[1].body), payload);
+    // Every session in the payload gains `pinned` — including the child,
+    // which the mock overlay walks only one level deep, so the assertion
+    // is on the top-level row. The point is that the field APPEARS, not
+    // that this particular stub marked it correctly.
+    assert.deepEqual(JSON.parse(written[1].body), {
+      ...payload,
+      projects: payload.projects.map((p) => ({
+        ...p,
+        directories: p.directories.map((d) => ({
+          ...d,
+          sessions: d.sessions.map((s) => ({ ...s, pinned: false })),
+        })),
+      })),
+      pins: { pinnedIds: [], degraded: true, reason: "engine_host_unavailable" },
+    });
   });
 
   test("?refresh=1 reaches the facade as force:true, and nothing else does", async (t) => {
diff --git a/packages/webui/test/lib/mcode-exec-stream.test.js b/packages/webui/test/lib/mcode-exec-stream.test.js
new file mode 100644
index 00000000..447a485a
--- /dev/null
+++ b/packages/webui/test/lib/mcode-exec-stream.test.js
@@ -0,0 +1,353 @@
+// webui/test/lib/mcode-exec-stream.test.js
+// D1: the exec transport's stream-json CONSUMER, end to end.
+//
+// Before D1, `collectExecResult` dispatched on `delta` / `message` /
+// `exec.result` — the supervisor's internal `TuiStreamEvent` names — while
+// `mcode exec --output-format stream-json` writes only the projected
+// `ExecEvent` union (packages/tui/src/headless/events.ts:27-48). The two
+// name families have an empty intersection, so nothing the wire wrote was
+// ever read: no streaming delta, no session id, no usage, no terminal
+// status. These tests drive the real parser with the real wire bytes and
+// assert what lands in the client state the front end renders.
+//
+// The wire is produced by `ExecEventProjector` itself, imported from the
+// tui package, so the fixture cannot drift from what the CLI actually
+// emits — a hand-written JSON literal in a test is a claim about the
+// wire; a projected event is the wire. `TuiStreamEvent` inputs are the
+// supervisor's own delivery events, which is the one layer where
+// `delta`/`message` legitimately exist: the projector is what turns them
+// into the `ExecEvent`s the parser must read.
+//
+// The child process is a real one (a tiny node script in a tmpdir that
+// replays a projected event stream to stdout), so the test exercises the
+// actual stdout -> line-splitting -> JSON.parse path rather than a stub.
+
+import { test, describe, mock } from "node:test";
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import { writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import { mkTmpDir } from "../helpers/tmp.js";
+
+const TEST_DIR = dirname(fileURLToPath(import.meta.url));
+const absPath = (rel) =>
+  pathToFileURL(join(TEST_DIR, "..", "..", "server", rel)).href;
+
+// The state-bus is mocked down to the three calls `collectExecResult`
+// makes into it. The real module is not a passive registry: the first
+// `pushStateFor` walks into the acp client singleton and starts a real
+// subprocess, which then outlives the test file. The parser's behaviour
+// under test is exactly what happens BETWEEN those three calls, so
+// stubbing them removes a live side effect without touching it.
+mock.module(absPath("lib/state-bus.js"), {
+  namedExports: {
+    setActiveChild: () => {},
+    clearActiveChild: () => {},
+    pushStateFor: () => {},
+  },
+});
+
+const { collectExecResult } = await import(absPath("lib/mcode-exec.js"));
+const { ExecEventProjector } = await import(
+  pathToFileURL(join(TEST_DIR, "..", "..", "..", "tui", "src", "headless", "events.ts")).href
+);
+
+const RUN = { runId: "run_d1", sessionId: "mvs_d1session", turnId: "turn_d1" };
+
+// `TuiStreamEvent` inputs in the shapes `projectItems` reads
+// (events.ts:141-177): an assistant `delta` carries thinking/content
+// deltas and tool calls, an assistant `message` carries the final text.
+const delta = (content, extra = {}) => ({
+  type: "delta",
+  role: "assistant",
+  turnId: RUN.turnId,
+  messageId: "msg_1",
+  ...extra,
+  content,
+});
+const message = (extra) => ({
+  type: "message",
+  message: { id: "msg_1", role: "assistant", turnId: RUN.turnId, ...extra },
+});
+
+/** The exact bytes `mcode exec --output-format stream-json` writes for
+ * one turn: `ExecEventProjector.project()` per delivery event, then
+ * `complete(result)`. Returned as JSONL. */
+function projectWire(deliveries, result) {
+  const projector = new ExecEventProjector({ ...RUN, resumed: false, nowMs: () => 0 });
+  const events = deliveries.flatMap((d) => projector.project(d));
+  events.push(...projector.complete(result));
+  return events.map((e) => JSON.stringify(e)).join("\n") + "\n";
+}
+
+/** A real child that reads `wire` from stdin, replays it to stdout one
+ * line at a time (so the parser sees real chunk boundaries), then exits —
+ * the shape it is handed in production, where the prompt arrives on stdin
+ * and the event stream leaves on stdout. */
+function spawnWireEmitter(wire, { holdMs = 0 } = {}) {
+  const dir = mkTmpDir("mcode-exec-stream-");
+  const script = join(dir, "emit.mjs");
+  writeFileSync(
+    script,
+    `import { createInterface } from "node:readline";
+const rl = createInterface({ input: process.stdin });
+let buf = "";
+rl.on("line", (l) => { buf += l + "\\n"; });
+rl.on("close", async () => {
+  for (const line of buf.split("\\n")) {
+    if (!line) continue;
+    process.stdout.write(line + "\\n");
+    await new Promise((r) => setTimeout(r, 1));
+  }
+  ${holdMs ? `await new Promise((r) => setTimeout(r, ${holdMs}));` : ""}
+  process.exit(0);
+});
+`,
+  );
+  const child = spawn(process.execPath, [script], {
+    stdio: ["pipe", "pipe", "pipe"],
+  });
+  child.stdin.end(wire);
+  return child;
+}
+
+/** The client-state fields `collectExecResult` reads, spelled out rather
+ * than taken from `makeClientState()`: importing the state-bus here
+ * would boot the module's process singletons, and the shape is already
+ * pinned by sessions-reset-context.check.mjs. */
+function makeCs() {
+  return {
+    chat: [],
+    model: { name: "test-model" },
+    context: {
+      tokens: 0, used: 0, percent: 0, limit: 512000, tps: 0,
+      estimated: false, lastUsageAt: null, thinkingStatus: "Idle",
+    },
+    usage: { sessionInput: 0, sessionOutput: 0, sessionTotal: 0 },
+    running: {
+      active: false, prompt: null, pid: null, startedAt: null,
+      model: null, sessionId: null, lastDeltaAt: null, tps: 0,
+    },
+  };
+}
+
+/** Run one turn through the real parser and resolve with everything the
+ * front end would see. `cid` is null so the state-bus run/child
+ * registries stay out of the way — this test is about the parser. */
+function runTurn(wire, opts) {
+  const cs = makeCs();
+  const child = spawnWireEmitter(wire, opts);
+  return collectExecResult({
+    child,
+    label: "prompt",
+    model: cs.model.name,
+    cs,
+    cid: null,
+    sessionId: null,
+  }).then((r) => ({ r, cs, child }));
+}
+
+describe("exec transport — the stream-json consumer (D1)", () => {
+
+  test("a streamed turn lands incremental text in the chat buffer and the result", async () => {
+    const wire = projectWire(
+      [
+        // The projector splits one delivery event into a reasoning item
+        // and an agent_message item, so a real turn delivers thinking and
+        // content in SEPARATE deltas — a delta carrying both projects to
+        // two items per line, which would interleave the ▲ and ● lines.
+        { ...delta(""), thinking: "think" },
+        { ...delta(""), thinking: "ing" },
+        delta("Let me "),
+        delta("check"),
+        delta(" that for you."),
+      ],
+      {
+        schemaVersion: 1,
+        type: "exec.result",
+        runId: RUN.runId,
+        sessionId: RUN.sessionId,
+        turnId: RUN.turnId,
+        status: "succeeded",
+        usage: { totalTokens: 120, inputTokens: 80, outputTokens: 40 },
+        durationMs: 4321,
+      },
+    );
+    const { r, cs } = await runTurn(wire);
+    // The answer arrived as deltas, not from a terminal line.
+    assert.equal(r.answer, "Let me check that for you.");
+    assert.equal(r.thinking, "thinking");
+    assert.equal(r.status, "succeeded");
+    assert.equal(r.sessionId, RUN.sessionId);
+    assert.equal(r.usage.totalTokens, 120);
+    assert.equal(r.durationMs, 4321);
+    // The streaming lines are what the front end rendered: an `▲`
+    // reasoning line and a `●` answer line, cursor stripped at finalize.
+    const answerLines = cs.chat.filter((l) => l.startsWith("● "));
+    const thinkingLines = cs.chat.filter((l) => l.startsWith("▲ "));
+    assert.equal(thinkingLines.length, 1, "one reasoning line");
+    assert.equal(thinkingLines[0], "▲ thinking");
+    assert.equal(answerLines.length, 1, "one answer line");
+    assert.equal(answerLines[0], "● Let me check that for you.");
+    // Usage reached the conversation counters, so the context panel moves.
+    assert.equal(cs.context.used, 120);
+    assert.equal(cs.usage.sessionInput, 80);
+    assert.equal(cs.usage.sessionOutput, 40);
+    assert.equal(cs.context.estimated, false);
+    // finalize cleared the running claim.
+    assert.equal(cs.running.active, false);
+    assert.equal(cs.context.thinkingStatus, "Idle");
+  });
+
+  test("the chat buffer grows DURING the turn, before the terminal event", async () => {
+    // The regression this whole fix exists for: nothing reached the
+    // buffer until the process was already over. A wire that stalls
+    // between the first delta and its terminal events must still show the
+    // partial text while the child is alive.
+    const projector = new ExecEventProjector({ ...RUN, resumed: false, nowMs: () => 0 });
+    const head = [
+      ...projector.project(delta("partial ")),
+      ...projector.project(delta("answer")),
+    ]
+      .map((e) => JSON.stringify(e))
+      .join("\n") + "\n";
+    const cs = makeCs();
+    // The child holds the terminal events back for 30s, so the window in
+    // which "the run is still open" is not a timing accident. It is
+    // SIGKILLed below, so the hold never elapses and the test costs no
+    // wall-clock time.
+    const child = spawnWireEmitter(head, { holdMs: 30000 });
+    const done = collectExecResult({
+      child, label: "prompt", model: cs.model.name, cs, cid: null, sessionId: null,
+    });
+    // Wait for the streamed lines to appear, while the run is still open.
+    // The predicate is the FULL expected line, not "a `● ` line exists":
+    // the first `contentDelta` already creates that line, so a predicate
+    // that loose races the second one and reads a half-written turn. The
+    // bound is generous on purpose — it is node startup plus module load
+    // for a freshly spawned child under a loaded test gate, and a tight
+    // bound here shows up as a flake rather than as a defect.
+    const streamed = "● partial answer ▍";
+    const deadline = Date.now() + 15000;
+    while (Date.now() < deadline && !cs.chat.includes(streamed)) {
+      await new Promise((r) => setTimeout(r, 10));
+    }
+    // The child is signalled by the PID this test spawned, in a finally
+    // so a failed assertion cannot leave a 30s hold running and hang the
+    // file.
+    try {
+      const midRun = cs.chat.filter((l) => l.startsWith("● "));
+      assert.equal(midRun.length, 1, "the answer line exists mid-run");
+      assert.equal(midRun[0], streamed, "with the live streaming cursor");
+      assert.equal(cs.running.active, true, "the turn is still running");
+    } finally {
+      child.kill("SIGKILL");
+      await done;
+    }
+  });
+
+  test("a turn that never streamed still delivers its answer and status", async () => {
+    // No delta at all: the agent's whole message arrives as one
+    // `message` event, which the projector emits as `item.completed` with
+    // the full `content`. Before D1 this produced an empty answer.
+    const wire = projectWire(
+      [message({ content: "one shot answer" })],
+      {
+        schemaVersion: 1,
+        type: "exec.result",
+        runId: RUN.runId,
+        sessionId: RUN.sessionId,
+        turnId: RUN.turnId,
+        status: "succeeded",
+        durationMs: 12,
+      },
+    );
+    const { r, cs } = await runTurn(wire);
+    assert.equal(r.answer, "one shot answer");
+    assert.equal(r.status, "succeeded");
+    assert.equal(r.sessionId, RUN.sessionId);
+    assert.equal(cs.chat.filter((l) => l.startsWith("● ")).length, 1);
+  });
+
+  test("a failed turn reports the engine's status and error", async () => {
+    const wire = projectWire(
+      [delta("partial")],
+      {
+        schemaVersion: 1,
+        type: "exec.result",
+        runId: RUN.runId,
+        sessionId: RUN.sessionId,
+        turnId: RUN.turnId,
+        status: "failed",
+        error: { code: "internal", message: "engine exploded" },
+        durationMs: 7,
+      },
+    );
+    const { r, cs } = await runTurn(wire);
+    assert.equal(r.status, "failed");
+    assert.equal(r.error.message, "engine exploded");
+    // `turn.failed` also carries it, and the last word wins only because
+    // the terminal event comes second — the answer is not discarded.
+    assert.equal(r.answer, "partial");
+    assert.equal(cs.running.active, false);
+  });
+
+  test("a tool_call item is consumed without becoming a chat line", async () => {
+    // The item stream is now read; `tool_call` items carry a toolCall
+    // payload instead of text, so they must be dropped rather than
+    // rendered as an empty `●` line. This is the same fact
+    // EXEC_CAPABILITIES.toolSkillInvocation records.
+    const wire = projectWire(
+      [
+        delta("before", {
+          toolCalls: [{ id: "call_1", name: "read", arguments: { path: "a" } }],
+        }),
+        delta(" after"),
+      ],
+      {
+        schemaVersion: 1,
+        type: "exec.result",
+        runId: RUN.runId,
+        sessionId: RUN.sessionId,
+        turnId: RUN.turnId,
+        status: "succeeded",
+        durationMs: 3,
+      },
+    );
+    const { r, cs } = await runTurn(wire);
+    assert.equal(r.answer, "before after");
+    assert.equal(
+      cs.chat.filter((l) => l.includes("▍") || l.trim() === "●").length,
+      0,
+      "no empty or cursor-bearing line is left behind",
+    );
+    assert.equal(cs.chat.filter((l) => l.startsWith("● ")).length, 1);
+  });
+
+  test("a session.resumed wire yields the resumed session id", async () => {
+    // The `--session <id>` re-entry path: the wire says which session the
+    // run entered, and the parser has to hand it back so the NEXT turn
+    // can continue it. This is what makes exec multi-turn at all.
+    const projector = new ExecEventProjector({
+      ...RUN, sessionId: "mvs_resumed", resumed: true, nowMs: () => 0,
+    });
+    const events = [
+      ...projector.project(delta("resumed answer")),
+      ...projector.complete({
+        schemaVersion: 1,
+        type: "exec.result",
+        runId: RUN.runId,
+        sessionId: "mvs_resumed",
+        turnId: RUN.turnId,
+        status: "succeeded",
+        durationMs: 5,
+      }),
+    ];
+    const wire = events.map((e) => JSON.stringify(e)).join("\n") + "\n";
+    const { r } = await runTurn(wire);
+    assert.equal(r.sessionId, "mvs_resumed");
+    assert.equal(r.answer, "resumed answer");
+  });
+});
diff --git a/packages/webui/test/server/app-hono.test.js b/packages/webui/test/server/app-hono.test.js
index 881165a1..3e7484c8 100644
--- a/packages/webui/test/server/app-hono.test.js
+++ b/packages/webui/test/server/app-hono.test.js
@@ -62,6 +62,18 @@ describe("app.js — migration ledger", () => {
       "GET /api/sessions/search",
       "POST /api/sessions/cleanup-orphans",
       "DELETE /api/sessions/:id",
+      // PB-1: the session right-click action family, in the same order as
+      // the registrations in app.js. Three of these unlock a menu item
+      // that used to render permanently greyed (`session-tree.tsx`), and
+      // the fourth is the options read the duplicate dialog renders. The
+      // worktree variant of that menu and the project-level "archive
+      // conversations" item are deliberately ABSENT from this list: they
+      // are honest placeholders with no backend, and a route for either
+      // would be a capability the UI cannot reach.
+      "POST /api/sessions/:id/archive",
+      "POST /api/sessions/:id/pin",
+      "GET /api/sessions/:id/fork-options",
+      "POST /api/sessions/:id/fork",
       "GET /api/session-tree",
       "GET /api/acp-sessions",
       "GET /api/acp-session-title",
diff --git a/packages/webui/test/server/session-context-actions-host.test.js b/packages/webui/test/server/session-context-actions-host.test.js
new file mode 100644
index 00000000..2098b044
--- /dev/null
+++ b/packages/webui/test/server/session-context-actions-host.test.js
@@ -0,0 +1,126 @@
+// webui/test/server/session-context-actions-host.test.js
+//
+// The real-host evidence for placeholder batch PB-1: the four session
+// right-click actions reach REAL engine methods on a BOOTED host.
+//
+// The gate, the three-state handling and the pure derivations live in
+// `test/lib/engine/session-context-actions.test.js` (fast, no boot,
+// injected host). This file exists for the one claim that cannot be
+// decided without a runtime:
+//
+//   1. `host.cliService` really carries `archiveSession`,
+//      `getSessionForkOptions` and `forkSession` — the three methods the
+//      menu's live items call. A facade test with a fake host proves the
+//      facade calls what it says; only this proves what it says EXISTS.
+//   2. `host.services.pinService` really carries `pinSession` and
+//      `getOrder`, on the SAME host, at the SAME path the three-state
+//      resolver walks. This is the one that matters most for PB-1: pin
+//      is the family's only member read through the PB-8 window rather
+//      than through `cliService`, and the path it walks
+//      (`host.services.pinService.pinSession`) is exactly the kind of
+//      string that is wrong in a way no fake-host test can see.
+//   3. `readEnginePinnedSessionOrder()` against the real host does NOT
+//      degrade — which is the difference between "the overlay works" and
+//      "the overlay silently returns [] on every tree read".
+//
+// What is deliberately NOT asserted. No session is archived, pinned or
+// forked here. These are WRITES against a real store, and a test whose
+// side effect is a row in the engine's database is a test that changes
+// the state the next assertion reads. The existence and shape of the
+// methods is the contract this batch owns; their behaviour under a real
+// id belongs with the engine's own suite, which is where
+// `lifecycle-application.ts#archiveSession` and the fork workflow are
+// already covered.
+//
+// Cost note, matching the sibling suite: booting the host opens a
+// better-sqlite3 connection per dataDir that the host's `close()` does
+// not close, so the tmp dir survives until GC runs. The teardown below
+// mirrors `test/server/host-services-window.test.js` for that reason and
+// reuses its registered tmp prefix, because the leak profile is
+// identical — same runtime, same fd lifetime.
+
+import { test, before, after } from "node:test";
+import { strict as assert } from "node:assert";
+
+import { mkTmpDir, rmTmpDir } from "../helpers/tmp.js";
+
+let tmpBase;
+before(() => {
+  tmpBase = mkTmpDir("mcode-webui-runtime-host-");
+});
+after(() => {
+  if (global.gc) {
+    try { global.gc(); } catch { /* best effort */ }
+  }
+  rmTmpDir(tmpBase);
+});
+
+test("PB-1-HOST-01: the four actions reach real methods on a booted host", async () => {
+  const dir = mkTmpDir("pb1-host-", { parent: tmpBase });
+  const { createCatalogueHost } = await import("../../server/lib/runtime-host.js");
+
+  const host = await createCatalogueHost({ dataDir: dir });
+  try {
+    // --- the three cliService members ---------------------------------
+    // These are the methods the three live menu items call. Asserted by
+    // name against the REAL surface, because the capability declaration
+    // that gates them (`sessionCrud: full` in
+    // `local-runtime-v2.capabilities.js`) is a static claim and this is
+    // the mechanical check that the claim is true. The snapshot audit
+    // (test/lib/engine/capability-snapshot.test.js:345) asserts the same
+    // methods; this file asserts the same methods THROUGH PB-1's own
+    // declaration table, so a divergence between the two is visible here
+    // rather than in whichever suite runs second.
+    for (const method of ["archiveSession", "getSessionForkOptions", "forkSession"]) {
+      assert.equal(
+        typeof host.cliService?.[method],
+        "function",
+        `host.cliService.${method} must be callable — a missing member here is a 501 on a menu item this batch unlocked`,
+      );
+    }
+
+    // --- the pin member, through the PB-8 window ----------------------
+    // The path is the load-bearing part. `resolveContextActionMember`
+    // walks `host` (not `host.services`) with the dotted string
+    // `services.pinService`, after checking the window's own three
+    // states. A unit test with a fake host cannot see a path that is
+    // wrong in a uniform way; this one can, and did: the first
+    // implementation walked the path from the window and answered 501 for
+    // a member that was right there.
+    const services = host.services;
+    assert.ok(services, "a booted v2 host must carry an owner graph");
+    assert.equal(typeof services.pinService, "object", "services.pinService must be composed");
+    assert.equal(
+      typeof services.pinService.pinSession,
+      "function",
+      "services.pinService.pinSession must be callable — the pin menu item resolves through exactly this member",
+    );
+    assert.equal(
+      typeof services.pinService.getOrder,
+      "function",
+      "services.pinService.getOrder must be callable — the sidebar's pin overlay reads through exactly this method",
+    );
+
+    // --- the overlay does not degrade against a real host ------------
+    // The absence of this assertion is what would let the overlay ship
+    // as a permanent no-op: `readEnginePinnedSessionOrder` degrades by
+    // design, so a path that always returns `{pinnedIds: [], degraded:
+    // true}` is a PASSING implementation with no pins on screen. On a
+    // real host nothing is pinned yet, so the honest answer is
+    // `degraded: false` with an empty list — and that is the pair that
+    // distinguishes "the engine said nothing is pinned" from "we could
+    // not ask".
+    const { readEnginePinnedSessionOrder } = await import(
+      "../../server/engine/session-context-actions.js"
+    );
+    const order = await readEnginePinnedSessionOrder({ getHost: async () => host });
+    assert.equal(
+      order.degraded,
+      false,
+      `the pin read must not degrade against a real host (reason: ${order.reason}) — a permanent degrade is a permanent no-op overlay`,
+    );
+    assert.deepEqual(order.pinnedIds, [], "a fresh data dir has nothing pinned");
+  } finally {
+    await host.close();
+  }
+});
diff --git a/packages/webui/webapp/components/session-tree.tsx b/packages/webui/webapp/components/session-tree.tsx
index a28a40df..e0f1eb54 100644
--- a/packages/webui/webapp/components/session-tree.tsx
+++ b/packages/webui/webapp/components/session-tree.tsx
@@ -578,7 +578,19 @@ function ProjectNode({
           icon="archive"
           label={t("projectMenu.archive")}
           disabled
-          title={t("common.notLocal")}
+          // PB-1 updated this reason, and the tooltip is the only place it
+          // is stated. The old `common.notLocal` was WRONG twice over: it
+          // claimed the local build lacks a capability it has had all
+          // along (the SESSION-level 归档 above this menu is now live and
+          // calls `archiveSession`), and it said nothing about what is
+          // actually missing. What is missing is a PROJECT-SCOPED bulk
+          // archive: v2 declares `archiveSession({id, archived})` for one
+          // session and nothing project-wide, so this item would have to
+          // fan out N single-session writes. Whether a partial failure
+          // counts as success, and whether the user authorizes once or N
+          // times, are product decisions no existing contract answers —
+          // see `server/engine/session-context-actions.js` KNOWN DEBT 2.
+          title={t("projectMenu.archiveUnavailable")}
           testid="project-menu-archive"
         />
       ),
@@ -1023,8 +1035,22 @@ function DirectoryNode({
  *
  *   - 重命名 / 复制（工作目录、会话 ID）/ 删除 are real — they route through
  *     the same endpoints the hover actions use.
- *   - 置顶 / 归档 / 复制为新会话 / 复制到新工作树 have no server contract
- *     yet, so they render disabled rather than fake an action.
+ *   - 置顶 / 归档 / 复制为新会话 became real in PB-1. Each has a handler
+ *     passed in by the row that owns it (`onPin` / `onArchive` / `onFork`);
+ *     they are `disabled` when the row did not supply one, which is the
+ *     same rule 重命名 has always used. The state is not re-derived here —
+ *     a row is pinned because `session.pinned` says so, and that field is
+ *     the engine's `PinService` answer laid over the tree by
+ *     `server/routes/sessions.js`.
+ *   - 复制到新工作树 stays disabled, and the reason is NOT "no contract":
+ *     the engine has the method. `ForkSessionInput.createIsolatedWorktree`
+ *     exists and `GET /api/sessions/:id/fork-options` already returns
+ *     `worktreeVisible` / `worktreeEligible` / `worktreeUnavailableReason`,
+ *     and this client type carries all three. What is missing is a
+ *     REFERENCE — design-ref/ has no screenshot of this menu, so the
+ *     dialog's shape, whether a branch is chosen, and what happens to the
+ *     source session are unknown. Per doc/placeholder-batch-plan.md §3.4
+ *     ("不要在没有参照的情况下自创形态") this item is not self-authored.
  *   - 在文件夹中显示 / 问题反馈 are disabled in the reference itself; they
  *     are carried across as-is so the menu's shape matches.
  */
@@ -1032,6 +1058,9 @@ function buildSessionContextMenu({
   session,
   workspaceDir,
   onRename,
+  onPin,
+  onArchive,
+  onFork,
   onDelete,
   t,
 }: {
@@ -1039,6 +1068,12 @@ function buildSessionContextMenu({
   /** The directory the session ran in — the reference's `session.workspaceDir`. */
   workspaceDir?: string;
   onRename?: () => void;
+  /** PB-1: pin / unpin this session. Absent → the item renders disabled. */
+  onPin?: () => void;
+  /** PB-1: archive this session. Absent → the item renders disabled. */
+  onArchive?: () => void;
+  /** PB-1: open the duplicate dialog. Absent → the item renders disabled. */
+  onFork?: () => void;
   onDelete: () => void;
   t: (key: MessageKey) => string;
 }): readonly WebuiContextMenuItem[] {
@@ -1047,9 +1082,13 @@ function buildSessionContextMenu({
     {
       kind: "item",
       key: "pin",
-      label: t("sessionMenu.pin"),
+      // A pinned session's action is to UNpin, and the label says so. The
+      // state comes from the engine's own pin answer, not from a local
+      // guess — see this component's header.
+      label: t(session.pinned ? "sessionMenu.unpin" : "sessionMenu.pin"),
       icon: menuIcon("pin"),
-      disabled: true, // no session-pin contract yet
+      disabled: !onPin,
+      onSelect: onPin,
     },
     {
       kind: "item",
@@ -1064,7 +1103,8 @@ function buildSessionContextMenu({
       key: "archive",
       label: t("sessionMenu.archive"),
       icon: menuIcon("archive"),
-      disabled: true, // no archive contract yet
+      disabled: !onArchive,
+      onSelect: onArchive,
     },
     { kind: "divider", key: "fork-divider" },
     {
@@ -1072,14 +1112,20 @@ function buildSessionContextMenu({
       key: "fork-current",
       label: t("sessionMenu.forkCurrent"),
       icon: menuIcon("fork"),
-      disabled: true, // no fork contract yet
+      disabled: !onFork,
+      onSelect: onFork,
     },
     {
       kind: "item",
       key: "fork-worktree",
       label: t("sessionMenu.forkWorktree"),
       icon: menuIcon("fork"),
-      disabled: true, // no worktree-fork contract yet
+      // Honest placeholder, not a missing backend. The engine method and
+      // the eligibility fields both exist (see this component's header);
+      // the desktop reference for this variant's UI does not. Enabling
+      // it would mean inventing the form. See
+      // server/engine/session-context-actions.js KNOWN DEBT 1.
+      disabled: true,
     },
     { kind: "divider", key: "copy-divider" },
     {
@@ -1141,6 +1187,203 @@ async function copyToClipboard(value: string | undefined, t: (key: MessageKey) =
   }
 }
 
+/**
+ * The 复制为新会话 preview dialog (PB-1).
+ *
+ * It exists because `GET /api/sessions/:id/fork-options` exists. The
+ * engine answers a real question before the write — can this session be
+ * forked, what will it be called, which copy of the title is it — and a
+ * dialog that did not ask would be throwing that answer away. So the
+ * dialog is the read, rendered: it opens, it fetches, and only the
+ * engine's own `canFork` decides whether the confirm button is live.
+ *
+ * What it deliberately does NOT render is the worktree row. The engine
+ * returns `worktreeVisible` / `worktreeEligible` and the client type
+ * carries them; showing a disabled "duplicate to new worktree" row here
+ * would be a second reference-free form, and this batch's discipline is
+ * that an item with no reference stays a single greyed menu row rather
+ * than becoming a greyed row in two places. See
+ * `server/engine/session-context-actions.js` KNOWN DEBT 1.
+ *
+ * The three states are all rendered and none is a blank:
+ *
+ *   loading   — the fetch is in flight. The confirm button is disabled
+ *               rather than absent, so the dialog does not change shape
+ *               when the answer lands.
+ *   canFork   — the confirm button is live and carries the suggested
+ *               title in its own label-adjacent line, so the user sees
+ *               exactly the title the fork will use (the server forces
+ *               `useSuggestedTitle: true`).
+ *   !canFork  — the engine's own `unavailableReason` is shown and the
+ *               confirm button is disabled. The reason is rendered as
+ *               the engine's text rather than translated: it is a
+ *               machine reason code the engine owns, and inventing a
+ *               translation for a code this build has never seen would
+ *               be a guess presented as a translation.
+ */
+function SessionForkDialog({
+  sessionId,
+  open,
+  onCancel,
+  onForked,
+  t,
+}: {
+  sessionId: string;
+  open: boolean;
+  onCancel: () => void;
+  /** Called with the new session's id once the fork succeeded. */
+  onForked: (newSessionId: string) => void;
+  t: (key: MessageKey) => string;
+}) {
+  const [options, setOptions] = useState<api.SessionForkOptions | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [forking, setForking] = useState(false);
+  // The id whose options are on screen. Without it, a dialog reopened on
+  // a DIFFERENT row would show the previous row's answer for the frames
+  // between mount and the fetch resolving — the same class of bug as
+  // reusing a stale closure over a changed prop.
+  const [loadedFor, setLoadedFor] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (!open) return;
+    let cancelled = false;
+    setLoading(true);
+    setOptions(null);
+    setLoadedFor(null);
+    void (async () => {
+      try {
+        const next = await api.getSessionForkOptions(sessionId);
+        if (cancelled) return;
+        setOptions(next);
+        setLoadedFor(sessionId);
+      } catch (cause) {
+        if (cancelled) return;
+        // A failed READ is not an empty answer: the dialog says so and
+        // keeps the confirm button disabled, rather than rendering
+        // `canFork:false` and implying the engine refused a fork it was
+        // never asked about.
+        reportActionError(t("sessionMenu.forkCurrent"), cause);
+      } finally {
+        if (!cancelled) setLoading(false);
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [open, sessionId, t]);
+
+  if (!open) return null;
+
+  const canFork = options?.ok === true && options.canFork === true;
+  // `loadedFor` guards the render against the one frame where `options`
+  // still holds the previous row's answer.
+  const answer = loadedFor === sessionId ? options : null;
+
+  const runFork = async () => {
+    setForking(true);
+    try {
+      const forked = await api.forkSession(sessionId);
+      onCancel();
+      onForked(forked.id);
+    } catch (cause) {
+      reportActionError(t("sessionMenu.forkCurrent"), cause);
+    } finally {
+      setForking(false);
+    }
+  };
+
+  return (
+    <AntModal
+      open
+      centered
+      closable
+      keyboard
+      maskClosable={!forking}
+      footer={null}
+      destroyOnHidden
+      width={440}
+      rootClassName="mavis-confirm-modal-compact"
+      classNames={{
+        mask: "mavis-confirm-modal-compact-mask",
+        content: "mavis-confirm-modal-compact-surface",
+      }}
+      styles={{ header: { background: "transparent" } }}
+      title={
+        <span className="mavis-confirm-modal-compact-title text-heading3 text-text_default_primary">
+          {t("sessionMenu.forkCurrent")}
+        </span>
+      }
+      onCancel={() => {
+        if (!forking) onCancel();
+      }}
+    >
+      <div data-testid="session-fork-dialog" className="flex flex-col gap-4 py-2">
+        {loading ? (
+          <p
+            data-testid="session-fork-loading"
+            className="text-sm leading-6 text-text_default_secondary"
+          >
+            {t("sessionMenu.forkLoading")}
+          </p>
+        ) : !answer ? (
+          <p
+            data-testid="session-fork-unavailable"
+            className="text-sm leading-6 text-text_default_secondary"
+          >
+            {t("sessionMenu.forkUnavailable")}
+          </p>
+        ) : (
+          <>
+            {answer.sourceTitle ? (
+              <p className="text-sm leading-6 text-text_default_secondary">
+                {t("sessionMenu.forkFrom").replace("{title}", answer.sourceTitle)}
+              </p>
+            ) : null}
+            <p className="text-caption-small-strong leading-5 text-text_default_tertiary">
+              {answer.suggestedTitle
+                ? t("sessionMenu.forkSuggested").replace("{title}", answer.suggestedTitle)
+                : t("sessionMenu.forkNoTitle")}
+            </p>
+            {answer.canFork ? null : (
+              <p
+                data-testid="session-fork-blocked"
+                className="text-caption-small-strong leading-5 text-text_label_danger_primary_default"
+              >
+                {t("sessionMenu.forkBlocked").replace(
+                  "{reason}",
+                  answer.unavailableReason ?? t("sessionMenu.forkBlockedUnknown"),
+                )}
+              </p>
+            )}
+          </>
+        )}
+        <div className="flex items-center justify-end gap-2">
+          <button
+            type="button"
+            disabled={forking}
+            onClick={onCancel}
+            className="h-8 rounded-lg border border-border_default px-3 text-sm text-text_default_primary transition-colors hover:bg-bg_interaction_tertiary_hover disabled:opacity-50"
+          >
+            {t("sessionMenu.forkCancel")}
+          </button>
+          <button
+            type="button"
+            // Live only on the engine's own `canFork`, and never while the
+            // read is in flight — a button that becomes clickable before
+            // the answer arrives would fork on a guess.
+            disabled={forking || loading || !canFork}
+            data-testid="session-fork-confirm"
+            onClick={() => void runFork()}
+            className="h-8 rounded-lg bg-bg_interaction_primary_default px-3 text-sm text-text_label_inverse_primary transition-colors hover:opacity-90 disabled:opacity-50"
+          >
+            {t("sessionMenu.forkConfirm")}
+          </button>
+        </div>
+      </div>
+    </AntModal>
+  );
+}
+
 const SESSION_STATE_MARK: Record<string, { dot: string; label: MessageKey }> = {
   error: { dot: "bg-bg_status_error", label: "session.status.error" },
   aborted: { dot: "bg-bg_status_warning", label: "session.status.aborted" },
@@ -1175,6 +1418,11 @@ function SessionNode({
     | { readonly x: number; readonly y: number; readonly items: readonly WebuiContextMenuItem[] }
     | undefined
   >();
+  // PB-1: the 复制为新会话 dialog. Held here rather than in the menu builder
+  // because the menu is a pure function of its arguments and rebuilt on
+  // every right-click, while the dialog is a piece of state with a fetch
+  // and a pending write behind it.
+  const [forkOpen, setForkOpen] = useState(false);
   const openSessionMenu = (event: React.MouseEvent<HTMLElement>) => {
     event.preventDefault();
     event.stopPropagation();
@@ -1185,6 +1433,14 @@ function SessionNode({
         session,
         workspaceDir,
         onRename: () => startRename(),
+        onPin: () =>
+          void runAction(
+            t(session.pinned ? "sessionMenu.unpin" : "sessionMenu.pin"),
+            api.pinSession(session.id, !session.pinned),
+          ).then(onChanged),
+        onArchive: () =>
+          void runAction(t("sessionMenu.archive"), api.archiveSession(session.id)).then(onChanged),
+        onFork: () => setForkOpen(true),
         onDelete: () =>
           void runAction(t("sidebar.delete"), api.deleteSession(session.id)).then(onChanged),
         t,
@@ -1470,6 +1726,20 @@ function SessionNode({
           onClose={() => setContextMenu(undefined)}
         />
       ) : null}
+      {/* PB-1. `onForked` re-reads the tree so the new row appears, then
+          switches to it: a duplicate the user cannot navigate to is a
+          duplicate they have to go find, and the switch is the same path
+          every other row-open takes. */}
+      <SessionForkDialog
+        sessionId={session.id}
+        open={forkOpen}
+        onCancel={() => setForkOpen(false)}
+        onForked={(newSessionId) => {
+          onChanged();
+          void openSessionAndReportLanding(newSessionId, onChanged, t);
+        }}
+        t={t}
+      />
     </>
   );
 }
@@ -1566,11 +1836,15 @@ function SubagentRow({
   // right-click menu as its parent — the reference's `openSessionMenu` is
   // bound to child rows too. Rename stays disabled here: the child row has
   // no inline editor to swap into (its rename contract would need the same
-  // edit affordance the main row has).
+  // edit affordance the main row has). PB-1's 置顶 / 归档 / 复制为新会话 are
+  // NOT in that category and are wired below — see `openChildMenu`.
   const [contextMenu, setContextMenu] = useState<
     | { readonly x: number; readonly y: number; readonly items: readonly WebuiContextMenuItem[] }
     | undefined
   >();
+  // PB-1: the child's own copy of the fork dialog, for the same reason
+  // `SessionNode` holds one.
+  const [forkOpen, setForkOpen] = useState(false);
   const openChildMenu = (event: React.MouseEvent<HTMLElement>) => {
     event.preventDefault();
     event.stopPropagation();
@@ -1580,6 +1854,22 @@ function SubagentRow({
       items: buildSessionContextMenu({
         session,
         workspaceDir,
+        // PB-1: the child row gets the same three actions as its parent,
+        // and the reason it can is that all three are keyed on the
+        // session id alone — the child row carries a real `mvs_` id, the
+        // engine's archive/pin/fork methods take no parent/child notion,
+        // and none of them needs an inline editor the way 重命名 does.
+        // Leaving them off would produce two menus with the same items
+        // that behave differently depending on which row was clicked,
+        // which is the kind of difference a user discovers by accident.
+        onPin: () =>
+          void runAction(
+            t(session.pinned ? "sessionMenu.unpin" : "sessionMenu.pin"),
+            api.pinSession(session.id, !session.pinned),
+          ).then(onChanged),
+        onArchive: () =>
+          void runAction(t("sessionMenu.archive"), api.archiveSession(session.id)).then(onChanged),
+        onFork: () => setForkOpen(true),
         onDelete: () =>
           void runAction(t("sidebar.delete"), api.deleteSession(session.id)).then(onChanged),
         t,
@@ -1639,6 +1929,16 @@ function SubagentRow({
           onClose={() => setContextMenu(undefined)}
         />
       ) : null}
+      <SessionForkDialog
+        sessionId={session.id}
+        open={forkOpen}
+        onCancel={() => setForkOpen(false)}
+        onForked={(newSessionId) => {
+          onChanged();
+          void openSessionAndReportLanding(newSessionId, onChanged, t);
+        }}
+        t={t}
+      />
     </>
   );
 }
diff --git a/packages/webui/webapp/lib/api.ts b/packages/webui/webapp/lib/api.ts
index 1f7884b9..c708722d 100644
--- a/packages/webui/webapp/lib/api.ts
+++ b/packages/webui/webapp/lib/api.ts
@@ -297,6 +297,14 @@ export interface TreeSession {
   kind: string;
   status: string;
   updatedAt: number;
+  /**
+   * Whether the engine's `PinService` currently pins this session.
+   *
+   * Always present, `false` included: the server lays the pin overlay
+   * over the whole tree rather than only over the pinned rows, so the
+   * client reads a boolean and never has to know the id set exists.
+   */
+  pinned: boolean;
   /** Subagents this session spawned. Only present on level-3 entries. */
   children: TreeSession[];
 }
@@ -325,6 +333,17 @@ export interface SessionTreePayload {
   truncated?: boolean;
   counts?: { projects: number; directories: number; sessions: number };
   projects?: TreeProject[];
+  /**
+   * How the pin overlay was resolved — present only on a successful tree.
+   *
+   * `degraded: true` means the engine could not be asked which sessions
+   * are pinned, so every `pinned` on this payload is `false` because the
+   * answer is unknown, not because nothing is pinned. The sidebar does
+   * not branch on it today (an unavailable pin section is a cosmetic
+   * loss, not a failure — see `readEnginePinnedSessionOrder`), and the
+   * field exists so that decision is visible rather than implied.
+   */
+  pins?: { pinnedIds: string[]; degraded: boolean; reason: string | null };
 }
 
 // --- filesystem -------------------------------------------------------------
@@ -483,6 +502,85 @@ export const searchFs = (root: string, q: string, opts: FsSearchOpts = {}) => {
 export const getSessionTree = (refresh = false) =>
   request<SessionTreePayload>(`/api/session-tree${refresh ? "?refresh=1" : ""}`);
 
+// --- session right-click actions (PB-1) --------------------------------------
+//
+// The four endpoints behind 归档 / 置顶 / 复制为新会话. Each returns the
+// server's own payload and, on failure, THROWS — `request()` turns a
+// non-2xx into an `HTTP <status>` error, so a 501 from a provider that
+// cannot archive reaches `runAction`'s error path instead of being
+// rendered as a successful click. That is the property #110 established
+// and the reason none of these four returns a bare `{ok:false}`.
+
+/**
+ * Archive or unarchive one session.
+ *
+ * `archived` defaults to `true`; the engine's `archiveSession` covers
+ * both directions in one method, so the flag selects rather than
+ * separates. An archived session leaves the sidebar on the next tree
+ * read and is restorable by calling this again with `archived: false`.
+ */
+export const archiveSession = (id: string, archived = true) =>
+  request<{ ok: boolean; id: string; archived: boolean }>(
+    `/api/sessions/${encodeURIComponent(id)}/archive`,
+    { method: "POST", json: { archived } },
+  );
+
+/**
+ * Pin or unpin one session. The flag is required and is not defaulted:
+ * the menu item is a toggle, and a defaulted flag would move the row in
+ * a direction the user did not pick.
+ *
+ * The response carries the engine's whole pinned set, in the engine's
+ * order, so a caller can re-render without a second tree read.
+ */
+export const pinSession = (id: string, pinned: boolean) =>
+  request<{ ok: boolean; id: string; pinned: boolean; pinnedIds: string[] }>(
+    `/api/sessions/${encodeURIComponent(id)}/pin`,
+    { method: "POST", json: { pinned } },
+  );
+
+/** What a fork of this session would be, before the user commits to one. */
+export interface SessionForkOptions {
+  ok: boolean;
+  id: string;
+  canFork: boolean;
+  unavailableReason: string | null;
+  suggestedTitle: string | null;
+  nextForkOrdinal: number | null;
+  sourceTitle: string | null;
+  /**
+   * The engine's worktree eligibility, carried through untouched.
+   *
+   * Read by nobody in this batch: the worktree variant of the menu has
+   * no desktop reference to build against, so it stays an honest
+   * placeholder. The fields travel so the batch that unblocks it does
+   * not need a second round trip.
+   */
+  worktree: { visible: boolean; eligible: boolean; unavailableReason: string | null };
+}
+
+export const getSessionForkOptions = (id: string, assistantMessageId?: string) =>
+  request<SessionForkOptions>(
+    `/api/sessions/${encodeURIComponent(id)}/fork-options` +
+      (assistantMessageId
+        ? `?assistantMessageId=${encodeURIComponent(assistantMessageId)}`
+        : ""),
+  );
+
+/**
+ * Duplicate this conversation as a new session in the same workspace.
+ *
+ * `assistantMessageId` is the fork POINT; omitted, the whole
+ * conversation is duplicated, which is what the menu item means when
+ * the user has not picked a message. The created session's id comes
+ * back so the caller can switch to it.
+ */
+export const forkSession = (id: string, assistantMessageId?: string) =>
+  request<{ ok: boolean; id: string; sourceId: string; forkOriginMessageId: string | null }>(
+    `/api/sessions/${encodeURIComponent(id)}/fork`,
+    { method: "POST", json: assistantMessageId ? { assistantMessageId } : {} },
+  );
+
 // --- model and permissions --------------------------------------------------
 
 /**
diff --git a/packages/webui/webapp/lib/i18n.ts b/packages/webui/webapp/lib/i18n.ts
index b6cbd288..6335516d 100644
--- a/packages/webui/webapp/lib/i18n.ts
+++ b/packages/webui/webapp/lib/i18n.ts
@@ -210,13 +210,20 @@ const en = {
 
   /* Project context menu (ticket 55c, ref-26). Rename / pin are backed by the
      browser-local project customizations (webapp/lib/project-custom.ts);
-     reveal-in-folder and archive render disabled with `common.notLocal`;
-     remove batch-deletes the project's sessions behind a confirm. */
+     reveal-in-folder renders disabled with `common.notLocal`; remove
+     batch-deletes the project's sessions behind a confirm.
+     PB-1 corrected the archive item's reason: it used `common.notLocal`,
+     which claimed the local build lacks a capability it has (the
+     SESSION-level 归档 is live and calls `archiveSession`). What is
+     missing is a project-SCOPED bulk archive, so this item gets its own
+     tooltip — see `server/engine/session-context-actions.js` KNOWN DEBT 2. */
   "projectMenu.rename": "Rename project",
   "projectMenu.pin": "Pin project",
   "projectMenu.unpin": "Unpin project",
   "projectMenu.revealInFolder": "Reveal in folder",
   "projectMenu.archive": "Archive chats",
+  "projectMenu.archiveUnavailable":
+    "No project-wide archive yet: the engine archives one session at a time, and archiving a whole project is a bulk operation this build has not defined.",
   "projectMenu.remove": "Remove",
   "projectMenu.removeConfirmTitle": "Remove project",
   /* Both {count} keys are replaced by the component with the TRUE deletion
@@ -237,14 +244,30 @@ const en = {
 
   /* Session-row context menu (webui-parity 58 line B — the reference
      SessionRail's `openSessionMenu` item set, zh labels verbatim from the
-     reference). Pin / archive / fork / reveal / feedback have no contract
-     here (the reference ships reveal and feedback disabled too) and render
-     disabled; rename / copy / delete are real. */
+     reference). Reveal / feedback have no contract here (the reference
+     ships both disabled too) and render disabled; rename / copy / delete
+     are real. PB-1 unlocked pin / archive / fork-current — see
+     `server/engine/session-context-actions.js`. `forkWorktree` stays
+     disabled and is NOT a missing backend: the engine method and the
+     eligibility fields exist, the desktop reference for its UI does not. */
   "sessionMenu.pin": "Pin",
+  "sessionMenu.unpin": "Unpin",
   "sessionMenu.rename": "Rename",
   "sessionMenu.archive": "Archive",
   "sessionMenu.forkCurrent": "Duplicate as new session",
   "sessionMenu.forkWorktree": "Duplicate to new worktree",
+  /* The 复制为新会话 preview dialog (PB-1). Every string here is driven by
+     the engine's own `getSessionForkOptions` answer — the dialog renders
+     what it was told, not what it assumed. */
+  "sessionMenu.forkLoading": "Checking what this duplicate will look like…",
+  "sessionMenu.forkUnavailable": "The engine could not describe this duplicate. Try again.",
+  "sessionMenu.forkFrom": "Source: {title}",
+  "sessionMenu.forkSuggested": "The duplicate will be named “{title}”.",
+  "sessionMenu.forkNoTitle": "The engine named no title for the duplicate.",
+  "sessionMenu.forkBlocked": "The engine declined this duplicate: {reason}",
+  "sessionMenu.forkBlockedUnknown": "no reason given",
+  "sessionMenu.forkCancel": "Cancel",
+  "sessionMenu.forkConfirm": "Duplicate",
   "sessionMenu.revealInFolder": "Reveal in folder",
   "sessionMenu.copy": "Copy",
   "sessionMenu.copyWorkspaceDir": "Copy workspace directory",
@@ -1354,13 +1377,19 @@ const zh: Record<MessageKey, string> = {
   "userMenu.localUser": "本地用户",
 
   /* 项目右键菜单（工单 55c，ref-26）。重命名 / 置顶由浏览器本地项目自定义
-     （webapp/lib/project-custom.ts）支撑；在文件夹中显示与归档对话渲染为
-     禁用并标注 `common.notLocal`；移除在确认弹窗后批量删除项目下的会话。 */
+     （webapp/lib/project-custom.ts）支撑；在文件夹中显示渲染为禁用并标注
+     `common.notLocal`；移除在确认弹窗后批量删除项目下的会话。
+     PB-1 纠正了归档对话一项的禁用理由：原先用 `common.notLocal`，声称本地版
+     缺少一项它本就具备的能力（会话级「归档」已接通 `archiveSession`）。
+     真正缺的是**项目级批量归档**，故此项改用自己的提示文案 —— 见
+     server/engine/session-context-actions.js KNOWN DEBT 2。 */
   "projectMenu.rename": "重命名项目",
   "projectMenu.pin": "置顶项目",
   "projectMenu.unpin": "取消置顶",
   "projectMenu.revealInFolder": "在文件夹中显示",
   "projectMenu.archive": "归档对话",
+  "projectMenu.archiveUnavailable":
+    "暂无项目级批量归档：引擎一次只归档一个会话，而归档整个项目是本版尚未定义的批量操作。",
   "projectMenu.remove": "移除",
   "projectMenu.removeConfirmTitle": "移除项目",
   /* 两个 {count} 占位均由组件填充为真实删除集——主会话与子代理会话
@@ -1378,14 +1407,28 @@ const zh: Record<MessageKey, string> = {
   "projectMenu.cancel": "取消",
 
   /* 会话行右键菜单（webui-parity 58 线 B —— 参照 SessionRail 的
-     `openSessionMenu` 菜单项，中文文案照抄参照）。置顶/归档/复制为新会话/
-     复制到新工作树暂无服务端契约；在文件夹中显示与问题反馈参照本身即为
-     禁用项，照搬；重命名/复制/删除为真实能力。 */
+     `openSessionMenu` 菜单项，中文文案照抄参照）。在文件夹中显示与问题反馈
+     参照本身即为禁用项，照搬；重命名/复制/删除为真实能力。PB-1 解锁了
+     置顶/归档/复制为新会话，见 server/engine/session-context-actions.js。
+     复制到新工作树仍为禁用项，且**不是**缺后端：引擎方法与可用性字段都在，
+     缺的是该形态的桌面参照。 */
   "sessionMenu.pin": "置顶",
+  "sessionMenu.unpin": "取消置顶",
   "sessionMenu.rename": "重命名",
   "sessionMenu.archive": "归档",
   "sessionMenu.forkCurrent": "复制为新会话",
   "sessionMenu.forkWorktree": "复制到新工作树",
+  /* 复制为新会话的预览弹窗（PB-1）。每条文案都由引擎自己的
+     getSessionForkOptions 回答驱动 —— 弹窗渲染它被告知的，而非它以为的。 */
+  "sessionMenu.forkLoading": "正在确认这次复制会得到什么…",
+  "sessionMenu.forkUnavailable": "引擎无法描述这次复制，请重试。",
+  "sessionMenu.forkFrom": "来源会话：{title}",
+  "sessionMenu.forkSuggested": "复制出的会话将命名为“{title}”。",
+  "sessionMenu.forkNoTitle": "引擎未为这次复制给出名称。",
+  "sessionMenu.forkBlocked": "引擎拒绝了这次复制：{reason}",
+  "sessionMenu.forkBlockedUnknown": "未给出原因",
+  "sessionMenu.forkCancel": "取消",
+  "sessionMenu.forkConfirm": "复制",
   "sessionMenu.revealInFolder": "在文件夹中显示",
   "sessionMenu.copy": "复制",
   "sessionMenu.copyWorkspaceDir": "复制工作目录",
diff --git a/packages/webui/webapp/lib/markdown.ts b/packages/webui/webapp/lib/markdown.ts
index 1889907f..bac435c9 100644
--- a/packages/webui/webapp/lib/markdown.ts
+++ b/packages/webui/webapp/lib/markdown.ts
@@ -12,7 +12,10 @@ import { marked } from "marked";
  * the way the desktop does.
  *
  * Assistant text can contain anything the model or a file it read produced, so
- * the parser output is sanitised (see `sanitize`) before it reaches the DOM.
+ * two walls stand between it and the DOM: the `html` renderer override below
+ * escapes raw HTML in the source outright (model-authored `<svg>`/`<path>` and
+ * friends are shown as text, never mounted), and the parser output is then
+ * sanitised (see `sanitize`) for everything the renderers themselves emit.
  * Syntax highlighting is deliberately absent for now — upstream colours code
  * through `--code-theme-*` tokens when a highlighter is attached, and those
  * tokens are already in the token layer, so adding a highlighter later needs no
@@ -199,6 +202,35 @@ marked.use({
     codespan({ text }: { text: string }) {
       return `<code class="inline-code">${escapeHtml(text)}</code>`;
     },
+    /**
+     * Escape raw HTML found in the markdown source — never mount it.
+     *
+     * `marked` has no "no raw HTML" option: whatever inline (`Tokens.Tag`) and
+     * block (`Tokens.HTML`) HTML appears in the source is forwarded into the
+     * output verbatim, which left the sanitiser below as the only wall. That
+     * wall is per-tag, and it allowlists `svg`/`path` for KaTeX geometry, so a
+     * model that pastes an inline SVG snippet had `<path>` survive to
+     * `components/markdown-html.tsx`, which calls `createElement("path")` — an
+     * unknown host element, and one `The tag <path> is unrecognized in this
+     * browser` console error per occurrence (UAT 2026-10-03 16:00 round, ×9).
+     *
+     * Escaping here rather than tightening the allowlist is what keeps the two
+     * consumers apart:
+     *
+     *   - **author HTML** — model output, a file the model read, a user's own
+     *     markdown preview — arrives as `html` tokens and becomes text;
+     *   - **generated HTML** — KaTeX via the `webuiMath` inline extension, and
+     *     every fenced language via `registerLanguageRenderer` — is returned
+     *     straight from its own renderer and never passes through this hook, so
+     *     the real `<svg>`/`<path>` geometry formulas need survives.
+     *
+     * A block token's `text` is the raw source including its trailing newline,
+     * so escaping preserves the original line structure; no newline is added
+     * here (adding one would double every blank line between blocks).
+     */
+    html(token: { text: string }) {
+      return escapeHtml(token.text);
+    },
   },
 });
 
@@ -321,7 +353,15 @@ function sanitize(html: string): string {
   if (typeof window === "undefined" || typeof DOMParser === "undefined") {
     // Static export prerender: the transcript is empty, so there is nothing to
     // render. Returning escaped text keeps this path inert rather than unsafe.
-    return html.replace(/[&<>]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;" })[c] ?? c);
+    //
+    // Only the two angle brackets are escaped, never `&`. The input is already
+    // the parser's output, in which every author `&` and `<` has become an
+    // entity (the `html` override above owns that escaping); escaping `&` again
+    // here would flatten those entities into literal `&amp;lt;` text, so a
+    // reader on the prerender path would see `&lt;script&gt;` where they should
+    // see `<script>`. Escaping `<` and `>` is already sufficient to stay inert —
+    // without a literal `<`, no tag can be formed.
+    return html.replace(/[<>]/g, (c) => (c === "<" ? "&lt;" : "&gt;"));
   }
 
   const doc = new DOMParser().parseFromString(`<body>${html}</body>`, "text/html");
diff --git a/packages/webui/webapp/test/markdown-raw-html.test.ts b/packages/webui/webapp/test/markdown-raw-html.test.ts
new file mode 100644
index 00000000..a12de937
--- /dev/null
+++ b/packages/webui/webapp/test/markdown-raw-html.test.ts
@@ -0,0 +1,188 @@
+// webapp/test/markdown-raw-html.test.ts
+//
+// Regression suite for P17: raw HTML in the markdown source is text, never DOM.
+//
+// The defect
+// ----------
+//
+// UAT round 2026-10-03 16:00 (board P17) recorded nine `[error]`-level
+// `Warning: The tag <path> is unrecognized in this browser` entries whenever a
+// model's reasoning or answer echoed an inline SVG snippet. Three layers
+// combined into it:
+//
+//   1. `marked` has no "no raw HTML" option, and `lib/markdown.ts` configured
+//      it with `{ gfm, breaks }` only — author HTML was forwarded verbatim.
+//   2. `ALLOWED_TAGS` in `lib/markdown.ts` admits `svg` and `path` because
+//      KaTeX emits real SVG geometry, so the sanitiser passed the snippet
+//      through (`<g>`, not allowlisted, was unwrapped).
+//   3. `htmlToReact` (`components/markdown-html.tsx`) turns the sanitised
+//      HTML into React elements with `createElement(tag, …)`, so `<path>`
+//      became a real unknown host element — one console error per occurrence.
+//
+// The fix is one hook (`renderer.html` escaping the token text). This file
+// pins it from both ends:
+//
+//   - author-written SVG / HTML becomes escaped text and produces **no**
+//     element in the React tree, which is what "zero console errors" means
+//     here — React has nothing to warn about;
+//   - renderer-generated SVG (KaTeX) still produces real `svg`/`path`
+//     elements, so the fix did not over-reach.
+//
+// Test strategy: `marked` and the React tree builder are pure, so both are
+// asserted in Node. `htmlToReact` needs a `DOMParser`, which Node lacks, so it
+// runs under the existing parse5-backed shim (`test/helpers/dom-shim.ts`) —
+// the same harness `markdown-html-render.test.ts` uses for the walker. No new
+// dependency: the shim's whole point is that the project does not pull in
+// jsdom/happy-dom.
+
+import { test, describe } from "node:test";
+import assert from "node:assert/strict";
+
+import { parseMarkdown, renderMarkdown } from "../lib/markdown";
+import { htmlToReact } from "../components/markdown-html";
+import "../lib/math-renderer"; // auto-registers the math renderers
+import { withDomParserShim } from "./helpers/dom-shim";
+
+/**
+ * The UAT input, verbatim in shape: an SVG snippet the model pasted into its
+ * reasoning, block-level, with a `<g>` wrapper and a self-closing `<path>`.
+ */
+const REASONING_WITH_SVG = [
+  "先看这棵树的形状：",
+  "",
+  '<svg width="120" height="120" viewBox="0 0 120 120">',
+  '  <g opacity="0.6">',
+  '    <path d="M100 100 L20 20" stroke="black" fill="none"/>',
+  "  </g>",
+  "</svg>",
+  "",
+  "主干就这样。",
+].join("\n");
+
+/** Inline variant — the same tags typed mid-sentence. */
+const INLINE_SVG = '画一个 <svg viewBox="0 0 10 10"><path d="M0 0h10v10z"/></svg> 就行';
+
+/**
+ * Collect every host-element tag the React tree builder emitted.
+ *
+ * `htmlToReact` returns React elements (`{ type, props }`) and text nodes
+ * (strings); components are function/class types and are skipped, so what
+ * lands in the set is exactly the tag names React would ask the DOM to mount.
+ * That set is the direct precondition of the `unrecognized tag` warning: a tag
+ * React does not know must never appear in it.
+ */
+function hostTagNames(node: unknown, out: Set<string> = new Set()): Set<string> {
+  if (Array.isArray(node)) {
+    for (const child of node) hostTagNames(child, out);
+    return out;
+  }
+  if (node === null || typeof node !== "object") return out;
+  const element = node as { type?: unknown; props?: { children?: unknown } };
+  if (typeof element.type === "string") out.add(element.type);
+  if (element.props && "children" in element.props) {
+    hostTagNames(element.props.children, out);
+  }
+  return out;
+}
+
+/** Host tag names the walker produces for a markdown string, under the shim. */
+function tagsFor(source: string): Set<string> {
+  return withDomParserShim(() => hostTagNames(htmlToReact(parseMarkdown(source), "light")));
+}
+
+describe("P17 — author-written SVG becomes text, never DOM tags", () => {
+  test("a block-level SVG snippet emits no live svg/g/path tag", () => {
+    const html = parseMarkdown(REASONING_WITH_SVG);
+    for (const tag of ["svg", "g", "path"]) {
+      assert.doesNotMatch(html, new RegExp(`<${tag}[\\s/>]`, "i"), `<${tag}> must not be live markup`);
+    }
+    // The snippet is still readable — as the source the model wrote.
+    assert.match(html, /&lt;svg width=&quot;120&quot;/);
+    assert.match(html, /&lt;path d=&quot;M100 100 L20 20&quot;/);
+    // Surrounding prose is untouched: one bad snippet does not blank the message.
+    assert.match(html, /先看这棵树的形状：/);
+    assert.match(html, /主干就这样。/);
+  });
+
+  test("an inline SVG snippet typed mid-sentence is escaped too", () => {
+    const html = parseMarkdown(INLINE_SVG);
+    assert.doesNotMatch(html, /<svg[\s/>]/i);
+    assert.doesNotMatch(html, /<path[\s/>]/i);
+    assert.match(html, /&lt;svg viewBox=&quot;0 0 10 10&quot;&gt;/);
+    assert.match(html, /^<p>画一个 /);
+  });
+
+  test("the React tree contains no svg/g/path element for author HTML", () => {
+    // This is the console-zero-error assertion: React warns per unknown host
+    // element it is asked to mount, so the absence of the tags is the absence
+    // of the `The tag <path> is unrecognized in this browser` flood.
+    const tags = tagsFor(REASONING_WITH_SVG);
+    for (const tag of ["svg", "g", "path"]) {
+      assert.equal(tags.has(tag), false, `the React tree must not mount <${tag}>`);
+    }
+    // The paragraph itself still renders — the text was not dropped with the tag.
+    assert.equal(tags.has("p"), true);
+  });
+
+  test("the escaped block keeps its original line structure", () => {
+    // marked hands a block token its raw source *including* the trailing
+    // newline. Escaping must not swallow that, or a pasted multi-line snippet
+    // would collapse into one unreadable line.
+    const html = parseMarkdown(REASONING_WITH_SVG);
+    assert.match(html, /&lt;svg[^\n]*?&gt;\n/, "the newline after the <svg> opener must survive");
+    assert.match(html, /&lt;path[^\n]*?&gt;\n/, "the newline after the <path> line must survive");
+  });
+
+  test("renderMarkdown shows the snippet as escaped text (no-DOM fallback path)", () => {
+    // Node has no `DOMParser`, so `sanitize` takes its inert fallback and
+    // escapes the whole string — which is why this case is *not* the one that
+    // goes red under the mutation; the parse-level tests above are. What it
+    // pins is the contract a caller relies on: the public entry point returns
+    // the snippet as readable source, never blank and never as markup.
+    const html = renderMarkdown(REASONING_WITH_SVG);
+    assert.doesNotMatch(html, /<svg[\s/>]/i);
+    assert.doesNotMatch(html, /<path[\s/>]/i);
+    assert.match(html, /&lt;svg width=&quot;120&quot;/);
+    assert.match(html, /主干就这样。/);
+  });
+
+  test("an HTML block with an event handler is text, not a live element", () => {
+    // The general case behind the SVG symptom: any author HTML, including the
+    // attribute surface the sanitiser would otherwise have to police.
+    const html = parseMarkdown('<div onclick="steal()">hi</div>');
+    assert.doesNotMatch(html, /<div/);
+    assert.match(html, /&lt;div onclick=/);
+    const tags = withDomParserShim(() => hostTagNames(htmlToReact(html, "light")));
+    assert.equal(tags.has("div"), false);
+  });
+
+  test("raw HTML inside a fenced code block is unaffected by the new hook", () => {
+    // The fence has its own escaping path (renderer.code); the new hook must
+    // not change how it looks.
+    const html = parseMarkdown("```html\n<svg><path d=\"M0 0\"/></svg>\n```");
+    assert.match(html, /class="codeblock-shell"/);
+    assert.match(html, /&lt;svg&gt;&lt;path d=&quot;M0 0&quot;\/&gt;&lt;\/svg&gt;/);
+    const tags = withDomParserShim(() => hostTagNames(htmlToReact(html, "light")));
+    assert.equal(tags.has("svg"), false);
+    assert.equal(tags.has("code"), true);
+  });
+});
+
+describe("P17 — generated SVG still renders (the fix must not over-reach)", () => {
+  test("KaTeX geometry still emits real svg and path elements", () => {
+    // KaTeX output comes from the `webuiMath` inline extension's own renderer,
+    // which never passes through `renderer.html`. If this assertion ever goes
+    // red, the escape hook has swallowed renderer-generated markup and every
+    // radical, fraction and stretchy delimiter has lost its shape.
+    const html = parseMarkdown("面积是 $\\sqrt{x}$ 这样");
+    assert.match(html, /class="katex"/);
+    assert.match(html, /<svg/);
+    assert.match(html, /<path/);
+  });
+
+  test("the React tree for a formula contains svg and path elements", () => {
+    const tags = tagsFor("$\\sqrt{x}$");
+    assert.equal(tags.has("svg"), true);
+    assert.equal(tags.has("path"), true);
+  });
+});
diff --git a/packages/webui/webapp/test/session-context-actions.test.ts b/packages/webui/webapp/test/session-context-actions.test.ts
new file mode 100644
index 00000000..6af25c8a
--- /dev/null
+++ b/packages/webui/webapp/test/session-context-actions.test.ts
@@ -0,0 +1,392 @@
+// webapp/test/session-context-actions.test.ts
+//
+// PB-1 — the session right-click menu's three unlocked items, and the
+// two that are still honest placeholders.
+//
+// The same two layers, and for the same reasons, as
+// `shell-elements-parity.test.ts`:
+//
+//   1. Bilingual coverage. The dictionary is typed against `en`, so a
+//      missing-en key is a compile error — but a missing-zh entry
+//      silently falls back to English. PB-1 added ten `sessionMenu.*`
+//      keys plus one `projectMenu.*` key, and every one is pinned in
+//      BOTH locales here. The fork dialog's strings are the user-visible
+//      half of a WRITE, so a dialog that fell back to English would ship
+//      a Chinese UI asking an English question about a fork.
+//
+//   2. Static-source tripwires. The render harness cannot mount antd
+//      popups, so the menu wiring is pinned on the source. This is not a
+//      shortcut: a revert of any of these keeps every other test green —
+//      typecheck included, because the strings would still exist. A menu
+//      that silently went back to grey is exactly the state PB-1 was
+//      written to end, and a test that cannot see it is a test that
+//      would have let it return.
+//
+// The ENGINE side of the same batch — the gate, the three-state host
+// handling, the fork request's forced fields — is in
+// `test/lib/engine/session-context-actions.test.js` and
+// `test/server/session-context-actions-host.test.js`. This file owns
+// only what the browser can see.
+
+import { test, describe } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { resolve, dirname } from "node:path";
+
+import { translate, type MessageKey } from "../lib/i18n";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const read = (relative: string) => readFileSync(resolve(here, relative), "utf8");
+const treeSrc = read("../components/session-tree.tsx");
+const apiSrc = read("../lib/api.ts");
+
+// ---------------------------------------------------------------------------
+// 1. Bilingual coverage — every key PB-1 introduced
+// ---------------------------------------------------------------------------
+
+const PB1_KEYS: MessageKey[] = [
+  "sessionMenu.pin",
+  "sessionMenu.unpin",
+  "sessionMenu.archive",
+  "sessionMenu.forkCurrent",
+  "sessionMenu.forkLoading",
+  "sessionMenu.forkUnavailable",
+  "sessionMenu.forkFrom",
+  "sessionMenu.forkSuggested",
+  "sessionMenu.forkNoTitle",
+  "sessionMenu.forkBlocked",
+  "sessionMenu.forkBlockedUnknown",
+  "sessionMenu.forkCancel",
+  "sessionMenu.forkConfirm",
+  "projectMenu.archiveUnavailable",
+];
+
+describe("PB-1 bilingual coverage", () => {
+  test("every PB-1 key resolves in both locales", () => {
+    for (const key of PB1_KEYS) {
+      const en = translate("en", key);
+      const zh = translate("zh", key);
+      assert.ok(en && en !== key, `en is missing ${key}`);
+      assert.ok(zh && zh !== key, `zh is missing ${key}`);
+      // A zh value identical to the en one is a missing translation that
+      // happens to have been seeded with the English string. Not a
+      // failure for a brand-neutral word, but for a sentence it means
+      // the dialog would ask an English question in a Chinese UI.
+      if (key !== "sessionMenu.forkCancel" && key !== "sessionMenu.forkConfirm") {
+        assert.notEqual(en, zh, `${key} fell back to the English value in zh-CN`);
+      }
+    }
+  });
+
+  test("the placeholder placeholders carry no pin/archive wording", () => {
+    // `sessionMenu.forkUnavailable` and `projectMenu.archiveUnavailable`
+    // are the two strings that now CARRY a reason instead of shrugging
+    // with `common.notLocal`. They must keep naming the specific missing
+    // capability; a future edit that shortens them back to "not supported"
+    // re-creates the vagueness PB-1 removed.
+    assert.match(
+      translate("en", "projectMenu.archiveUnavailable"),
+      /project-wide/i,
+    );
+    assert.match(
+      translate("zh", "projectMenu.archiveUnavailable"),
+      /项目级/,
+    );
+  });
+
+  test("the fork dialog's placeholders are the ones the dialog substitutes", () => {
+    // `{title}` and `{reason}` are `.replace()`d by the component. A key
+    // that lost its placeholder would render the literal braces, and a
+    // key that GAINED one the component does not replace would render the
+    // literal `{…}` — neither is a compile error, so both are pinned here.
+    assert.ok(translate("en", "sessionMenu.forkFrom").includes("{title}"));
+    assert.ok(translate("en", "sessionMenu.forkSuggested").includes("{title}"));
+    assert.ok(translate("en", "sessionMenu.forkBlocked").includes("{reason}"));
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 2. The three unlocked menu items
+// ---------------------------------------------------------------------------
+
+describe("PB-1 — the three live menu items", () => {
+  /** The source slice of one context-menu row, from its key to the next. */
+  /**
+   * The SESSION menu's source, isolated from the PROJECT menu.
+   *
+   * The isolation is not tidiness. Both menus define rows keyed `"pin"`
+   * and `"archive"`, and the project menu comes FIRST in the file, so a
+   * plain `indexOf('key: "archive"')` reads the project item and every
+   * assertion about the session item silently passes against the wrong
+   * code. A test that pins the wrong rows is worse than no test, because
+   * it reads as coverage.
+   */
+  const sessionMenuSrc = treeSrc.slice(
+    treeSrc.indexOf("function buildSessionContextMenu"),
+    treeSrc.indexOf("/** Clipboard write that degrades"),
+  );
+
+  /** One row of the SESSION menu, from its key to `span` chars later. */
+  const rowSource = (key: string, span = 700): string => {
+    const at = sessionMenuSrc.indexOf(`key: "${key}"`);
+    assert.notEqual(at, -1, `session menu row ${key} is missing from session-tree.tsx`);
+    return sessionMenuSrc.slice(at, at + span);
+  };
+
+  test("置顶 is live and toggles on the engine's own pin state", () => {
+    const row = rowSource("pin");
+    // The state must come from the TREE, which carries the engine's
+    // `PinService` answer — not from a local guess. A pin that flipped a
+    // local boolean would look correct until the next tree read.
+    assert.ok(row.includes("session.pinned"), "the pin row reads the tree's pinned field");
+    assert.ok(
+      row.includes('t(session.pinned ? "sessionMenu.unpin" : "sessionMenu.pin")'),
+      "the label must say which direction the click goes",
+    );
+    assert.ok(row.includes("disabled: !onPin"), "disabled only when no handler was supplied");
+    assert.ok(row.includes("onSelect: onPin"), "the row is wired to its handler");
+  });
+
+  test("归档 is live", () => {
+    const row = rowSource("archive");
+    assert.ok(row.includes("disabled: !onArchive"), "disabled only when no handler was supplied");
+    assert.ok(row.includes("onSelect: onArchive"), "the row is wired to its handler");
+  });
+
+  test("复制为新会话 is live and opens the preview dialog", () => {
+    const row = rowSource("fork-current");
+    assert.ok(row.includes("disabled: !onFork"), "disabled only when no handler was supplied");
+    assert.ok(row.includes("onSelect: onFork"), "the row is wired to its handler");
+  });
+
+  test("all three handlers are supplied by BOTH the parent and the child row", () => {
+    // The child (subagent) row builds the same menu. Leaving the three
+    // off it would produce two menus with identical items that behave
+    // differently depending on which row was clicked — a difference the
+    // user discovers by accident, not by reading.
+    const supply = treeSrc.match(/onPin: \(\) =>/g) ?? [];
+    assert.equal(
+      supply.length,
+      2,
+      `both SessionNode and SubagentRow must supply onPin, found ${supply.length}`,
+    );
+    // The window is bounded because `api.pinSession` appears TWICE per
+    // supply site (once in the call, once in no other row) — an unbounded
+    // lazy match would happily pair the first `onPin:` with the SECOND
+    // row's `api.pinSession` and report two supplies when the child row
+    // supplies none. 400 chars is the whole handler body.
+    for (const [handler, call] of [
+      ["onPin", "api.pinSession"],
+      ["onArchive", "api.archiveSession"],
+      ["onFork", "setForkOpen(true)"],
+    ] as const) {
+      const uses = treeSrc.split(`${handler}: () =>`).length - 1;
+      assert.equal(uses, 2, `${handler} must be supplied twice, found ${uses}`);
+      // And each supply must actually reach the engine call, not merely
+      // exist: a handler that was written and never wired to anything
+      // would pass the count above.
+      const bodies = treeSrc.split(`${handler}: () =>`).slice(1);
+      for (const body of bodies) {
+        assert.ok(
+          body.slice(0, 400).includes(call),
+          `${handler} must reach ${call} within its own handler body`,
+        );
+      }
+    }
+  });
+
+  test("the pin direction is negated, so the same handler serves both", () => {
+    // `api.pinSession(session.id, !session.pinned)` — the negation is the
+    // toggle. A handler that always sent `true` would pin an already
+    // pinned row, and the menu would look like it worked.
+    assert.ok(
+      treeSrc.includes("api.pinSession(session.id, !session.pinned)"),
+      "the pin call must negate the current state",
+    );
+  });
+
+  test("every action refreshes the tree through the shared onChanged", () => {
+    // A pin or an archive that did not re-read the tree would leave the
+    // sidebar showing the old state until some unrelated refresh fired —
+    // the user clicks 归档 and the row is still there.
+    for (const call of ["api.pinSession", "api.archiveSession"]) {
+      const at = treeSrc.indexOf(call);
+      const slice = treeSrc.slice(at, at + 200);
+      assert.ok(slice.includes("onChanged"), `${call} must refresh the tree`);
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 3. The two honest placeholders
+// ---------------------------------------------------------------------------
+
+describe("PB-1 — the two placeholders that stay", () => {
+  test("复制到新工作树 stays disabled, and the reason names the missing REFERENCE", () => {
+    const at = treeSrc.indexOf('key: "fork-worktree"');
+    assert.notEqual(at, -1, "the worktree fork row must still exist — removing it is not the same as honest-placeholdering it");
+    const row = treeSrc.slice(at, at + 700);
+    assert.ok(row.includes("disabled: true"), "the worktree fork stays disabled");
+    // The distinguishing assertion. The old comment said "no worktree-fork
+    // contract yet", which was FALSE — the engine has the method and the
+    // eligibility fields. The reason is the absent desktop reference, and
+    // a comment that says so is what stops the next reader from
+    // re-deriving the wrong conclusion and "fixing" it by wiring a flag.
+    assert.match(row, /reference/i);
+    assert.ok(
+      !row.includes("no worktree-fork contract yet"),
+      "the stale 'no contract' reason must be gone",
+    );
+  });
+
+  test("the worktree eligibility fields are carried, not dropped", () => {
+    // The narrowing that discarded them would force the batch that
+    // unblocks the worktree item to re-derive three fields the engine
+    // already sends. They are typed on the client and present in the
+    // server's projection.
+    assert.ok(apiSrc.includes("worktree: { visible: boolean; eligible: boolean"), "client type carries the triple");
+    assert.ok(
+      apiSrc.includes("carried through untouched") || apiSrc.includes("The engine's worktree eligibility"),
+      "the client type documents why the fields are unread",
+    );
+  });
+
+  test("the project-level 归档对话 stays disabled with an accurate reason", () => {
+    // Scoped to the PROJECT menu, which is the one that carries a
+    // `MenuRow` label. A session-menu slice would be a different item
+    // entirely and the assertion would be about the wrong code.
+    // Anchored on the row's OWN `key:` token, reached by scanning
+    // backwards from its label. Anchoring 400 chars before the label
+    // would reach into the 在文件夹中显示 row above it, whose
+    // `common.notLocal` is correct and must not be confused with this
+    // one's — which is the same trap as the session/project `key: "pin"`
+    // collision above, in the other direction.
+    const label = treeSrc.indexOf('t("projectMenu.archive")');
+    assert.notEqual(label, -1, "the project archive row must still exist");
+    const at = treeSrc.lastIndexOf('key: "archive"', label);
+    assert.notEqual(at, -1, "the project archive row key must still exist");
+    const row = treeSrc.slice(at, label + 1200);
+    assert.ok(row.includes("disabled: true"), "project bulk archive stays disabled");
+    assert.ok(row.includes('t("projectMenu.archiveUnavailable")'));
+    assert.ok(
+      !row.includes('t("common.notLocal")'),
+      "the wrong `common.notLocal` reason must be gone from the project archive item",
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 4. The fork dialog
+// ---------------------------------------------------------------------------
+
+describe("PB-1 — the 复制为新会话 dialog", () => {
+  const dialog = treeSrc.slice(
+    treeSrc.indexOf("function SessionForkDialog"),
+    treeSrc.indexOf("const SESSION_STATE_MARK"),
+  );
+
+  test("the confirm button is gated on the ENGINE's canFork, not on having loaded", () => {
+    // A dialog whose confirm is live as soon as the fetch resolves — or
+    // before it does — forks on a guess. The three-way condition is the
+    // whole point: the user may only fork what the engine said it could
+    // fork, and may not fork while the answer is still in flight.
+    assert.ok(dialog.includes("disabled={forking || loading || !canFork}"), "confirm gated on fork/load/canFork");
+    assert.ok(dialog.includes("options?.ok === true && options.canFork === true"), "canFork is a strict read");
+  });
+
+  test("a failed options READ is not rendered as canFork:false", () => {
+    // The distinction the dialog exists to preserve: "the engine refused"
+    // and "we could not ask" are different sentences. A catch that set
+    // `canFork: false` would put the second on screen as the first.
+    assert.ok(dialog.includes('data-testid="session-fork-unavailable"'), "an unreadable answer has its own state");
+    assert.ok(dialog.includes("reportActionError"), "a failed read reports rather than renders a refusal");
+  });
+
+  test("the suggested title is SHOWN before the fork, because the server forces it", () => {
+    // `useSuggestedTitle: true` is forced server-side, so the dialog
+    // showing it is not a courtesy — it is the only way the user learns
+    // what the new session will be called before it exists.
+    assert.ok(dialog.includes("answer.suggestedTitle"), "the suggestion is rendered");
+    assert.ok(dialog.includes("sessionMenu.forkSuggested"), "with the key that names it");
+  });
+
+  test("the dialog does not render a worktree row", () => {
+    // A greyed worktree row in the dialog would be a SECOND
+    // reference-free form. The discipline this batch follows is that an
+    // item with no reference stays a single greyed menu row.
+    assert.ok(!dialog.includes("worktree.eligible"), "the dialog must not read the worktree fields");
+    assert.ok(!dialog.includes("forkWorktree"), "the dialog must not mention the worktree item");
+  });
+
+  test("a stale answer from a previously opened row is not shown", () => {
+    // The dialog is mounted per row, but React can re-render it against a
+    // changed prop between open and the fetch resolving. `loadedFor` is
+    // what stops row B from displaying row A's answer for those frames.
+    assert.ok(dialog.includes("loadedFor"), "the answer is keyed by the id it describes");
+    assert.ok(dialog.includes("loadedFor === sessionId"), "and the render checks that key");
+  });
+
+  test("a successful fork switches to the new session", () => {
+    // A duplicate the user cannot navigate to is a duplicate they have to
+    // go find afterwards.
+    assert.ok(dialog.includes("onForked(forked.id)"), "the new id is handed back");
+    assert.ok(
+      treeSrc.includes("void openSessionAndReportLanding(newSessionId, onChanged, t)"),
+      "and the tree switches to it",
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 5. The API client
+// ---------------------------------------------------------------------------
+
+describe("PB-1 — the API client", () => {
+  test("the four calls hit the four routes, verb-first and id-encoded", () => {
+    for (const [fn, method, verb] of [
+      ["archiveSession", "POST", "archive"],
+      ["pinSession", "POST", "pin"],
+      ["forkSession", "POST", "fork"],
+    ] as const) {
+      const at = apiSrc.indexOf(`export const ${fn} = `);
+      assert.notEqual(at, -1, `${fn} is missing from api.ts`);
+      const slice = apiSrc.slice(at, at + 400);
+      assert.ok(
+        slice.includes(`/api/sessions/\${encodeURIComponent(id)}/${verb}`),
+        `${fn} must target /${verb}`,
+      );
+      assert.ok(slice.includes(`method: "${method}"`), `${fn} must be a ${method}`);
+    }
+    const at = apiSrc.indexOf("export const getSessionForkOptions");
+    assert.notEqual(at, -1, "getSessionForkOptions is missing");
+    assert.ok(apiSrc.slice(at, at + 400).includes("fork-options"));
+  });
+
+  test("archive defaults to archiving, and pin has no default", () => {
+    // The asymmetry is deliberate and is the engine's own: `archiveSession`
+    // reads `req.archived !== false` so a missing flag archives, while
+    // `pinSession` takes the flag positionally and branches on it, so a
+    // defaulted one would move the row in a direction the user did not
+    // pick.
+    assert.ok(apiSrc.includes("archiveSession = (id: string, archived = true)"));
+    assert.ok(apiSrc.includes("pinSession = (id: string, pinned: boolean)"));
+  });
+
+  test("TreeSession.pinned is declared as a required boolean", () => {
+    // Required, not optional: the server writes it on every session, and
+    // a `pinned?: boolean` client type is an invitation to write
+    // `if (session.pinned)` where `undefined` silently means false.
+    const at = apiSrc.indexOf("export interface TreeSession");
+    const slice = apiSrc.slice(at, at + 900);
+    assert.ok(slice.includes("pinned: boolean;"), "pinned is a required boolean");
+    assert.ok(!slice.includes("pinned?:"), "pinned must not be optional");
+  });
+
+  test("the tree payload declares how the pin overlay resolved", () => {
+    // `pins.degraded` is what tells "nothing is pinned" from "we could
+    // not ask". Without the field the sidebar cannot tell, and an outage
+    // renders as an empty pin section that reads as a fact about the user.
+    assert.ok(apiSrc.includes("pins?: { pinnedIds: string[]; degraded: boolean; reason: string | null }"));
+  });
+});
diff --git a/packages/webui/webapp/test/shell-elements-parity.test.ts b/packages/webui/webapp/test/shell-elements-parity.test.ts
index 549fc9ff..8b8b3e17 100644
--- a/packages/webui/webapp/test/shell-elements-parity.test.ts
+++ b/packages/webui/webapp/test/shell-elements-parity.test.ts
@@ -185,13 +185,38 @@ describe("55c project context menu (session-tree.tsx, ref-26)", () => {
     }
   });
 
-  test("reveal / archive are disabled with the notLocal marker", () => {
-    for (const key of ["reveal", "archive"]) {
-      const at = src.indexOf(`key: "${key}"`);
-      const slice = src.slice(at, at + 700);
-      assert.ok(slice.includes("disabled: true"), `${key} disabled`);
-      assert.ok(slice.includes('t("common.notLocal")'), `${key} notLocal marker`);
-    }
+  test("reveal keeps the notLocal marker; archive gets its own accurate reason", () => {
+    // `reveal` is unchanged: 在文件夹中显示 is not a webui capability at
+    // all, and `common.notLocal` still describes it correctly.
+    const atReveal = src.indexOf('key: "reveal"');
+    const reveal = src.slice(atReveal, atReveal + 700);
+    assert.ok(reveal.includes("disabled: true"), "reveal disabled");
+    assert.ok(reveal.includes('t("common.notLocal")'), "reveal notLocal marker");
+
+    // `archive` is CHANGED by PB-1, and deliberately. The old expectation
+    // asserted `common.notLocal`, which was wrong twice over: it claimed
+    // the local build lacks a capability it has always had (the
+    // SESSION-level 归档 in the same file is now live and calls
+    // `archiveSession`), and it said nothing about what is actually
+    // missing. What is missing is a project-SCOPED bulk archive — v2
+    // declares `archiveSession({id, archived})` for one session and
+    // nothing project-wide — so the item keeps its `disabled: true` and
+    // gains a tooltip that says so. Both halves are asserted: an item
+    // that silently stopped being disabled, and an item that stayed
+    // disabled for a reason that is no longer true, are the two ways this
+    // drifts.
+    const atArchive = src.indexOf('key: "archive"');
+    const archive = src.slice(atArchive, atArchive + 1600);
+    const marker = 't("projectMenu.archiveUnavailable")';
+    assert.ok(archive.includes("disabled: true"), "archive stays disabled");
+    assert.ok(
+      archive.includes(marker),
+      "archive's disabled reason must name the missing project-scoped bulk archive",
+    );
+    assert.ok(
+      !archive.slice(0, archive.indexOf(marker)).includes('t("common.notLocal")'),
+      "archive must no longer claim the local build lacks archiving",
+    );
   });
 
   test("remove is the danger row and batch-deletes behind a confirm", () => {
diff --git a/release/public-source.json b/release/public-source.json
index 4ae6b638..01f886ba 100644
--- a/release/public-source.json
+++ b/release/public-source.json
@@ -3467,6 +3467,7 @@
     "packages/webui/server/engine/providers/local-runtime-v2.capabilities.js",
     "packages/webui/server/engine/providers/local-runtime-v2.js",
     "packages/webui/server/engine/providers/tui-runtime-adapter.js",
+    "packages/webui/server/engine/session-context-actions.js",
     "packages/webui/server/engine/session-delete.js",
     "packages/webui/server/engine/session-export.js",
     "packages/webui/server/engine/session-load.js",
@@ -3627,6 +3628,7 @@
     "packages/webui/test/lib/engine/provider-store-ownership.test.js",
     "packages/webui/test/lib/engine/provider-store.test.js",
     "packages/webui/test/lib/engine/provider-writes.test.js",
+    "packages/webui/test/lib/engine/session-context-actions.test.js",
     "packages/webui/test/lib/engine/session-delete-ownership.test.js",
     "packages/webui/test/lib/engine/session-export.test.js",
     "packages/webui/test/lib/engine/session-load.test.js",
@@ -3652,6 +3654,7 @@
     "packages/webui/test/lib/mcode-acp-note.test.js",
     "packages/webui/test/lib/mcode-acp-ownership.check.mjs",
     "packages/webui/test/lib/mcode-acp-tc-marker.test.js",
+    "packages/webui/test/lib/mcode-exec-stream.test.js",
     "packages/webui/test/lib/mcode-exec.test.js",
     "packages/webui/test/lib/mcode-rpc-live-lookup.test.js",
     "packages/webui/test/lib/mcode-rpc.check.mjs",
@@ -3740,6 +3743,7 @@
     "packages/webui/test/server/runtime-host.test.js",
     "packages/webui/test/server/send-run-guard.test.js",
     "packages/webui/test/server/server-startup.test.js",
+    "packages/webui/test/server/session-context-actions-host.test.js",
     "packages/webui/test/server/state-snapshot-no-chat.test.js",
     "packages/webui/test/server/stream-cumulative-render.test.js",
     "packages/webui/test/tooling/check-docs-alignment.test.js",
@@ -3987,6 +3991,7 @@
     "packages/webui/webapp/test/markdown-code-wrap.test.ts",
     "packages/webui/webapp/test/markdown-html-render.test.ts",
     "packages/webui/webapp/test/markdown-math.test.ts",
+    "packages/webui/webapp/test/markdown-raw-html.test.ts",
     "packages/webui/webapp/test/markdown-registry.test.ts",
     "packages/webui/webapp/test/markdown-toc.test.ts",
     "packages/webui/webapp/test/markdown.test.ts",
@@ -3999,6 +4004,7 @@
     "packages/webui/webapp/test/provider-management.test.ts",
     "packages/webui/webapp/test/send-busy-state.test.ts",
     "packages/webui/webapp/test/send-confirmation.test.ts",
+    "packages/webui/webapp/test/session-context-actions.test.ts",
     "packages/webui/webapp/test/session-row-hover-tray.test.ts",
     "packages/webui/webapp/test/session-switch-visibility.test.ts",
     "packages/webui/webapp/test/settings-extra-pages.test.ts",
diff --git a/scripts/test-tmp-leak.check.mjs b/scripts/test-tmp-leak.check.mjs
index e9c7a3a4..bb8b3a1d 100644
--- a/scripts/test-tmp-leak.check.mjs
+++ b/scripts/test-tmp-leak.check.mjs
@@ -229,6 +229,7 @@ const KNOWN_PREFIXES = [
   "mcode-exec-nosibling-",
   "mcode-exec-plain-",
   "mcode-exec-posix-",
+  "mcode-exec-stream-",
   "mcode-exec-test-",
   "mcode-resolver-bad-",
   "mcode-resolver-empty-",
@@ -353,6 +354,13 @@ const KNOWN_PREFIXES = [
   // that prefix, its children need their own.
   "pb8-svc-",
   "pb8-svc-shape-",
+  // PB-1's real-host suite (`test/server/session-context-actions-host.test.js`).
+  // Same runtime, same better-sqlite3 fd profile as the two above, so it
+  // reuses their parent and needs its own child prefix — which is exactly
+  // what this registry is for: a new suite that boots a host without
+  // registering its prefix fails `test:release-tools` rather than leaking
+  // silently, and the reverse scan below is what keeps the two in step.
+  "pb1-host-",
   "webui-t36-engine-",
   // Catch-all prefixes (last — matching stops on the first prefix that
   // matches, so every entry above this point wins over these). Round-3