iterate-plugin 3.13.0 → 3.14.0

package/README.md

@@ -114,6 +114,7 @@ Both modes share:
 - **ProgressCapsule** (`shell.overlay`) — popup notification on each round completion / convergence (incl. convergence confirm).
 - **SettingsPanel** (`settings.section`) — theme toggle, triage-persistence notes, config-management guide (covers `validation.commands` / `language` / `personalization.known_intentional` with an explicit "empty validation.commands = unprotected" warning; a field picker generates the matching `iterate_config write` instruction), **v3.7: a 回读当前配置 (read back current config) button that closes the write → read-back loop** — it copies an `iterate_config read` instruction and, once the model echoes the result into the session, shows the current value of the selected field, runtime status overview (artifact layout + view/cleanup tool guide + disk-snapshot pull), one-click triage data reset.
 - **Bilingual UI (v3.7)** — every piece of UI chrome (panels, empty states, tabs, badges, settings, stop-reason and completion labels) ships in 简体中文 and English. Pick the language under **Settings → 界面语言 / Interface language**; the choice persists in `localStorage` (`iterate-ui-lang`) and otherwise auto-detects from `navigator.language` (a stored choice always wins, and auto-detection never writes a preference). **Model-facing copy deliberately stays Chinese** — the `build*Instruction` payloads and the copy-paste guides are contract text mirroring `SKILL.md`, so the two expanded guides carry a 「中文（粘贴给模型的契约文案）」 chip instead of looking like a missed translation.
+- **Right-click menu (v3.14, dsh ≥ 0.2.2-alpha.3)** — the iterate entry points now also hang off the **native unified context menus**: right-click a **Session** in the sidebar to `打开 iterate 质量指挥中心` (expands the docked observatory and jumps to the live stream), copy the preflight / dry-run / checkpoint-resume / disk-snapshot instructions, or right-click a **file** (with line) / **directory** to copy a *scoped* dry-run review instruction. Bilingual labels, copy-failure recovery guidance, and a shared success toast; a host without `contextMenus` degrades to no menu items (the docked panel remains the entry point).
 
 The UI layer is **defensive by design**: it degrades gracefully if any of `slots` / `theme` / `React` is unavailable — it never crashes the client.
 
