dominds 1.4.2 → 1.5.1

package/dist/docs/app-constitution.md

@@ -34,7 +34,7 @@ This document uses **A/B/C/D** to describe the evolution phases of this feature.
 Goal: make the kernel/app boundary and the minimal data flow runnable, so the install/resolve/boot path can be validated.
 
 - Key capabilities (at minimum):
-  - App install handshake (`<app> --json`) can be consumed by the kernel/CLI.
+  - App install handshake (`<app> --dominds-app`) can be consumed by the kernel/CLI.
   - App manifest (`.minds/app.yaml`) schema/loader is available.
   - Basic local resolution strategy (`local`) works: discover local apps under `<rtws>/dominds-apps/<appId>/`.
 
@@ -168,7 +168,7 @@ Key semantics:
   - `<rtws>/.apps/resolution.yaml` can pin an `assignedPort` as a stable resolved config; **if present it must be non-zero** (anti-jitter).
   - `assignedPort` is not the runtime “bound port”; it is the resolver’s stable config output.
 
-### Install JSON (`npx <pkg> --json`)
+### Install JSON (`npx <pkg> --dominds-app`)
 
 (Target: planned) Install JSON should avoid overlapping with the manifest (`.minds/app.yaml`).
 
@@ -179,6 +179,20 @@ Recommended principles:
 - Install JSON carries only the minimal fields required for locating caches and reading the manifest.
 - Capability inventory (teammates/tools/web/seed, etc.) must be **manifest-only**, to avoid drift from dual-writing.
 
+User-facing installation and the low-level handshake must stay clearly separated:
+
+- The **user-facing install entrypoint** should be `dominds install <spec>`, not `npx <pkg> --dominds-app`.
+- `--dominds-app` is a **kernel/CLI-to-app handshake flag** used by Dominds to retrieve install JSON. It is not meant to be the ordinary human-facing UX.
+- For published apps, the kernel/CLI may resolve install JSON through `npx -y <pkg> --dominds-app` during resolution.
+- For local apps under development, the kernel/CLI may call the local package bin through `dominds install <path> --local`, still passing the same `--dominds-app` handshake flag underneath.
+- `npm install` / `pnpm add` only answers “where is the package downloaded/cached”. They do **not** register an app into the current rtws by themselves. The operation that actually adds the app into the current workspace dependency graph is still `dominds install`.
+
+Recommended user mental model:
+
+- `npm` / `pnpm`: package managers responsible for publishing, downloading, and caching.
+- `npx`: one-shot execution of an npm package entrypoint; in the app system it mainly serves as the kernel's resolution/handshake backend.
+- `dominds install`: the product-level Dominds command that updates `.minds/app.yaml`, `.minds/app-lock.yaml`, `<rtws>/.apps/configuration.yaml`, and `<rtws>/.apps/resolution.yaml`, making the app actually part of the current rtws capability graph.
+
 (Current: implemented) existing anchors:
 
 - JSON schema: `dominds/main/apps/app-json.ts` (`DomindsAppInstallJsonV1`).
@@ -243,6 +257,143 @@ Key semantics:
 - The kernel must not implicitly write `env.md` into shell rc or environment.
 - If the kernel offers “write managed rc block” (e.g. setup flow), it must be explicit and user-confirmed.
 