@@ -346,14 +347,13 @@ All runtime state lives under `.iterate/` at the project root (can be excluded v
   `0.1.7-alpha.1`, `0.1.7-alpha.2`, `0.1.7-rc.1`, `0.1.7-rc.2`, `0.2.0-rc.1`,
   `0.2.0-rc.2`, `0.2.1-alpha.1`, `0.2.1-alpha.2`, `0.2.1-alpha.3`,
   `0.2.1-alpha.4`, `0.2.1-alpha.5`, `0.2.1-rc.1`, `0.2.1-rc.2`,
-   `0.2.1-rc.3`, `0.2.1-rc.4`, `0.2.1-rc.5`, `0.2.2-alpha.2` (28 releases,
-  `0.1.1-rc.1` …
-  `0.2.2-alpha.2`).
+   `0.2.1-rc.3`, `0.2.1-rc.4`, `0.2.1-rc.5`, `0.2.2-alpha.2`,
+  `0.2.2-alpha.3` (29 releases, `0.1.1-rc.1` … `0.2.2-alpha.3`).
   The plugin is built against `@deepseek-ai/dsh-tools` /
-  `@deepseek-ai/dsh-util-values` `0.2.2-alpha.2` and uses only public contracts
+  `@deepseek-ai/dsh-util-values` `0.2.2-alpha.3` and uses only public contracts
   (tool registration, client slots + theme, bundle patch, and — since v3.9 —
   the session state-record API for session-linked run records).
-  It also declares `engines.dsh` (`>=0.1.1-rc.1`) so the dsh ≥ 0.2.2-alpha.2
+  It also declares `engines.dsh` (`>=0.1.1-rc.1`) so the dsh ≥ 0.2.2-alpha.3
   runtime evaluates compatibility from that single range (earlier runtimes fall
   back to the `@deepseek-ai/dsh-*` peer versions listed in `package.json`).
 - **Disposable-Profile evidence (real, `dsh` CLI `0.1.1-rc.1`)**: on a temp

package/README.zh-CN.md

@@ -113,6 +113,7 @@ dsh plugin --profile web add iterate-plugin
 - **进度胶囊 `ProgressCapsule`**（`shell.overlay`）— 每轮完成 / 收敛时右下角弹出通知（含收敛确认）。
 - **iterate 设置区 `SettingsPanel`**（`settings.section`）— 主题开关、分诊持久化说明、配置管理指引（覆盖 `validation.commands` / `language` / `personalization.known_intentional`，并显式警告"validation.commands 为空 = 本轮不受任何测试保护"；字段选择器可生成对应的 `iterate_config write` 指令），**v3.7：新增「回读当前配置」补齐写入 → 回读闭环**——复制 `iterate_config read` 指令，模型把结果回显进会话后，卡片就地展示所选字段的当前值；运行时状态概览（产物布局 + 查看/清理工具指引 + 磁盘快照拉取）、一键清空分诊数据。
 - **双语 UI（v3.7）**——所有界面文案（面板、空态、页签、徽标、设置、停止原因与完成汇总）均提供简体中文与 English。在**设置 → 界面语言 / Interface language**切换；选择持久化在 `localStorage`（`iterate-ui-lang`），否则按 `navigator.language` 自动探测（已保存的选择始终优先，且自动探测不会写入偏好）。**面向模型的文案有意保持中文**——`build*Instruction` 指令与可粘贴指引是与 `SKILL.md` 对齐的契约文本，因此两处展开的指引带「中文（粘贴给模型的契约文案）」标签，避免被误当成漏翻。
+- **右键菜单（v3.14，dsh ≥ 0.2.2-alpha.3）**——iterate 入口现在也挂在**原生统一右键菜单**上：右键侧边栏的**会话**可 `打开 iterate 质量指挥中心`（展开停靠观测台并跳到实时流）、复制预检 / dry-run / 断点恢复 / 磁盘快照指令；右键**文件**（带行号）/ **目录**可复制**定向** dry-run 审查指令（仅审查该文件/目录）。双语标签、复制失败的自救指引、共享成功 toast；宿主无 `contextMenus` 时降级为无菜单项（停靠面板仍是入口）。
 
 UI 层为**防御式设计**：`slots` / `theme` / `React` 任一不可用时自动降级，不会崩溃客户端。
 
@@ -336,7 +337,7 @@ validation:
 ### Node.js / DSH 兼容范围
 
 - **Node.js**：`>=20`（`package.json` 的 `engines.node`）。
-- **DSH**：`package.json` 的 `dsh.compatibility.dshReleases` 字段是发布兼容性的**唯一真源**（本 README 逐字镜像该字段；两者需同步更新）。以下官方版本声明为 `compatible`：`0.1.1-rc.1`、`0.1.2-alpha.4`、`0.1.2-alpha.5`、`0.1.2-rc.1`、`0.1.3-alpha.1`、`0.1.5-alpha.1`、`0.1.5-alpha.2`、`0.1.5-rc.1`、`0.1.5-rc.2`、`0.1.6-alpha.1`、`0.1.6-alpha.2`、`0.1.7-alpha.1`、`0.1.7-alpha.2`、`0.1.7-rc.1`、`0.1.7-rc.2`、`0.2.0-rc.1`、`0.2.0-rc.2`、`0.2.1-alpha.1`、`0.2.1-alpha.2`、`0.2.1-alpha.3`、`0.2.1-alpha.4`、`0.2.1-alpha.5`、`0.2.1-rc.1`、`0.2.1-rc.2`、`0.2.1-rc.3`、`0.2.1-rc.4`、`0.2.1-rc.5`、`0.2.2-alpha.2`（共 28 个版本，`0.1.1-rc.1` … `0.2.2-alpha.2`）。插件基于 `@deepseek-ai/dsh-tools` / `@deepseek-ai/dsh-util-values` `0.2.2-alpha.2` 构建，只使用公开契约（工具注册、客户端 slots + theme、bundle patch，以及 v3.9 起的会话状态记录接口）。插件同时声明 `engines.dsh`（`>=0.1.1-rc.1`），使 dsh ≥ 0.2.2-alpha.2 运行时只依据该范围判断兼容性（更早的运行时仍回退校验 `package.json` 中列出的 `@deepseek-ai/dsh-*` peer 版本）。
+- **DSH**：`package.json` 的 `dsh.compatibility.dshReleases` 字段是发布兼容性的**唯一真源**（本 README 逐字镜像该字段；两者需同步更新）。以下官方版本声明为 `compatible`：`0.1.1-rc.1`、`0.1.2-alpha.4`、`0.1.2-alpha.5`、`0.1.2-rc.1`、`0.1.3-alpha.1`、`0.1.5-alpha.1`、`0.1.5-alpha.2`、`0.1.5-rc.1`、`0.1.5-rc.2`、`0.1.6-alpha.1`、`0.1.6-alpha.2`、`0.1.7-alpha.1`、`0.1.7-alpha.2`、`0.1.7-rc.1`、`0.1.7-rc.2`、`0.2.0-rc.1`、`0.2.0-rc.2`、`0.2.1-alpha.1`、`0.2.1-alpha.2`、`0.2.1-alpha.3`、`0.2.1-alpha.4`、`0.2.1-alpha.5`、`0.2.1-rc.1`、`0.2.1-rc.2`、`0.2.1-rc.3`、`0.2.1-rc.4`、`0.2.1-rc.5`、`0.2.2-alpha.2`、`0.2.2-alpha.3`（共 29 个版本，`0.1.1-rc.1` … `0.2.2-alpha.3`）。插件基于 `@deepseek-ai/dsh-tools` / `@deepseek-ai/dsh-util-values` `0.2.2-alpha.3` 构建，只使用公开契约（工具注册、客户端 slots + theme、bundle patch，以及 v3.9 起的会话状态记录接口）。插件同时声明 `engines.dsh`（`>=0.1.1-rc.1`），使 dsh ≥ 0.2.2-alpha.3 运行时只依据该范围判断兼容性（更早的运行时仍回退校验 `package.json` 中列出的 `@deepseek-ai/dsh-*` peer 版本）。
 - **一次性 Profile 证据（真实，`dsh` CLI `0.1.1-rc.1`）**：在临时 `$DSH_HOME` 下
   `dsh plugin --profile <p> add <本仓库>` 约 449ms 完成安装；`dsh --profile <p>
   --dump-config` 正确合成 `iterate-plugin` bundle patch；`dsh plugin --profile <p>

package/lib/client.js

@@ -1,4 +1,4 @@
-/* iterate-plugin client source-digest: 909db487a440ae131a6de59f253a9d84b240e5fbd55bce9ae83a9876b711a9a2 */
+/* iterate-plugin client source-digest: 5b22267e6de6fb0564d60874b3de1211755cdeb398f6c7ffa87dfa1007e6796f */
 window.__ModuleLoader__.load({ id: "iterate-plugin", factory: (require) => {
 var module = { exports: {} };
 var exports = module.exports;
@@ -1250,6 +1250,13 @@ var START_INSTRUCTIONS = {
   full: START_INSTRUCTION_FULL,
   reviewOnly: START_INSTRUCTION_REVIEW_ONLY
 };
+function buildScopedReviewInstruction(scope) {
+  const hasFile = scope && typeof scope.file === "string" && scope.file.length > 0;
+  const hasDir = !hasFile && scope && typeof scope.dir === "string" && scope.dir.length > 0;
+  if (!hasFile && !hasDir) return "";
+  const subject = hasFile ? `\u6587\u4EF6 \`${scope.file}\`${typeof scope.line === "number" && scope.line > 0 ? `\uFF08\u7B2C ${scope.line} \u884C\uFF09` : ""}` : `\u76EE\u5F55 \`${scope.dir}\``;
+  return `\u5F00\u59CB\u4E00\u6B21\u4EC5\u8BC4\u5BA1\uFF08dry-run\uFF0C\u4E0D\u4FEE\u6539\u4EFB\u4F55\u6587\u4EF6\uFF09\uFF0C\u5BA1\u67E5\u8303\u56F4\u9650\u5B9A\u5728${subject}\uFF1A\u8BF7\u8C03\u7528 \`workflow\` \u5DE5\u5177\u8FD0\u884C iterate \u5DE5\u4F5C\u6D41\uFF0Cmode: "dry-run"\uFF0C\u6309\u7CFB\u7EDF\u63D0\u793A\u7684 Iterate Workflow \u6267\u884C plan \u2192 \u8BC4\u5BA1 \u2192 \u5206\u8BCA \u2192 \`iterate_review aggregate\` / \`meta-review\` \u7EC8\u62A5\u5E76 \`iterate_transcript\` capture\uFF1B\u8BC4\u5BA1\u65F6\u628A\u8303\u56F4\u9650\u5B9A\u5728${subject}\uFF0C\u5176\u4F59\u6587\u4EF6\u4EC5\u4F5C\u4E0A\u4E0B\u6587\u3001\u4E0D\u5F97\u7ED9\u51FA\u4FEE\u590D\u3002\u5168\u7A0B\u4E0D\u8981\u8C03\u7528 \`iterate_fix\` / \`iterate_rollback\`\u3002`;
+}
 function fixFindingPayload(finding) {
   const f = finding && typeof finding === "object" ? finding : {};
   const file = String(f.file ?? "");
@@ -2858,6 +2865,135 @@ function subscribeSession(listener) {
   };
 }
 