+### Reference design: Web Dev App (replacing the old prototype-app narrative)
+
+Instead of continuing to discuss app semantics around an accidental prototype, this document now uses a more durable reference design: **Web Dev App**.
+
+Its goal is not to represent one specific product. Its goal is to provide a high-frequency, easy-to-validate app shape:
+
+- focused on web development and browser regression work,
+- packaging browser interaction capability as an explicit toolset,
+- shipping a minimal but complete team with at least `web_tester` and `web_developer`.
+
+Design stance:
+
+- `Web Dev App` is an **integrator-style app**. The important part is the packaging of team, toolsets, environment guidance, and workflow posture, not a demo business frontend.
+- It should reuse existing capabilities where possible instead of inventing a new browser automation protocol inside the app.
+- The current upstream capability to learn from is the repo-root `playwright-interactive/` skill. That skill is better understood as a workflow/method asset, not as a ready-to-install Dominds MCP server.
+
+So `Web Dev App` should make the `playwright-interactive` relationship explicit as two separate layers:
+
+1. **Product-semantic layer (in scope for this design)**
+   - define a stable toolset semantic such as `playwright_interactive`;
+   - define which teammates receive it, what problem it solves, and when to use it;
+   - ship the related `.minds/team.yaml`, member persona/knowledge, `.minds/env.md`, etc.
+2. **Execution-backend layer (replaceable implementation detail)**
+   - this may wrap the `playwright-interactive` skill into app-host tools;
+   - or later be replaced by an equivalent MCP server / local host module;
+   - as long as the team-facing toolset contract does not drift.
+
+It must be explicit that **an app is not the same thing as a skill**:
+
+- An **app** is a Dominds install/resolve/composition unit. It has an `id`, a manifest (`.minds/app.yaml`), team-facing assets (`.minds/team.yaml`, persona/knowledge/lessons), env docs (`.minds/env.md`), and participates in rtws-level lock/configuration/resolution.
+- A **skill** is closer to a workflow asset, method asset, or low-level execution material. A skill can be reused, wrapped, or replaced by an app, but it usually does not own rtws installation, dependency graph membership, or `team.yaml` import semantics by itself.
+- `playwright-interactive/` is currently closer to a skill: it provides browser-workflow capability that Web Dev can learn from or wrap. `Web Dev App` is the installable product unit that packages those capabilities into a stable team/toolset/env contract.
+
+So the correct story is not “install a skill as an app”. The correct story is:
+
+- the skill is absorbed as implementation material by an app,
+- the app exposes a stable team-facing contract,
+- the low-level skill / MCP / host-module backend can change later without changing the app identity or team-facing semantics.
+
+Suggested user-facing installation flow:
+
+```bash
+# Local app under development
+dominds install ./dominds-apps/web-dev --local --enable
+
+# Published npm app (target shape)
+dominds install @longrun-ai/web-dev --enable
+```
+
+After installation, the user should expect these files to change:
+
+- `.minds/app.yaml`: root dependency declaration is updated.
+- `.minds/app-lock.yaml`: app package version is frozen.
+- `<rtws>/.apps/configuration.yaml`: explicit enable/disable intent is recorded.
+- `<rtws>/.apps/resolution.yaml`: effective source, enabled state, and stable `assignedPort` are materialized.
+
+Suggested minimal asset shape:
+
+```text
+web-dev/
+├── package.json
+├── .minds/
+│   ├── app.yaml
+│   ├── team.yaml
+│   ├── env.md
+│   ├── app-lock.yaml
+│   └── team/
+│       ├── web_tester/
+│       │   ├── persona.zh.md
+│       │   ├── knowledge.zh.md
+│       │   └── lessons.zh.md
+│       └── web_developer/
+│           ├── persona.zh.md
+│           ├── knowledge.zh.md
+│           └── lessons.zh.md
+└── src/
+    └── app-host.ts
+```
+
+Suggested team shape:
+
+- `web_tester`
+  - primary responsibility: run browser interaction, perform regression walkthroughs, collect screenshot/console/network evidence;
+  - default toolsets: `playwright_interactive` plus read-only workspace tools such as `ws_read`;
+  - non-goal: does not directly edit product code or take over build/process management.
+- `web_developer`
+  - primary responsibility: implement UI/interaction fixes, consume `web_tester` findings, and close the loop;
+  - default toolsets: code-edit/search tools such as `codex_style_tools` (or equivalent) plus optional access to read tester evidence;
+  - non-goal: should not blur browser acceptance into an implicit “I also tested it” posture; when acceptance is needed, it should explicitly tell/ask `web_tester`.
+
+Suggested `team.yaml` fragment:
+
+```yaml
+members:
+  web_tester:
+    name: Web Tester
+    icon: '🧪'
+    toolsets:
+      - ws_read
+      - playwright_interactive
+
+  web_developer:
+    name: Web Developer
+    icon: '🛠️'
+    toolsets:
+      - ws_read
+      - codex_style_tools
+```
+
+Requirements for the `playwright_interactive` toolset design:
+
+- It should be treated as a **stable team-facing capability name**, not as a hard-coded implementation detail tied forever to one backend.
+- At minimum it should cover these task intents:
+  - open/reuse a browser session,
+  - navigate to a target URL,
+  - perform interaction and assertions,
+  - capture screenshots and key debugging evidence,
+  - preserve the “reusable session across multiple fix iterations” mental model.
+- If the current phase does not yet ship a directly executable backend, the docs must label it as a **target contract (planned)** instead of pretending it is already built in.
+
+Current prototype note (`dominds-apps/web-dev`, as of March 8, 2026):
+
+- The app is already installable and contributes `web_tester` / `web_developer` teammates plus a live `playwright_interactive` toolset registration.
+- `playwright_session_new/list/status/eval/attach/detach/close` and cross-dialog reminder sync are already implemented.
+- `kind: "web"` sessions now create a real Playwright-backed browser/context/page runtime and report live page surfaces via session status/reminders.
+- `kind: "electron"` is **not** at the same completion level yet: it still falls back to the older prototype runtime path and should be treated as unfinished.
+- Reminder UX contract: tool output may summarize reminder-sync actions, but the reminder panel is the authoritative surface for attachment state.
+- Runtime refresh contract: after enabling the app, a full Dominds instance restart should not be required just to discover the toolset; the next minds reload / tools-registry fetch should refresh enabled app tool proxies. This does **not** mean in-flight prompts are rewritten retroactively.
+- Remaining gap list for the browser capability layer: screenshot / console / network evidence are not yet exposed as first-class tool outputs, and there is not yet a production-grade browser lifecycle manager.
+- Restart boundary: if the kernel/apps-host process restarts, persisted session records remain but the in-memory browser runtime degrades and must be recreated.
+
+Why this app shape matters:
+
+- It makes `.minds/team.yaml` collaboration semantics concrete: development and testing are two long-lived teammates, not vague temporary roles.
+- It validates whether “app provides team + toolset + env docs” is expressive enough for a real workflow.
+- It gives future skill/MCP/local-host convergence a stable semantic anchor at the app layer.
+
 ## `<rtws>/.apps/override/<app-id>/`: override layer
 
 ### Override root

package/dist/docs/app-constitution.zh.md

@@ -33,7 +33,7 @@
 目标：把 Kernel/App 的边界与最小数据流跑通，让“安装/解析/启动路径”可被验证。
 
 - 关键能力（至少）：
-  - App 的 install handshake（`<app> --json`）可被 Kernel/CLI 读取。
+  - App 的 install handshake（`<app> --dominds-app`）可被 Kernel/CLI 读取。
   - App manifest（`.minds/app.yaml`）schema/loader 可用。
   - 基本的本地解析策略（`local`）可工作：按 `<rtws>/dominds-apps/<appId>/` 发现本地 app。
 
@@ -167,7 +167,7 @@ rtws 是一次运行的工作区根目录（`process.cwd()`）。Kernel 在其
   - `<rtws>/.apps/resolution.yaml` 中的 `assignedPort` 用于“固化后的解析配置”，一旦存在则必须为**非 0**端口（用于防抖动）。
   - `assignedPort` 不等同于运行时“实际绑定端口（bound port）”；它是 resolver 产出的稳定配置。
 
-### Install JSON（`npx <pkg> --json`）
+### Install JSON（`npx <pkg> --dominds-app`）
 
 （目标：拟实现）Install JSON 应避免与 manifest（`.minds/app.yaml`）内容重叠。
 
@@ -178,6 +178,20 @@ rtws 是一次运行的工作区根目录（`process.cwd()`）。Kernel 在其
 - Install JSON 只承载“定位与缓存”所需的最小字段。
 - App 的能力清单（teammates/tools/web/seed 等）**只以 manifest 为准**，避免双写导致漂移。
 