+// src/client/context-menu.ts
+var OBS_OPEN_EVENT = "iterate-plugin:open-observatory";
+function openObservatory(detail) {
+  if (typeof window === "undefined" || typeof window.dispatchEvent !== "function") return false;
+  try {
+    window.dispatchEvent(new CustomEvent(OBS_OPEN_EVENT, { detail: detail ?? {} }));
+    return true;
+  } catch {
+    return false;
+  }
+}
+var LABELS = {
+  "iterate.open-panel": { zh: "\u6253\u5F00 iterate \u8D28\u91CF\u6307\u6325\u4E2D\u5FC3", en: "Open iterate command center" },
+  "iterate.preflight": { zh: "\u590D\u5236\u5F00\u8DD1\u9884\u68C0\u6307\u4EE4", en: "Copy preflight instruction" },
+  "iterate.dry-run": { zh: "\u590D\u5236 dry-run \u5BA1\u67E5\u6307\u4EE4", en: "Copy dry-run review instruction" },
+  "iterate.resume": { zh: "\u590D\u5236\u65AD\u70B9\u6062\u590D\u6307\u4EE4", en: "Copy checkpoint-resume instruction" },
+  "iterate.pull": { zh: "\u590D\u5236\u62C9\u53D6\u78C1\u76D8\u5FEB\u7167\u6307\u4EE4", en: "Copy disk-snapshot pull instruction" },
+  "iterate.review-file": { zh: "\u590D\u5236\u300C\u4EC5\u5BA1\u67E5\u6B64\u6587\u4EF6\u300D\u6307\u4EE4", en: 'Copy "review this file only" instruction' },
+  "iterate.review-dir": { zh: "\u590D\u5236\u300C\u4EC5\u5BA1\u67E5\u6B64\u76EE\u5F55\u300D\u6307\u4EE4", en: 'Copy "review this directory only" instruction' }
+};
+function pick(id, lang) {
+  const entry = LABELS[id];
+  if (!entry) return id;
+  return lang === "zh" ? entry.zh : entry.en;
+}
+var COPY_FAILURE = {
+  zh: "\u590D\u5236\u5931\u8D25\uFF1A\u526A\u8D34\u677F\u88AB\u62D2\u7EDD\u3002\u8BF7\u6539\u4E3A\u5728\u89C2\u6D4B\u53F0\u9762\u677F\u91CC\u7528\u540C\u4E00\u6307\u4EE4\u7684\u300C\u590D\u5236\u300D\u6309\u94AE\uFF0C\u6216\u624B\u52A8\u9009\u4E2D\u6307\u4EE4\u6587\u672C\u590D\u5236\u3002",
+  en: 'Copy failed: clipboard denied. Use the matching "Copy" button in the observatory panel, or select the instruction text manually.'
+};
+function buildSessionMenuEntries(lang, opts) {
+  return [
+    { id: "iterate.open-panel", label: pick("iterate.open-panel", lang), openTab: "live" },
+    { id: "iterate.preflight", label: pick("iterate.preflight", lang), separatorBefore: true },
+    { id: "iterate.dry-run", label: pick("iterate.dry-run", lang) },
+    { id: "iterate.resume", label: pick("iterate.resume", lang), disabled: opts?.hasCheckpoint === false },
+    { id: "iterate.pull", label: pick("iterate.pull", lang), separatorBefore: true }
+  ];
+}
+function buildFileMenuEntries(lang) {
+  return [
+    { id: "iterate.review-file", label: pick("iterate.review-file", lang) },
+    { id: "iterate.open-panel", label: pick("iterate.open-panel", lang) }
+  ];
+}
+function buildDirectoryMenuEntries(lang) {
+  return [
+    { id: "iterate.review-dir", label: pick("iterate.review-dir", lang) },
+    { id: "iterate.preflight", label: pick("iterate.preflight", lang), separatorBefore: true },
+    { id: "iterate.open-panel", label: pick("iterate.open-panel", lang) }
+  ];
+}
+function toAction(entry, deps, lang) {
+  const action = {
+    id: entry.id,
+    label: entry.label,
+    danger: entry.danger,
+    separatorBefore: entry.separatorBefore
+  };
+  if (entry.disabled) action.disabled = true;
+  if (entry.openTab) {
+    action.run = () => {
+      deps.openPanel({ tab: entry.openTab });
+      deps.notify(lang === "zh" ? "\u5DF2\u6253\u5F00 iterate \u89C2\u6D4B\u53F0\u3002" : "Iterate observatory opened.", true);
+    };
+    return action;
+  }
+  if (entry.instruction) {
+    const text = entry.instruction;
+    const failureLabel = COPY_FAILURE[lang];
+    action.failureLabel = failureLabel;
+    action.run = async () => {
+      const ok = await deps.copy(text);
+      if (!ok) throw new Error(failureLabel);
+      deps.notify(lang === "zh" ? "\u6307\u4EE4\u5DF2\u590D\u5236\uFF0C\u7C98\u8D34\u7ED9\u6A21\u578B\u5373\u53EF\u3002" : "Instruction copied \u2014 paste it to the model.", true);
+    };
+  }
+  return action;
+}
+function registerIterateContextMenus(service, deps, instructionByEntry) {
+  const unregister = [];
+  const register = (target, order, build) => {
+    try {
+      const dispose = service.register({
+        id: `iterate-plugin.${target}`,
+        target,
+        order,
+        resolve: (t2, _signal) => {
+          const lang = getLang();
+          return build(lang, t2).map((entry) => {
+            const full = { ...entry, instruction: entry.instruction ?? instructionByEntry(entry.id) };
+            return toAction(full, deps, lang);
+          });
+        }
+      });
+      unregister.push(dispose);
+    } catch (err) {
+      if (typeof console !== "undefined" && typeof console.error === "function") {
+        console.error("[iterate-ui] context-menu registration failed for target", target, err);
+      }
+    }
+  };
+  register("session", 300, (_lang, t2) => {
+    const target = t2;
+    return buildSessionMenuEntries(getLang(), { hasCheckpoint: target?.value?.sessionId ? true : void 0 });
+  });
+  register("file", 300, (_lang, t2) => {
+    const target = t2;
+    return buildFileMenuEntries(getLang()).map((e) => ({
+      ...e,
+      instruction: e.id === "iterate.review-file" ? instructionByEntry(`file:${target?.value?.path ?? ""}${typeof target?.value?.line === "number" ? `:${target.value.line}` : ""}`) : e.instruction
+    }));
+  });
+  register("directory", 300, (_lang, t2) => {
+    const target = t2;
+    return buildDirectoryMenuEntries(getLang()).map((e) => ({
+      ...e,
+      instruction: e.id === "iterate.review-dir" ? instructionByEntry(`dir:${target?.value?.path ?? ""}`) : e.instruction
+    }));
+  });
+  return () => {
+    for (const dispose of unregister.splice(0)) {
+      try {
+        dispose();
+      } catch {
+      }
+    }
+  };
+}
+
 // src/client/index.ts
 var React = require("react");
 var name = "iterate-plugin";