+用户路径与底层机制应明确区分：
+
+- **用户安装入口** 应是 `dominds install <spec>`，而不是要求用户自己执行 `npx <pkg> --dominds-app`。
+- `--dominds-app` 是 **Kernel/CLI 与 app 包之间的握手参数**，用于让 Dominds 读取 app install JSON；它不是面向终端用户的常规操作界面。
+- 对已发布 app：Kernel/CLI 可以在解析阶段通过 `npx -y <pkg> --dominds-app` 获取 install JSON。
+- 对本地开发中的 app：Kernel/CLI 可以通过 `dominds install <path> --local` 调用本地包的 bin，并传入 `--dominds-app` 完成同一握手。
+- `npm install` / `pnpm add` 只解决“包被下载到哪里”；它们**不会**自动把 app 注册到当前 rtws。把 app 纳入当前 workspace 依赖图的动作仍然是 `dominds install`。
+
+建议的用户心智模型：
+
+- `npm` / `pnpm`：包管理器，负责发布、下载、缓存。
+- `npx`：一次性执行某个 npm package 的入口；在 app 体系里主要作为 Kernel 的解析/握手后端。
+- `dominds install`：Dominds 的产品级安装命令，负责把 app 写入 `.minds/app.yaml`、更新 `.minds/app-lock.yaml`、刷新 `<rtws>/.apps/configuration.yaml` / `resolution.yaml`，并让该 app 真正进入当前 rtws 的能力图。
+
 （现状：已实现）install json schema 与 apps 配置/解析锚点仍可参考：
 
 - JSON schema：`dominds/main/apps/app-json.ts`（`DomindsAppInstallJsonV1`）。
@@ -241,6 +255,143 @@ rtws 是一次运行的工作区根目录（`process.cwd()`）。Kernel 在其
 - Kernel 不应自动把 `env.md` 写入 shell rc 或环境；它只提供可见性（文档/提示）。
 - 若 Kernel 提供“写入 rc managed block”的能力（例如 setup flow），也应基于明确的 UI/确认，而不是隐式执行。
 