@@ -3294,12 +3430,42 @@ function readTheme(ctx) {
   }
   return void 0;
 }
+function readContextMenus(ctx) {
+  if (!ctx || typeof ctx.get !== "function") return void 0;
+  const raw = ctx.get("contextMenus", false);
+  if (!raw || typeof raw !== "object") return void 0;
+  const svc = raw;
+  if (typeof svc.register !== "function") return void 0;
+  if (typeof svc.notify !== "function") return void 0;
+  return svc;
+}
+function sessionIdOfSession(session) {
+  if (!session || typeof session !== "object") return null;
+  const s = session;
+  const candidates = [
+    s.sessionId,
+    s.id,
+    s.header,
+    s.session
+  ];
+  for (const c of candidates) {
+    if (typeof c === "string" && c) return c;
+    if (c && typeof c === "object") {
+      const o = c;
+      for (const k of ["sessionId", "id"]) {
+        if (typeof o[k] === "string" && o[k]) return o[k];
+      }
+    }
+  }
+  return null;
+}
 var slotsSvc = void 0;
 var themeSvc = void 0;
 var storage2 = null;
 var themeDisposer = null;
 var themeListener = null;
 var themeEnabled = true;
+var menuDisposer = null;
 var roundPulseListeners = [];
 function emitRoundPulse(round, converged) {
   const payload = { round, converged: converged === true };
@@ -4607,6 +4773,21 @@ function ObservatoryPanel(props) {
     doc.addEventListener("keydown", onKeyDown);
     return () => doc.removeEventListener("keydown", onKeyDown);
   }, [open]);
+  const panelSessionId = sessionIdOfSession(session);
+  React.useEffect(() => {
+    if (typeof window === "undefined" || typeof window.addEventListener !== "function") return;
+    const onOpen = (ev) => {
+      const detail = ev.detail;
+      const detailSession = detail && typeof detail.sessionId === "string" && detail.sessionId ? detail.sessionId : null;
+      if (detailSession && panelSessionId && detailSession !== panelSessionId) return;
+      setOpen(true);
+      const target = detail && typeof detail.tab === "string" ? detail.tab : "live";
+      const valid = OBS_TABS.some((x) => x.key === target);
+      setTab(valid ? target : "live");
+    };
+    window.addEventListener(OBS_OPEN_EVENT, onOpen);
+    return () => window.removeEventListener(OBS_OPEN_EVENT, onOpen);
+  }, [panelSessionId]);
   const copyInstruction = (key, text) => {
     if (!text) return;
     copyText(text).then((ok) => {
@@ -6217,6 +6398,54 @@ function apply(ctx) {
       )
     );
   }
+  {
+    const menuSvc = readContextMenus(ctx);
+    if (menuSvc) {
+      const instructionByEntry = (id) => {
+        if (id === "iterate.preflight") return buildPreflightInstruction();
+        if (id === "iterate.dry-run") return START_INSTRUCTIONS.reviewOnly;
+        if (id === "iterate.resume") return buildCheckpointResumeInstruction();
+        if (id === "iterate.pull") return buildDiskSnapshotInstruction();
+        if (id.startsWith("file:")) {
+          const rest = id.slice("file:".length);
+          const colon = rest.lastIndexOf(":");
+          const path = colon > 0 ? rest.slice(0, colon) : rest;
+          const line = colon > 0 ? Number(rest.slice(colon + 1)) : void 0;
+          return buildScopedReviewInstruction({ file: path, ...Number.isInteger(line) && line > 0 ? { line } : {} });
+        }
+        if (id.startsWith("dir:")) return buildScopedReviewInstruction({ dir: id.slice("dir:".length) });
+        return "";
+      };
+      if (menuDisposer) {
+        try {
+          menuDisposer();
+        } catch {
+        }
+        menuDisposer = null;
+      }
+      menuDisposer = registerIterateContextMenus(
+        menuSvc,
+        {
+          copy: (text) => copyText(text),
+          openPanel: (detail) => {
+            openObservatory(detail);
+          },
+          notify: (text, success, action) => {
+            menuSvc.notify(text, success, action);
+          }
+        },
+        instructionByEntry
+      );
+      if (typeof ctx.effect === "function") {
+        ctx.effect(() => {
+          if (menuDisposer) {
+            menuDisposer();
+            menuDisposer = null;
+          }
+        });
+      }
+    }
+  }
   registerThemeListener(ctx);
 }
 return module.exports; } });

package/lib/parse.js

@@ -1788,6 +1788,34 @@ export const START_INSTRUCTIONS = {
   reviewOnly: START_INSTRUCTION_REVIEW_ONLY,
 }
 