+### 参考设计：Web Dev App（替代旧的原型 app 叙事）
+
+为了避免继续围绕一个过于偶然的原型 app 收敛语义，本文改用一个更直接、可长期演进的参考设计：**Web Dev App**。
+
+它的目标不是“代表某个具体产品”，而是提供一个高频、通用、容易验证的 app 形态：
+
+- 面向 Web 开发与浏览器回归。
+- 把浏览器交互能力包装成一个明确的 toolset。
+- 自带一支最小但完整的团队：至少 `web_tester` 与 `web_developer`。
+
+设计口径：
+
+- `Web Dev App` 是一个 **integrator-style app**：重点是封装团队、工具集、环境说明与工作方式，而不是炫耀某个业务前端。
+- 它应优先复用已有能力，而不是在 app 内重复发明一套浏览器自动化协议。
+- 当前可参考的上游能力是仓库根目录的 `playwright-interactive/` skill；该 skill 更像“工作流/方法学资产”，不是可直接作为 Dominds MCP server 安装的现成 server。
+
+因此，`Web Dev App` 对 `playwright-interactive` 的定位应明确分成两层：
+
+1. **产品语义层（本次设计范围）**：
+   - 定义一个稳定的 toolset 语义，例如 `playwright_interactive`。
+   - 规定哪些成员拿到这个 toolset、它解决什么问题、什么时候用。
+   - 配套 `.minds/team.yaml`、成员 persona/knowledge、`.minds/env.md` 等资产。
+2. **执行后端层（后续实现可替换）**：
+   - 可以是把 `playwright-interactive` skill 包装成 app-host tools；
+   - 也可以是未来替换成等价的 MCP server / 本地 host module；
+   - 只要对 team.yaml 暴露的 toolset 契约不漂移即可。
+
+这里必须明确 **app 与 skill 不是同一层概念**：
+
+- **App** 是 Dominds 的安装/解析/组合单元：它有自己的 `id`、manifest（`.minds/app.yaml`）、团队资产（`.minds/team.yaml`、persona/knowledge/lessons）、环境说明（`.minds/env.md`），并可被 `dominds install` 纳入某个 rtws。
+- **Skill** 更像工作流资产、方法学资产，或某个底层执行能力的封装材料。它可以被 app 复用、包装、替换，但通常不直接承担“被 workspace 安装、被 team.yaml 引用、被 resolution/lock 管理”的职责。
+- `playwright-interactive/` 当前更接近 skill：它提供可借鉴或可包装的浏览器工作流能力，但 `Web Dev App` 才是把这些能力整合成“可安装产品单元”的实体。
+
+因此，正确表述不是“把一个 skill 直接当 app 安装”，而是：
+
+- skill 作为实现材料被 app 吸纳；
+- app 对外暴露稳定的 team/toolset/env 契约；
+- 底层 skill / MCP / host module 可以替换，但 app 身份与 team-facing contract 应保持稳定。
+
+建议安装流程（面向用户）：
+
+```bash
+# 本地开发态 app
+dominds install ./dominds-apps/web-dev --local --enable
+
+# 已发布到 npm 的 app（目标形态）
+dominds install @longrun-ai/web-dev --enable
+```
+
+安装完成后，用户应预期以下文件发生变化：
+
+- `.minds/app.yaml`：增加根依赖声明。
+- `.minds/app-lock.yaml`：冻结 app package 版本。
+- `<rtws>/.apps/configuration.yaml`：记录用户显式 enable/disable 意图。
+- `<rtws>/.apps/resolution.yaml`：记录实际来源、effective enabled 与稳定 `assignedPort`。
+
+建议的最小资产形态：
+
+```text
+web-dev/
+├── package.json
+├── .minds/
+│   ├── app.yaml
+│   ├── team.yaml
+│   ├── env.md
+│   ├── app-lock.yaml
+│   └── team/
+│       ├── web_tester/
+│       │   ├── persona.zh.md
+│       │   ├── knowledge.zh.md
+│       │   └── lessons.zh.md
+│       └── web_developer/
+│           ├── persona.zh.md
+│           ├── knowledge.zh.md
+│           └── lessons.zh.md
+└── src/
+    └── app-host.ts
+```
+
+建议的团队形态：
+
+- `web_tester`
+  - 主要职责：运行浏览器交互、回归走查、收集截图/console/network 证据。
+  - 默认工具集：`playwright_interactive` + 只读型 workspace 工具（如 `ws_read`）。
+  - 非目标：不直接修改业务代码；不接管构建/进程管理。
+- `web_developer`
+  - 主要职责：实现页面/UI/交互修复，消费 `web_tester` 的缺陷报告并完成闭环。
+  - 默认工具集：代码修改/检索工具（如 `codex_style_tools` 或等价工具）+ 可选读取 `web_tester` 产出的证据。
+  - 非目标：不把浏览器验收职责模糊地“顺手做掉”；需要时应显式 tellask `web_tester` 做验收。
+
+建议的 `team.yaml` 片段：
+
+```yaml
+members:
+  web_tester:
+    name: Web Tester
+    icon: '🧪'
+    toolsets:
+      - ws_read
+      - playwright_interactive
+
+  web_developer:
+    name: Web Developer
+    icon: '🛠️'
+    toolsets:
+      - ws_read
+      - codex_style_tools
+```
+
+关于 `playwright_interactive` toolset 的设计要求：
+
+- 它应被视为 **app 暴露给 team 的稳定能力名**，而不是强绑定某个底层实现细节（skill / MCP / app-host）。
+- 它应至少覆盖以下任务意图：
+  - 打开/复用浏览器会话。
+  - 导航到目标 URL。
+  - 执行交互与断言。
+  - 采集截图与关键调试证据。
+  - 在多轮修复之间保持“可复用会话”的心智模型。
+- 如果当前阶段还没有可直接执行的后端实现，文档必须明确标注为“目标契约（拟实现）”，而不是宣称已经内建完成。
+
+当前 prototype 说明（`dominds-apps/web-dev`，截至 2026-03-08）：
+
+- 该 app 已可安装，并已贡献 `web_tester` / `web_developer` teammate 与可用的 `playwright_interactive` toolset 注册。
+- `playwright_session_new/list/status/eval/attach/detach/close` 与跨对话 reminder sync 已落地。
+- `kind: "web"` 会话现在会创建真实的 Playwright browser/context/page runtime，并通过 status/reminder 报告实时页面 surface。
+- `kind: "electron"` 还没有达到同等完成度：当前仍回落到旧的 prototype runtime 路径，应视为未完成能力。
+- reminder 体验契约：tool 输出可以摘要提示 reminder-sync 动作，但 attachment state 的权威可见面仍是 reminder 面板本身。
+- runtime 刷新契约：app 启用后，不应再要求为了“看见 toolset”而整实例重启；下一次 minds reload / tools-registry fetch 应刷新 enabled app tool proxies。但这 **不表示** 已经发出的 in-flight prompt 会被追写更新。
+- 浏览器能力层的剩余缺口：截图 / console / network 证据尚未作为一等 tool output 暴露，也还没有生产级浏览器生命周期管理器。
+- 重启边界：若 kernel/apps-host 进程重启，已持久化的 session record 仍在，但内存态浏览器 runtime 会退化，需要后续 tool call 重新建立。
+
+这类 app 的价值在于：
+
+- 它让 `.minds/team.yaml` 的跨成员协作语义更具体：开发与测试天然是两个长期 agent，而不是临时角色描述。
+- 它验证“app 提供团队 + toolset + env 文档”的组合是否足够表达一个真实工作流。
+- 它为后续把 skill/MCP/本地 host module 统一到同一个 app 语义层提供了稳定锚点。
+
 ## `<rtws>/.apps/override/<app-id>/`：覆盖层
 
 ### 覆盖层目录（override root）

package/dist/docs/dialog-persistence.md

@@ -300,6 +300,37 @@ Simple text file containing the current course number:
 }
 ```
 
+### Root-generation anchors and reconciliation records
+
+To support root dialog fork, persistence now records which root-generation viewpoint a piece of dialog state belongs to.
+
+**Root-generation anchor**:
+
+- `rootCourse`
+- `rootGenseq`
+
+**Purpose**:
+
+- Any state snapshot that must stay aligned across the entire root dialog tree must be anchored to the root generation rather than each subdialog's local course/genseq
+- When forking at `(course, genseq)`, the retained state is the latest consistent snapshot at or before `(rootCourse=course, rootGenseq=genseq-1)`
+
+**New / strengthened persisted records**:
+
+- `subdialog_created_record`
+  - persisted in the root transcript
+  - marks when a subdialog already exists on the root timeline, so fork can decide whether to include it
+- `reminders_reconciled_record`
+- `questions4human_reconciled_record`
+- `pending_subdialogs_reconciled_record`
+- `subdialog_registry_reconciled_record`
+- `subdialog_responses_reconciled_record`
+
+**Required behavior**:
+
+- These reconciliation records are state snapshots, not LLM transcript content; message reconstruction must skip them
+- Any subdialog transcript record that participates in root-fork cutoff trimming must carry `rootCourse/rootGenseq`
+- When writing a forked root, persistence appends a baseline reconciliation set into `course-1` so reminders / Q4H / pending subdialogs / registry / responses are restored to the pre-cutoff state
+
 ---
 
 ## Memory Persistence

package/dist/docs/dialog-persistence.zh.md

@@ -297,6 +297,37 @@ status: 'active' # 当前对话状态
 }
 ```
 
+### Root generation 锚点与状态对账记录
+
+为支持 root dialog fork，持久化层现在显式记录“某条数据对应的是哪一个 root generation 视角”。
+
+**Root generation 锚点**：
+
+- `rootCourse`
+- `rootGenseq`
+
+**用途**：
+
+- 所有需要跨整棵 root tree 对齐的状态快照，都必须绑定到 root generation，而不是各自子对话的本地 course/genseq
+- root fork 在切点 `(course, genseq)` 时，实际保留的是**不晚于** `(rootCourse=course, rootGenseq=genseq-1)` 的最后一个一致快照
+
+**新增/强化的持久化记录**：
+
+- `subdialog_created_record`
+  - 持久化在 root transcript 中
+  - 记录某个子对话何时在 root 时间线上已“存在”，供 fork 时判断是否应纳入新树
+- `reminders_reconciled_record`
+- `questions4human_reconciled_record`
+- `pending_subdialogs_reconciled_record`
+- `subdialog_registry_reconciled_record`
+- `subdialog_responses_reconciled_record`
+
+**规范要求**：
+
+- 这些对账记录是状态快照，不属于 LLM transcript 内容；重建消息上下文时应跳过
+- 子对话 transcript 中凡是需要参与 root fork 边界裁剪的记录，都必须带 `rootCourse/rootGenseq`
+- fork 写入新 root 时，会在 `course-1` 追加一组 baseline 对账记录，用来把 reminders / Q4H / pending subdialogs / registry / responses 恢复到切点前状态
+
 ---
 
 ## 记忆持久化

package/dist/docs/dialog-system.md