+/**
+ * Scoped dry-run review instruction (right-click menu: file / directory).
+ *
+ * `iterate_review plan` has no per-call `scope` parameter, so a single-file or
+ * single-directory review is expressed as a directed instruction the model
+ * resolves through the `workflow` tool exactly like the full dry-run flow, but
+ * with the review scope explicitly narrowed to the clicked subject. The user
+ * never has to type the path themselves.
+ *
+ * @param {{ file?: string, line?: number, dir?: string }} scope
+ * @returns {string} empty when no scope is given (defensive; never throw)
+ */
+export function buildScopedReviewInstruction(scope) {
+  const hasFile = scope && typeof scope.file === 'string' && scope.file.length > 0
+  const hasDir = !hasFile && scope && typeof scope.dir === 'string' && scope.dir.length > 0
+  if (!hasFile && !hasDir) return ''
+  const subject = hasFile
+    ? `文件 \`${scope.file}\`${typeof scope.line === 'number' && scope.line > 0 ? `（第 ${scope.line} 行）` : ''}`
+    : `目录 \`${scope.dir}\``
+  return (
+    `开始一次仅评审（dry-run，不修改任何文件），审查范围限定在${subject}：` +
+    '请调用 `workflow` 工具运行 iterate 工作流，mode: "dry-run"，' +
+    `按系统提示的 Iterate Workflow 执行 plan → 评审 → 分诊 → \`iterate_review aggregate\` / \`meta-review\` 终报并 \`iterate_transcript\` capture；` +
+    `评审时把范围限定在${subject}，其余文件仅作上下文、不得给出修复。` +
+    '全程不要调用 `iterate_fix` / `iterate_rollback`。'
+  )
+}
+
 /** Normalize an arbitrary finding-ish node into the payload field set. */
 function fixFindingPayload(finding) {
   const f = finding && typeof finding === 'object' ? finding : {}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iterate-plugin",
-  "version": "3.13.0",
+  "version": "3.14.0",
   "description": "dsh plugin that turns the iterate skill into an autonomous closed-loop harness with quality command center and experience bank (v3.3). Features: plan -> parallel review xN -> atomic fixes -> validate -> loop -> auto-stop, plus dry-run pure-review mode, quality gate compute/persist, writable experience bank, defense events stream (record + bilingual labels), and native command buttons — with a live quality command center (F8/F9/F10 render real session data), §8 assign-fix instruction, and task_mode indicator wired end to end.",
   "type": "module",
   "license": "MIT",
@@ -55,7 +55,8 @@
         "0.2.1-rc.3": "compatible",
         "0.2.1-rc.4": "compatible",
         "0.2.1-rc.5": "compatible",
-        "0.2.2-alpha.2": "compatible"
+        "0.2.2-alpha.2": "compatible",
+        "0.2.2-alpha.3": "compatible"
       }
     },
     "client": {
@@ -96,10 +97,10 @@
     "js-yaml": "4.3.2"
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.5-alpha.2 || ~4.0.6-alpha.1",
-    "@deepseek-ai/dsh-session": "0.1.1-rc.1 || 0.1.2-alpha.4 || 0.1.2-alpha.5 || 0.1.2-rc.1 || 0.1.5-alpha.1 || 0.1.5-alpha.2 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.6-alpha.1 || 0.1.6-alpha.2 || 0.1.7-alpha.1 || 0.1.7-alpha.2 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.1 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-alpha.4 || 0.2.1-alpha.5 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-alpha.2",
-    "@deepseek-ai/dsh-tools": "0.1.1-rc.1 || 0.1.2-alpha.4 || 0.1.2-alpha.5 || 0.1.2-rc.1 || 0.1.5-alpha.1 || 0.1.5-alpha.2 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.6-alpha.1 || 0.1.6-alpha.2 || 0.1.7-alpha.1 || 0.1.7-alpha.2 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.1 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-alpha.4 || 0.2.1-alpha.5 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-alpha.2",
-    "@deepseek-ai/dsh-util-values": "0.1.2-alpha.5 || 0.1.2-rc.1 || 0.1.5-alpha.1 || 0.1.5-alpha.2 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.6-alpha.1 || 0.1.6-alpha.2 || 0.1.7-alpha.1 || 0.1.7-alpha.2 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.1 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-alpha.4 || 0.2.1-alpha.5 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-alpha.2"
+    "@deepseek-ai/cordis": "^4.0.5-alpha.2 || ~4.0.6-alpha.1 || ~4.0.6-alpha.2",
+    "@deepseek-ai/dsh-session": "0.1.1-rc.1 || 0.1.2-alpha.4 || 0.1.2-alpha.5 || 0.1.2-rc.1 || 0.1.5-alpha.1 || 0.1.5-alpha.2 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.6-alpha.1 || 0.1.6-alpha.2 || 0.1.7-alpha.1 || 0.1.7-alpha.2 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.1 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-alpha.4 || 0.2.1-alpha.5 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-alpha.2 || 0.2.2-alpha.3",
+    "@deepseek-ai/dsh-tools": "0.1.1-rc.1 || 0.1.2-alpha.4 || 0.1.2-alpha.5 || 0.1.2-rc.1 || 0.1.5-alpha.1 || 0.1.5-alpha.2 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.6-alpha.1 || 0.1.6-alpha.2 || 0.1.7-alpha.1 || 0.1.7-alpha.2 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.1 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-alpha.4 || 0.2.1-alpha.5 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-alpha.2 || 0.2.2-alpha.3",
+    "@deepseek-ai/dsh-util-values": "0.1.2-alpha.5 || 0.1.2-rc.1 || 0.1.5-alpha.1 || 0.1.5-alpha.2 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.6-alpha.1 || 0.1.6-alpha.2 || 0.1.7-alpha.1 || 0.1.7-alpha.2 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.1 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-alpha.4 || 0.2.1-alpha.5 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-alpha.2 || 0.2.2-alpha.3"
   },
   "peerDependenciesMeta": {
     "@deepseek-ai/cordis": {
@@ -116,20 +117,20 @@
     }
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "4.0.6-alpha.1",
-    "@deepseek-ai/dsh-agent": "0.2.2-alpha.2",
-    "@deepseek-ai/dsh-jobs": "0.2.2-alpha.2",
-    "@deepseek-ai/dsh-llm": "0.2.2-alpha.2",
-    "@deepseek-ai/dsh-ptc-runtime": "0.2.2-alpha.2",
-    "@deepseek-ai/dsh-sandbox": "0.2.2-alpha.2",
-    "@deepseek-ai/dsh-sandbox-policy": "0.2.2-alpha.2",
-    "@deepseek-ai/dsh-scope": "0.2.2-alpha.2",
-    "@deepseek-ai/dsh-session": "0.2.2-alpha.2",
-    "@deepseek-ai/dsh-system-prompt": "0.2.2-alpha.2",
-    "@deepseek-ai/dsh-tools": "0.2.2-alpha.2",
-    "@deepseek-ai/dsh-user-approval": "0.2.2-alpha.2",
-    "@deepseek-ai/dsh-util-values": "0.2.2-alpha.2",
-    "@deepseek-ai/dsh-working-directory": "0.2.2-alpha.2",
+    "@deepseek-ai/cordis": "4.0.6-alpha.2",
+    "@deepseek-ai/dsh-agent": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-jobs": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-llm": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-ptc-runtime": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-sandbox": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-sandbox-policy": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-scope": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-session": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-system-prompt": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-tools": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-user-approval": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-util-values": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-working-directory": "0.2.2-alpha.3",
     "@types/js-yaml": "4.0.9",
     "@types/node": "22.15.0",
     "@types/react": "19.2.2",

package/src/client/context-menu.ts

@@ -0,0 +1,289 @@
+/**
+ * src/client/context-menu.ts — iterate-plugin right-click menu contributions.
+ *
+ * dsh 0.2.2-alpha.3 added the *unified context-menu* capability
+ * (`@deepseek-ai/dsh-client-ui-context-menu`): any client plugin may register
+ * actions that appear on right-click / Shift+F10 / ContextMenu key over a
+ * Session, file, directory, URL, image, tab, or workspace, without importing
+ * a React component. The captured target stays fixed even when selection
+ * changes, and contributions are withdrawn automatically when the plugin
+ * unloads.
+ *
+ * This module turns that new upstream capability into a *user-perceivable*
+ * iterate surface: instead of only being reachable through the docked
+ * observatory and the empty-dashboard CTA, the iterate entry points now also
+ * hang off the native right-click menus — on a Session (open the quality
+ * command center, copy a preflight / dry-run / resume / disk-snapshot
+ * instruction), on a file (dry-run review scoped to that file), and on a
+ * directory (scoped review + preflight).
+ *
+ * Design (mirrors the rest of the client half):
+ *   - **Defensive**: the `contextMenus` service is optional and probed at
+ *     apply-time; a host that predates 0.2.2-alpha.3 simply has no menu
+ *     entries (the docked panel remains the entry point). Nothing throws.
+ *   - **Pure builders**: `buildSessionMenuEntries` / `buildFileMenuEntries` /
+ *     `buildDirectoryMenuEntries` return *localized descriptors* with no DOM
+ *     or clipboard side effects, so they are unit-testable on their own
+ *     (normal + empty + boundary). The imperative wiring (`copy` / `openPanel`
+ *     / `notify`) is injected by `registerIterateContextMenus`.
+ *   - **Bilingual**: every label carries zh + en and resolves against the
+ *     language passed in (the caller reads `getLang()` at menu-build time, so
+ *     a language switch is picked up on the next open).
+ *
+ * Event bridge: the observatory is a React panel with its own open/tab state.
+ * The browser client cannot call harness tools, so the "open command center"
+ * menu action dispatches a window CustomEvent (`OBS_OPEN_EVENT`) that the
+ * ObservatoryPanel listens for — the panel expands and switches tab without
+ * any cross-plugin import. The event carries an optional `sessionId` so a
+ * right-click in the session sidebar targets the right session's panel and is
+ * ignored by every other mounted panel.
+ */
+
+import { getLang, type Lang } from './i18n.ts'
+
+// ─── Structural service types (defensive; mirrors SlotsService) ──────────────
+//
+// The dsh client runtime is not type-imported (no compile-time coupling to a
+// package a pre-0.2.2-alpha.3 host may not have). The surface below is the
+// subset this plugin consumes; `register` is only ever called when a service
+// with the right shape is present.
+
+/** A right-click target this plugin contributes actions to. */
+export type IterateMenuTarget =
+  | { kind: 'session'; value: { sessionId: string; displayTitle?: string } }
+  | { kind: 'file'; value: { sessionId: string; path: string; line?: number } }
+  | { kind: 'directory'; value: { sessionId: string; path: string } }
+
+/** One menu action (presentation + optional execution). */
+export interface IterateMenuAction {
+  id: string
+  label: string
+  disabled?: boolean
+  danger?: boolean
+  separatorBefore?: boolean
+  /** Localized operation + recovery guidance when `run` rejects. */
+  failureLabel?: string
+  run?: () => void | Promise<void>
+}
+
+/** A namespaced contribution, ordered within its target family. */
+export interface IterateMenuContribution<K extends string> {
+  id: string
+  target: K
+  order: number
+  resolve(target: unknown, signal: AbortSignal): readonly IterateMenuAction[]
+}
+
+/** Structural view of the dsh `contextMenus` service this plugin consumes. */
+export interface ContextMenusService {
+  register<K extends string>(contribution: IterateMenuContribution<K>): () => void
+  notify(
+    text: string,
+    success?: boolean,
+    action?: { label: string; run: () => void | Promise<void>; failureLabel: string },
+  ): void
+}
+
+// ─── Observatory open event bridge ───────────────────────────────────────────
+
+/** Window event that asks the (matching) ObservatoryPanel to expand. */
+export const OBS_OPEN_EVENT = 'iterate-plugin:open-observatory'
+
+/** Payload carried by {@link OBS_OPEN_EVENT}. */
+export interface ObsOpenDetail {
+  /** Optional target session; omitted = open whatever panel is mounted. */
+  sessionId?: string
+  /** Tab key to switch to (`live` by default). */
+  tab?: string
+}
+
+/**
+ * Dispatch the "open observatory" event. No-op outside a browser (SSR / test
+ * environments without `window`). Returns whether the event was dispatched.
+ */
+export function openObservatory(detail?: ObsOpenDetail): boolean {
+  if (typeof window === 'undefined' || typeof window.dispatchEvent !== 'function') return false
+  try {
+    window.dispatchEvent(new CustomEvent<ObsOpenDetail>(OBS_OPEN_EVENT, { detail: detail ?? {} }))
+    return true
+  } catch {
+    return false
+  }
+}
+
+// ─── Localized descriptors (pure, testable) ──────────────────────────────────
+
+/** The action ids this plugin registers, for tests + duplicate guards. */
+export const SESSION_MENU_IDS = ['iterate.open-panel', 'iterate.preflight', 'iterate.dry-run', 'iterate.resume', 'iterate.pull'] as const
+export const FILE_MENU_IDS = ['iterate.review-file', 'iterate.open-panel'] as const
+export const DIRECTORY_MENU_IDS = ['iterate.review-dir', 'iterate.preflight', 'iterate.open-panel'] as const
+
+interface MenuEntry {
+  id: string
+  label: string
+  instruction?: string
+  /** Tab key to open when this entry is the "open panel" action. */
+  openTab?: string
+  danger?: boolean
+  disabled?: boolean
+  separatorBefore?: boolean
+}
+
+/** Bilingual labels; resolved by `pick` at build time. */
+const LABELS: Record<string, { zh: string; en: string }> = {
+  'iterate.open-panel': { zh: '打开 iterate 质量指挥中心', en: 'Open iterate command center' },
+  'iterate.preflight': { zh: '复制开跑预检指令', en: 'Copy preflight instruction' },
+  'iterate.dry-run': { zh: '复制 dry-run 审查指令', en: 'Copy dry-run review instruction' },
+  'iterate.resume': { zh: '复制断点恢复指令', en: 'Copy checkpoint-resume instruction' },
+  'iterate.pull': { zh: '复制拉取磁盘快照指令', en: 'Copy disk-snapshot pull instruction' },
+  'iterate.review-file': { zh: '复制「仅审查此文件」指令', en: 'Copy "review this file only" instruction' },
+  'iterate.review-dir': { zh: '复制「仅审查此目录」指令', en: 'Copy "review this directory only" instruction' },
+}
+
+/** Pick a localized label; unknown ids degrade to the raw id (never throw). */
+function pick(id: string, lang: Lang): string {
+  const entry = LABELS[id]
+  if (!entry) return id
+  return lang === 'zh' ? entry.zh : entry.en
+}
+
+/** Copy-failure guidance (a menu action's `failureLabel`). */
+const COPY_FAILURE: Record<'zh' | 'en', string> = {
+  zh: '复制失败：剪贴板被拒绝。请改为在观测台面板里用同一指令的「复制」按钮，或手动选中指令文本复制。',
+  en: 'Copy failed: clipboard denied. Use the matching "Copy" button in the observatory panel, or select the instruction text manually.',
+}
+
+/** Build the Session target menu entries (pure). */
+export function buildSessionMenuEntries(lang: Lang, opts?: { hasCheckpoint?: boolean }): MenuEntry[] {
+  return [
+    { id: 'iterate.open-panel', label: pick('iterate.open-panel', lang), openTab: 'live' },
+    { id: 'iterate.preflight', label: pick('iterate.preflight', lang), separatorBefore: true },
+    { id: 'iterate.dry-run', label: pick('iterate.dry-run', lang) },
+    { id: 'iterate.resume', label: pick('iterate.resume', lang), disabled: opts?.hasCheckpoint === false },
+    { id: 'iterate.pull', label: pick('iterate.pull', lang), separatorBefore: true },
+  ]
+}
+
+/** Build the File target menu entries (pure). */
+export function buildFileMenuEntries(lang: Lang): MenuEntry[] {
+  return [
+    { id: 'iterate.review-file', label: pick('iterate.review-file', lang) },
+    { id: 'iterate.open-panel', label: pick('iterate.open-panel', lang) },
+  ]
+}
+
+/** Build the Directory target menu entries (pure). */
+export function buildDirectoryMenuEntries(lang: Lang): MenuEntry[] {
+  return [
+    { id: 'iterate.review-dir', label: pick('iterate.review-dir', lang) },
+    { id: 'iterate.preflight', label: pick('iterate.preflight', lang), separatorBefore: true },
+    { id: 'iterate.open-panel', label: pick('iterate.open-panel', lang) },
+  ]
+}
+
+// ─── Imperative wiring (register + run callbacks) ────────────────────────────
+
+/** Injection points the menu wiring needs (kept dependency-light for tests). */
+export interface IterateMenuDeps {
+  /** Copy an instruction; resolves to whether the clipboard write succeeded. */
+  copy: (text: string) => Promise<boolean>
+  /** Open the observatory panel (optionally for a session, on a tab). */
+  openPanel: (detail?: ObsOpenDetail) => void
+  /** Show the shared toast. */
+  notify: (text: string, success?: boolean, action?: { label: string; run: () => void | Promise<void>; failureLabel: string }) => void
+}
+
+/** Map a pure entry to a runnable menu action, wiring the injected deps. */
+function toAction(entry: MenuEntry, deps: IterateMenuDeps, lang: Lang): IterateMenuAction {
+  const action: IterateMenuAction = {
+    id: entry.id,
+    label: entry.label,
+    danger: entry.danger,
+    separatorBefore: entry.separatorBefore,
+  }
+  if (entry.disabled) action.disabled = true
+  if (entry.openTab) {
+    action.run = () => {
+      deps.openPanel({ tab: entry.openTab })
+      deps.notify(lang === 'zh' ? '已打开 iterate 观测台。' : 'Iterate observatory opened.', true)
+    }
+    return action
+  }
+  if (entry.instruction) {
+    const text = entry.instruction
+    const failureLabel = COPY_FAILURE[lang]
+    action.failureLabel = failureLabel
+    action.run = async () => {
+      const ok = await deps.copy(text)
+      if (!ok) throw new Error(failureLabel)
+      deps.notify(lang === 'zh' ? '指令已复制，粘贴给模型即可。' : 'Instruction copied — paste it to the model.', true)
+    }
+  }
+  return action
+}
+
+/**
+ * Register this plugin's context-menu contributions on the (already-validated)
+ * `contextMenus` service. Returns an unregister function; a host without the
+ * service is a no-op that returns `() => {}` (callers guard).
+ */
+export function registerIterateContextMenus(
+  service: ContextMenusService,
+  deps: IterateMenuDeps,
+  instructionByEntry: (id: string) => string,
+): () => void {
+  const unregister: Array<() => void> = []
+
+  const register = <K extends string>(target: K, order: number, build: (lang: Lang, target: unknown) => MenuEntry[]) => {
+    try {
+      const dispose = service.register({
+        id: `iterate-plugin.${target}`,
+        target,
+        order,
+        resolve: (t, _signal) => {
+          const lang = getLang()
+          return build(lang, t).map((entry) => {
+            const full: MenuEntry = { ...entry, instruction: entry.instruction ?? instructionByEntry(entry.id) }
+            return toAction(full, deps, lang)
+          })
+        },
+      })
+      unregister.push(dispose)
+    } catch (err) {
+      // A duplicate contribution id or an unsupported target family must not
+      // take the plugin down — log and continue with the remaining targets.
+      if (typeof console !== 'undefined' && typeof console.error === 'function') {
+        console.error('[iterate-ui] context-menu registration failed for target', target, err)
+      }
+    }
+  }
+
+  register('session', 300, (_lang, t) => {
+    const target = t as { value?: { sessionId?: string } } | undefined
+    return buildSessionMenuEntries(getLang(), { hasCheckpoint: target?.value?.sessionId ? true : undefined })
+  })
+  register('file', 300, (_lang, t) => {
+    const target = t as { value?: { path?: string; line?: number } } | undefined
+    return buildFileMenuEntries(getLang()).map((e) => ({
+      ...e,
+      instruction: e.id === 'iterate.review-file'
+        ? instructionByEntry(`file:${target?.value?.path ?? ''}${typeof target?.value?.line === 'number' ? `:${target.value.line}` : ''}`)
+        : e.instruction,
+    }))
+  })
+  register('directory', 300, (_lang, t) => {
+    const target = t as { value?: { path?: string } } | undefined
+    return buildDirectoryMenuEntries(getLang()).map((e) => ({
+      ...e,
+      instruction: e.id === 'iterate.review-dir'
+        ? instructionByEntry(`dir:${target?.value?.path ?? ''}`)
+        : e.instruction,
+    }))
+  })
+
+  return () => {
+    for (const dispose of unregister.splice(0)) {
+      try { dispose() } catch { /* noop */ }
+    }
+  }
+}

package/src/client/index.ts

@@ -78,6 +78,7 @@ import {
   scanSessionForPreflight,
   buildPreflightInstruction,
   buildValidationApplyInstruction,
+  buildScopedReviewInstruction,
   filterLiveEntries,
   filterTimelineEntries,
   serializeObservatoryExport,
@@ -132,6 +133,14 @@ import {
   type Lang,
 } from './i18n.ts'
 import { noteSession, readSession, subscribeSession } from './session-cache.ts'
+// v3.14: right-click menu contributions (dsh 0.2.2-alpha.3 unified context menus).
+import {
+  openObservatory,
+  OBS_OPEN_EVENT,
+  registerIterateContextMenus,
+  type ContextMenusService,
+  type ObsOpenDetail,
+} from './context-menu.ts'
 
 // ─── Module contract ─────────────────────────────────────────────────────────
 
@@ -907,6 +916,47 @@ function readTheme(ctx: ClientContext): ThemeService | undefined {
   return undefined
 }
 
+/**
+ * Resolve the dsh 0.2.2-alpha.3 `contextMenus` service. Unlike slots/theme it
+ * is NOT in the typed `ClientContext`, so it is probed through `ctx.get` (the
+ * cordis service locator) and structurally validated. A host that predates the
+ * capability returns `undefined` and the plugin simply has no menu entries.
+ */
+function readContextMenus(ctx: ClientContext): ContextMenusService | undefined {
+  if (!ctx || typeof ctx.get !== 'function') return undefined
+  const raw = ctx.get('contextMenus', false)
+  if (!raw || typeof raw !== 'object') return undefined
+  const svc = raw as { register?: unknown; notify?: unknown }
+  if (typeof svc.register !== 'function') return undefined
+  if (typeof svc.notify !== 'function') return undefined
+  return svc as unknown as ContextMenusService
+}
+
+/**
+ * Extract a session identifier from an opaque host-shaped session object.
+ * The slot `props.session` shape is host-defined; this probes the common
+ * keys so the observatory open-event can target the right session and be
+ * ignored by every other mounted panel. Returns `null` when unknown (the
+ * panel then responds to any open event — the single-panel fallback).
+ */
+function sessionIdOfSession(session: unknown): string | null {
+  if (!session || typeof session !== 'object') return null
+  const s = session as Record<string, unknown>
+  const candidates = [
+    s.sessionId, s.id, s.header, s.session,
+  ] as unknown[]
+  for (const c of candidates) {
+    if (typeof c === 'string' && c) return c
+    if (c && typeof c === 'object') {
+      const o = c as Record<string, unknown>
+      for (const k of ['sessionId', 'id']) {
+        if (typeof o[k] === 'string' && o[k]) return o[k] as string
+      }
+    }
+  }
+  return null
+}
+
 // ─── Module-level runtime state (shared across slots) ────────────────────────
 
 let slotsSvc: SlotsService | undefined = undefined
@@ -915,6 +965,8 @@ let storage: ReturnType<typeof createStorage> | null = null
 let themeDisposer: (() => void) | null = null
 let themeListener: (() => void) | null = null
 let themeEnabled = true
+/** v3.14: right-click menu contribution disposer (re-apply() never stacks). */
+let menuDisposer: (() => void) | null = null
 const roundPulseListeners: Array<(payload: { round: number; converged: boolean }) => void> = []
 
 /**
@@ -2392,6 +2444,28 @@ function ObservatoryPanel(props: SlotProps) {
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [open])
 
+  // v3.14: the right-click "open command center" menu action dispatches a
+  // window event; this panel expands and switches tab when the event targets
+  // it (no sessionId = single-panel fallback, a different sessionId = ignore).
+  const panelSessionId = sessionIdOfSession(session)
+  React.useEffect(() => {
+    if (typeof window === 'undefined' || typeof window.addEventListener !== 'function') return
+    const onOpen = (ev: Event) => {
+      const detail = (ev as CustomEvent<ObsOpenDetail>).detail
+      const detailSession = detail && typeof detail.sessionId === 'string' && detail.sessionId
+        ? detail.sessionId
+        : null
+      if (detailSession && panelSessionId && detailSession !== panelSessionId) return
+      setOpen(true)
+      const target = detail && typeof detail.tab === 'string' ? detail.tab : 'live'
+      const valid = OBS_TABS.some((x) => x.key === target)
+      setTab(valid ? target : 'live')
+    }
+    window.addEventListener(OBS_OPEN_EVENT, onOpen)
+    return () => window.removeEventListener(OBS_OPEN_EVENT, onOpen)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [panelSessionId])
+
   /** Copy an instruction, flashing "已复制" on the originating button only when the copy actually succeeded. */
   const copyInstruction = (key: string, text: string) => {
     if (!text) return
@@ -3867,6 +3941,49 @@ export function apply(ctx: ClientContext): void {
     )
   }
 
+  // 5b. v3.14: right-click menu contributions (dsh 0.2.2-alpha.3 unified
+  // context menus). Optional service: a host that predates the capability has
+  // no menu entries, and the docked observatory stays the entry point.
+  {
+    const menuSvc = readContextMenus(ctx)
+    if (menuSvc) {
+      // Resolve a paste-able instruction for a menu action id. Session-level
+      // ids map to the shared builders (the SAME single source of truth the
+      // observatory copy buttons use); file:/dir: ids are the scoped review.
+      const instructionByEntry = (id: string): string => {
+        if (id === 'iterate.preflight') return buildPreflightInstruction()
+        if (id === 'iterate.dry-run') return START_INSTRUCTIONS.reviewOnly
+        if (id === 'iterate.resume') return buildCheckpointResumeInstruction()
+        if (id === 'iterate.pull') return buildDiskSnapshotInstruction()
+        if (id.startsWith('file:')) {
+          const rest = id.slice('file:'.length)
+          const colon = rest.lastIndexOf(':')
+          const path = colon > 0 ? rest.slice(0, colon) : rest
+          const line = colon > 0 ? Number(rest.slice(colon + 1)) : undefined
+          return buildScopedReviewInstruction({ file: path, ...(Number.isInteger(line) && line! > 0 ? { line: line! } : {}) })
+        }
+        if (id.startsWith('dir:')) return buildScopedReviewInstruction({ dir: id.slice('dir:'.length) })
+        return ''
+      }
+      if (menuDisposer) {
+        try { menuDisposer() } catch { /* noop */ }
+        menuDisposer = null
+      }
+      menuDisposer = registerIterateContextMenus(
+        menuSvc,
+        {
+          copy: (text) => copyText(text),
+          openPanel: (detail) => { openObservatory(detail) },
+          notify: (text, success, action) => { menuSvc.notify(text, success, action) },
+        },
+        instructionByEntry,
+      )
+      if (typeof ctx.effect === 'function') {
+        ctx.effect(() => { if (menuDisposer) { menuDisposer(); menuDisposer = null } })
+      }
+    }
+  }
+
   // 6: keep theme toggle state consistent across theme/change events.
   // Registered through registerThemeListener so repeated apply() and client
   // unmounts never leak a second listener.