@@ -979,6 +979,35 @@ Frontend twin must stay in sync: `dominds/webapp/src/shared/utils/inter-dialog-f
 
 **Registry**: Registered subdialogs (TYPE B Tellasks) are tracked in the root dialog's registry and persist across restarts.
 
+### Root dialog fork
+
+An entire root dialog tree can be forked at the start of a chosen root generation into a brand-new root dialog. This is used to preserve prior context while re-running the later mainline/sideline path from a historical branch point.
+
+**Entry points**:
+
+- UI shows `Fork dialog` only on generation bubbles of a root dialog (`selfId === rootId`)
+- Backend API: `POST /api/dialogs/:rootId/fork`
+- Request body: `{ course, genseq, status? }`
+
+**Semantics (required)**:
+
+- The selected generation bubble is **not** copied into the forked root; the fork point means "branch immediately before this generation starts"
+- The copy scope is the **entire root dialog tree**, not just one dialog
+- A subdialog is included only if the root had already persisted it as created before the cutoff
+- Subdialog transcript retention is bounded by the root-generation anchor, not by the subdialog's local `genseq`
+
+**Post-fork actions** (returned by backend to UI):
+
+- `draft_user_text`: if the target generation is a user message, prefill that text into the new dialog input and wait for user confirmation
+- `restore_pending`: if there were pending Q4H or pending subdialogs before the cutoff, restore those blocking states in the new root
+- `auto_continue`: if there is no pending blocker before the cutoff, initialize the new root as `interrupted(system_stop: fork_dialog_continue)` and have UI immediately send `resume_dialog`
+
+**Consistency requirements**:
+
+- Fork must preserve the same Taskdoc reference
+- The forked root and all forked subdialogs are persisted under `running/` with a new rootId
+- Frontend must not expose this entry for sideline dialogs; current implementation supports root dialogs only
+
 ### Lifecycle Management
 
 **Active State**: Dialogs remain active while agents are working on tasks.

package/dist/docs/dialog-system.zh.md

@@ -949,6 +949,35 @@ interface RegistryMethods {
 
 **注册表**：已注册的子对话（TYPE B Tellask）在根对话的注册表中跟踪，并在重启后持久化；若子对话被宣布卡死，其条目会被裁剪，不再参与后续同 slug 复用。
 
+### Root dialog fork（根对话分叉）
+
+运行中的一个完整 root dialog tree 可以在某个 root generation 起点处被 fork 成新的 root dialog。该能力用于“保留此前上下文，但从某个历史分叉点重新走后续主线/支线”。
+
+**入口**：
+
+- UI 仅对 root dialog（`selfId === rootId`）的 generation bubble 显示 `Fork 对话`
+- 后端 API：`POST /api/dialogs/:rootId/fork`
+- 请求体：`{ course, genseq, status? }`
+
+**语义（强制）**：
+
+- 选中的 generation bubble **不会**被复制到 fork 后的新 root；fork 切点语义是“从该 generation 开始前分叉”
+- 复制范围不是单个对话，而是**整棵 root dialog tree**
+- 子对话是否纳入 fork，取决于它是否已经在切点之前被根对话显式记录为已创建
+- 子对话 transcript 的保留边界由 root generation anchor 决定，而不是子对话自身的本地 `genseq`
+
+**fork 后动作**（由后端返回给 UI）：
+
+- `draft_user_text`：若目标 generation 是一条用户输入，则把该文本回填到新对话输入框中，等待用户决定是否发送
+- `restore_pending`：若切点之前存在待处理 Q4H 或待处理子对话，则恢复这些阻塞态，让新 root 继续处于阻塞状态
+- `auto_continue`：若切点之前没有待处理阻塞，则新 root 以 `interrupted(system_stop: fork_dialog_continue)` 初始化，UI 随后立即发送 `resume_dialog`
+
+**一致性要求**：
+
+- fork 必须保留同一 Taskdoc 引用
+- fork 后的 root/subdialog 都落到 `running/`，并拥有新的 rootId
+- 前端不得对 sideline dialog 暴露该入口；当前实现仅支持 fork root dialog
+
 ### 子对话课程头（强制）
 
 每次子对话 course 开始时，运行时必须在 assignment prompt 前插入角色头：