pi-dag-workflow 0.0.0-stage → 0.7.0

package/README.md

@@ -1,3 +1,212 @@
-# Temporary Holding Version
+# pi-dag-workflow
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![CI](https://github.com/Raix2215/pi-dag-workflow/actions/workflows/ci.yml/badge.svg)](https://github.com/Raix2215/pi-dag-workflow/actions/workflows/ci.yml)
+[![Pi extension](https://img.shields.io/badge/Pi-extension-blue)](https://pi.dev)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+English | [简体中文](README.zh-CN.md)
+
+Session-local task DAG, read-only planning, subagents, autonomous goal continuation, resilient error recovery, and multi-session team collaboration for [Pi](https://pi.dev). Maintain one authoritative task list in your current session, monitor background agents in real time, and verify evidence before marking work complete.
+
+![Task dependencies in the English interface](assets/overview.en.png)
+
+*Example data rendered by the actual panels; no model requests were used to create the previews.*
+
+## Highlights
+
+- **Prerequisite tracking** — Enforce execution order with `blockedBy`. Tasks cannot start, complete, or dispatch until their prerequisites are fulfilled.
+- **Read-only planning** — Read the code and structure the work before enabling implementation or child dispatch.
+- **Parallel subagents** — Dispatch up to 8 independent Pi child processes with explicit tool allowlists, skill sets, bounded task briefs, and same-task resumption.
+- **Goal continuation** — Continue long-running objectives across model turns with configurable pause policies, research modes, and pause-time progress notes.
+- **Error retry** — Automatically retry model and network failures across configurable intervals and fallback models when enabled.
+- **Team collaboration** — Coordinate independent Pi sessions in one workspace via point-to-point mailboxes, PID-verified liveness, and dynamic runtime model reconfiguration.
+
+## Installation
+
+Install the extension directly into Pi:
+
+```bash
+pi install https://github.com/Raix2215/pi-dag-workflow
+```
+
+Restart Pi or execute `/reload`. Enable or disable specific modules anytime using `pi config`.
+
+Enable Todos, Plan, Agents, Goal, Retry and Team independently or in combination via `pi config`; Display is provided by any enabled module, not enabled separately.
+
+### Compatibility & Requirements
+
+- **Pi**: `1.3.0` or newer (Pi 1.0–1.2 are outside verified compatibility).
+- **Node.js**: `>= 22.19.0` (required by package engines; subagents require a Node-based Pi host).
+- **Terminal Font**: A [Nerd Font](https://www.nerdfonts.com/) is recommended for tab and status icons.
+- **Localization**: Supports English and Simplified Chinese interfaces (`auto`, `en`, `zh-CN`).
+- **Team launches**: Modes depend on installed terminals. Windows supports supported desktop terminals through direct argv; shell-based tmux, background, copy-command and custom-template launches are refused.
+
+> **Note**: To prevent command and tool conflicts, avoid running multiple extensions providing identical names (e.g. standalone `todo`, `/plan`, `/goal`, `/retry`, or `subagent_spawn`).
+
+## Quick Start
+
+A typical workflow progresses from planning to execution and autonomous continuation:
+
+1. **Plan safely without executing actions**:
+   ```text
+   /plan start
+   ```
+   Direct Pi to investigate the codebase and draft a Todo dependency graph:
+   > "Inspect auth routes, plan token refresh with regression tests, and organize dependencies."
+
+2. **Exit planning and review the task graph**:
+   ```text
+   /plan off
+   /todos
+   /dag
+   ```
+   `/todos` opens the interactive docked panel (`/todos paths` and `/todos flat` switch views); `/dag` opens the full scrollable dependency view.
+
+3. **Drive continuous execution across turns**:
+   ```text
+   /goal new Implement token refresh and verify with tests
+   /goal enable #1
+   ```
+
+---
+
+## Core Modules
+
+### 1. Tasks & Dependency DAG (`todo`)
+
+The model interacts with the session DAG through the `todo` tool. Create tasks atomically in batches of 1–50 operations:
+
+```json
+{
+  "action": "batch",
+  "operations": [
+    { "action": "create", "ref": "audit", "subject": "Audit authentication endpoints" },
+    { "action": "create", "subject": "Implement refresh token", "blockedBy": ["@audit"] }
+  ]
+}
+```
+
+- **Atomic transactions**: `@ref` allows later creates within the batch to reference earlier ones. If any operation fails, the entire task list remains unchanged.
+- **State lifecycle**: Tasks use `pending`, `in_progress`, `completed`, `failed`, `cancelled`, and `deleted`. Prerequisites must be completed before work begins. Completed tasks are terminal; create new work for rework.
+- **Querying state**:
+  - `{"action": "list", "ready": true, "limit": 50}`: List executable tasks whose prerequisites are satisfied (paged up to 200).
+  - `{"action": "get", "id": 1}`: Inspect task details, direct blockers, and downstream dependants (`blocks`).
+  - `{"action": "status"}`: Retrieve a compact read-only summary of mode, task counts, protection, and retry state.
+- **Delivery vs. acceptance**: A child process completion or tool report delivery does not complete a task. The main session must independently verify files and tests before marking it `completed`.
+
+### 2. Read-only Plan Mode (`/plan`)
+
+Toggle plan mode with `/plan start` and `/plan off` (inspect settings and tools via `/plan settings` and `/plan tools`):
+- Strictly blocks file writes, edits, and all shell execution tools (`bash`, `powershell`).
+- Forbids subagent dispatch and starting or completing tasks.
+- Allows reading files, searching repositories, asking structured user questions, and creating or adjusting task definitions.
+
+### 3. Parallel Subagents (`agents`)
+
+Dispatch independent background Pi child processes for isolated, verifiable assignments:
+- **Strict single tier**: The main session dispatches child agents; child agents cannot spawn further subagents.
+- **Configuration resolution**: Settings resolve through parent defaults -> named profiles -> call-level overrides (`model`, `thinking`, `tools`, `skills`).
+- **Bounded briefs**: The `context: true` parameter supplies a concise brief (capped at 2,000 characters) containing prerequisite states and artifact references.
+- **Skills**: Attach up to 8 local Markdown files (<= 64 KiB each); requires `read` in the child's active tool set (inherited or explicitly declared). Skills are local file references, not additional tools or permissions.
+- **Steering & resumption**: Inspect running jobs with `subagent_inspect`, send messages or preflight tool updates via `subagent_send`, or resume prior attempts using `resumeFrom`.
+- **Sandbox boundaries**: Profile `isolate` restricts extension loading for Team/manual session launches; child tool selection controls the selected tool set. Neither provides an OS or credential sandbox, and neither rolls back file changes.
+
+For full protocol specifications, see [docs/COMMUNICATION.md](docs/COMMUNICATION.md).
+
+### 4. Autonomous Goals (`goal`)
+
+Manage multi-turn objectives with `/goal` and the `goal` tool:
+- **Safe defaults**: Creating a Goal does not auto-start it. Resumed sessions keep Goals paused until explicitly activated with `/goal enable`.
+- **Paused progress notes**: When paused, models can still record verified milestones (`progress`) or updated plans (`nextStep`) without resuming execution.
+- **Control switches**:
+  - `nopause`: Forbids interactive user questionnaires and mid-flight stops, but does *not* grant unlimited error retries.
+  - `nolimit`: Removes the default 32-turn continuation limit without altering error retry counts.
+  - `autoresearch`: Enforces continuous investigation loops without marking the Goal complete.
+
+### 5. Error Recovery (`retry`)
+
+Configure automated recovery from API failures, quota exhaustion, authentication errors, and network drops via `/retry`:
+- **Default state**: Error retry is disabled by default (`off`).
+- **User-defined intervals**: When enabled, the model retries using a sequence of specified pauses (e.g., `/retry when-error 5s,15s,30s count 3`). The `count` parameter is optional; omitting it allows recurring retries across the intervals without a fixed streak cutoff. Quota and authentication failures follow the same configured intervals.
+- **One recovery owner**: With Retry enabled, Goal hands failures to it. Otherwise Goal uses its own bounded error backoff; its allowance is separate from Retry's count.
+- **Fallback models**: Designate alternate models (`/retry models provider-b/backup-model`; replace this placeholder with a registered model). When the active model exhausts `after` consecutive plugin retry attempts (default 2; initial request failures and host-native retries do not count toward `after`), execution advances to the next candidate model while sharing the overall `count` budget. When the total `count` is exhausted, retries stop completely without switching further.
+- **Compaction resilience**: When an error is followed by session compaction, continuation respects the `resumeAfterCompaction` setting and user pause controls rather than restarting unconditionally.
+- **Safe restoration**: Reloading or resuming a session preserves retry parameters but resets state to `armed/off` without resurrecting defunct timers.
+
+### 6. Multi-session Teams (`team`)
+
+Open `/team` to create a team, then expand its row to join the current conversation or start a new member session. Starting a member does not move this conversation to that team.
+
+Connect multiple independent Pi sessions in the same workspace:
+- **Minimal model interface**: Models are restricted to two tools: `team_send` (point-to-point messaging) and `team_inspect` (`scope: "team"` reads the joined team, not the UI's viewed team, paged <= 20 members / 4 KiB; the default query reads self. Member snapshots <= 2 KiB, reply preview 240 characters, activity default 3 max 10).
+- **User-role transport security**: Team messages travel over user-role channels. **Agent-authored messages do not constitute human authorization or grant expanded privileges.**
+- **PID liveness**: Member presence is verified via operating system process checks and real event records, avoiding spurious heartbeat timeouts. Disbanding archives team records without killing processes or deleting session files.
+- **Live runtime reconfiguration**: From the Team panel, users can update a target member's model or reasoning level. Changes take effect before the target's next turn once its current reply and tool batch finish; submission is an update request, confirmed only when acknowledged by the target runtime. Switching providers directs subsequent turns to that provider. Existing running sessions require `/reload` to pick up newly added capabilities.
+- **Names and lifecycle**: Member labels and Pi session names are separate edits, addressed by full SID. Stop/removal preserves saved sessions and mailboxes; session-file/mailbox deletion is a separate confirmed action.
+- **Clean startup**: Newly initialized blank team sessions respond with a brief startup confirmation before awaiting explicit assignments. Ordinary joins, re-attaching existing sessions, and `/reload` do not repeat this confirmation.
+- **Read-only History**: Inspect session transcripts with Pi's native TreeSelector (press `Enter` to view entry content, `Esc` to return to the tree list, and `Esc` again to exit back to the Team panel).
+
+![Team runtime settings in the English interface](assets/team.en.png)
+
+---
+
+## Docked Panels & Navigation
+
+Running `/todos`, `/plan`, `/goal`, `/agents`, `/team`, `/retry`, or `/dag-display` opens a docked panel above the editor. Six extension modules are independently selectable in `pi config`; Display is shared UI, not a seventh extension. Disabled modules are omitted from the tab bar.
+
+### Keyboard Shortcuts
+
+| Key | Navigation / Action |
+|---|---|
+| `Tab` / `Shift+Tab` | Switch between active module tabs in place |
+| `j` / `k` or `↓` / `↑` | Move row cursor down / up |
+| `g` / `G` | Jump to the first row of the upper / lower zone |
+| `←` / `→` | Scroll active zone by one screen |
+| `h` / `l` | Collapse / expand details inline |
+| `Enter` | Toggle switch, cycle option, edit text inline, or execute action |
+| **Double `Enter`** | **In-place red prompt confirmation** for destructive actions (no popup page or window resizing) |
+| `/` | Live filter / search within active view |
+| `Esc` | Cancel inline edit, collapse view, or close the panel |
+
+Panels automatically scale to terminal height without artificial row limits. User input and confirmation workflows are never interrupted by background periodic refreshes. Above-editor widgets hide while panels are open and restore upon dismissal.
+
+### Display Preferences (`/dag-display`)
+
+Open `/dag-display` or select the **Display** tab to configure interface preferences:
+- **Icon style**: Switch between Nerd Font icons and plain text symbols.
+- **Language**: Choose `auto` (terminal locale), `en`, or `zh-CN`.
+- **Status widgets**: Independently toggle persistent widgets for Todos, Plan, Goal, Agents, and Retry.
+- **Model column width**: Configure display width limits for model labels.
+
+---
+
+## Commands & Tools Quick Reference
+
+| Module | Slash Command | Registered Tools | Description |
+|---|---|---|---|
+| **Todos** | `/todos`, `/dag` | `todo` | Task DAG, dependency ordering, status updates, batch definition, `/todos paths`, `/todos flat` |
+| **Plan** | `/plan` (`start`, `off`, `status`, `settings`, `tools`) | — | Read-only planning mode, shell/write block, and allowlist inspection |
+| **Agents** | `/agents` | `subagent_spawn`, `subagent_inspect`, `subagent_send`, `subagent_cancel` | Single-tier child process dispatch, steering, and verification |
+| **Goal** | `/goal` | `goal` | Multi-turn objective continuation, `nopause`, and `autoresearch` |
+| **Retry** | `/retry` (`when-error`, `models`, `on`, `off`, `status`) | — | Error interval backoff, streak limits, and candidate model fallback chains |
+| **Team** | `/team` | `team_send`, `team_inspect` | Multi-session workspace collaboration, mailboxes, and live controls |
+| **Display** | `/dag-display` | — | Interface language, icons, model width, and widget visibility |
+
+---
+
+## Status & Permission Boundaries
+
+- **English model prompts & localized UI**: Internal system prompts and instructions generated by the plugin are standardized in English. UI panels and menus support full localization in English and Simplified Chinese.
+- **Session-bound state**: Tasks, Goals, and child records are tracked within the active Pi session branch. Session rollbacks do not resurrect exited child processes or revert file edits. Team rosters and mailboxes do not roll back with the Pi session branch.
+- **Isolate boundary**: Profile `isolate` restricts extension loading for Team/manual launches; tool selection limits the selected tools. Neither provides an OS sandbox or rolls back file side effects.
+- **Privacy boundary**: This extension adds no analytics or tracking requests. Model calls and other installed extensions still use their configured providers and network access.
+
+## Documentation & Community
+
+- [Agent Communication & Delivery Protocol](docs/COMMUNICATION.md)
+- [Contributing Guidelines](CONTRIBUTING.md)
+- [Security Policy](SECURITY.md)
+
+## License
+
+MIT © [Raix2215](https://github.com/Raix2215)

package/README.zh-CN.md

@@ -0,0 +1,212 @@
+# pi-dag-workflow
+
+[![CI](https://github.com/Raix2215/pi-dag-workflow/actions/workflows/ci.yml/badge.svg)](https://github.com/Raix2215/pi-dag-workflow/actions/workflows/ci.yml)
+[![Pi extension](https://img.shields.io/badge/Pi-extension-blue)](https://pi.dev)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+[English](README.md) | 简体中文
+
+为 [Pi](https://pi.dev) 提供会话级任务 DAG、只读规划、子代理、目标自动续跑、容错重试与多会话团队协作。在当前会话中维护唯一权威任务列表，实时追踪后台 Agent 动态，并在验收实证充分后将任务标记为完成。
+
+![简体中文界面的任务依赖总览](assets/overview.zh-CN.png)
+
+*图中为真实面板渲染的示例数据；制作预览未调用模型。*
+
+## 核心特性
+
+- **前置依赖编排** — 通过 `blockedBy` 约束执行顺序。前置任务未全部验收完成前，后续任务不可启动、完成或派发。
+- **只读规划模式** — 先阅读代码、检索符号并梳理任务，再切回执行模式进行实施与派发。
+- **并行子代理** — 派发最多 8 个独立的 Pi 子进程处理解耦任务，支持工具白名单、Skill 挂载、有界上下文摘要与同任务接续。
+- **目标跨轮续跑** — 通过 `/goal` 跨模型轮次推进长线任务，支持灵活暂停策略、持续研究模式及暂停态进度笔记。
+- **错误自动重试** — 遇到接口错误、配额耗尽或网络异常时，在启用状态下按指定间隔自动重试，并支持备选模型轮换。
+- **多会话团队协作** — 汇聚同一代码库下的独立 Pi 会话，提供点对点信箱、真实 PID 进程探活与会话级运行配置热切换。
+
+## 安装指南
+
+直接在 Pi 中安装本扩展包：
+
+```bash
+pi install https://github.com/Raix2215/pi-dag-workflow
+```
+
+安装后重启 Pi 或在会话中执行 `/reload`。随时可通过 `pi config` 独立启用或关闭各功能模块。
+
+Todos、Plan、Agents、Goal、Retry、Team 六个模块可通过 `pi config` 独立启用或组合使用；Display 由任一已启用模块提供，不单独启用。
+
+### 兼容性与运行环境
+
+- **Pi 版本**：`1.3.0` 或更高（Pi 1.0–1.2 不在本次发布验证范围内）。
+- **Node.js**：`>= 22.19.0`（包规范要求；子 Agent 功能需要 Node 运行时环境的 Pi 宿主）。
+- **终端字体**：推荐使用 [Nerd Font](https://www.nerdfonts.com/) 终端字体以获得完整图标支持。
+- **界面语言**：支持英文与简体中文界面（可在设置中指定 `auto`、`en` 或 `zh-CN`）。
+- **Team 启动**：启动方式取决于已安装终端。Windows 仅支持受支持桌面终端的直接 argv 启动；基于 shell 的 tmux、后台、复制命令与自定义模板启动会被拒绝。
+
+> **提示**：为避免命令与工具冲突，请勿同时装载提供同名入口的其他扩展（如独立的 `todo`、`/plan`、`/goal`、`/retry` 或 `subagent_spawn`）。
+
+## 快速上手
+
+典型工作流涵盖“只读规划 -> 结构化执行 -> 跨轮自治推进”：
+
+1. **先只读规划**：
+   ```text
+   /plan start
+   ```
+   要求 Pi 分析仓库并梳理依赖图：
+   > “分析鉴权接口改造需求，拆解为带回归测试的任务 DAG，明确依赖先后关系。”
+
+2. **退出规划并检视任务图谱**：
+   ```text
+   /plan off
+   /todos
+   /dag
+   ```
+   `/todos` 打开交互式贴靠面板（可用 `/todos paths` 或 `/todos flat` 切换树/平铺视图）；`/dag` 打开可滚动依赖全景图。
+
+3. **跨轮自主推进核心目标**：
+   ```text
+   /goal new 实现 Refresh Token 并通过端到端测试验收
+   /goal enable #1
+   ```
+
+---
+
+## 核心模块详解
+
+### 1. 任务与依赖图 (`todo`)
+
+模型通过 `todo` 工具管理会话任务图。支持在单次批量操作中原子提交 1–50 个定义变更：
+
+```json
+{
+  "action": "batch",
+  "operations": [
+    { "action": "create", "ref": "audit", "subject": "审计鉴权接口端点" },
+    { "action": "create", "subject": "实现 Refresh Token 鉴权逻辑", "blockedBy": ["@audit"] }
+  ]
+}
+```
+
+- **原子事务**：批处理支持通过 `@ref` 引用同批已经创建的任务。若其中任一步骤校验失败，整个列表状态完整回滚。
+- **状态流转**：任务状态包括 `pending`、`in_progress`、`completed`、`failed`、`cancelled`、`deleted`。前置依赖完成后才可执行。已完成任务不能重开；返工需新建任务。
+- **高频查询**：
+  - `{"action": "list", "ready": true, "limit": 50}`：仅列出前置已完成、可立即执行的任务（单页最多 200 条，支持游标续页）。
+  - `{"action": "get", "id": 1}`：查看任务完整定义、直接前置与下游受阻任务（`blocks`）。
+  - `{"action": "status"}`: 获取紧凑只读摘要（规划模式、任务计数、保护项及重试状态）。
+- **交付不等于验收**：子进程完成报告交付只代表执行结束；主会话必须在独立检查代码修改和测试证据后，才显式将任务标记为 `completed`。
+
+### 2. 只读规划模式 (`/plan`)
+
+通过 `/plan start` 开启、`/plan off` 退出（可通过 `/plan settings` 查看设置，`/plan tools` 查看只读工具）：
+- 严格拦截文件写入、编辑以及一切 Shell 执行工具（`bash`、`powershell`）。
+- 严禁子进程派发，禁止将任务标记为进行中或已完成。
+- 允许文件阅读、代码符号检索、用户结构化提问以及创建或调整任务定义。
+
+### 3. 并行子代理 (`agents`)
+
+派发独立的后台 Pi 子进程执行高内聚、可独立验收的子任务：
+- **严格单层结构**：主会话派发子 Agent；子 Agent 严禁进一步派发下层进程（无孙子代理）。
+- **配置确定性解析**：参数按“父配置基线 -> 具名 Profile -> 显式单次调用参数（`model`、`thinking`、`tools`、`skills`）”依次覆盖。
+- **有界上下文摘要**：开启 `context: true` 时提供前置状态和产物引用的有界摘要，上限 2,000 字符；不替代完整任务要求。
+- **Skill 挂载**：支持引用最多 8 个本地 Markdown 文件（单文件 <= 64 KiB）；要求子进程可用工具集中包含 `read` 工具（继承或显式声明均可）。Skill 只作为本地文件引用，不增加工具或权限。
+- **动态指导与接续**：通过 `subagent_inspect` 监视状态，`subagent_send` 发送指令或预检替换工具集，或使用 `resumeFrom` 在保留同任务绑定的前提下继续未完工作。
+- **隔离与沙盒边界**：Profile `isolate` 限制 Team／手工会话启动时的扩展装载，子 Agent 的工具选择限制其所选工具；两者均不构成操作系统沙盒或凭据隔离层，亦无法自动回滚文件修改等外部副作用。
+
+完整通信与报告交付协议参见 [docs/COMMUNICATION.md](docs/COMMUNICATION.md)。
+
+### 4. 目标跨轮续跑 (`goal`)
+
+通过 `/goal` 及模型工具 `goal` 驱动多轮长期目标：
+- **安全启动**：创建 Goal 不会自动激活；会话重载或恢复后保持暂停，必须由用户通过 `/goal enable` 显式开启。
+- **暂停态笔记**：在 Goal 暂停期间，模型仍可记录已验证的里程碑（`progress`）或调整下一步计划（`nextStep`），不影响暂停状态。
+- **控制开关**：
+  - `nopause`：运行中禁止向用户发起常规确认提问，但**不代表**无限错误重试。
+  - `nolimit`：解除默认 32 轮续跑上限，不影响已设定的错误重试阈值。
+  - `autoresearch`：开启持续自主探索模式，不自动将 Goal 标记为完成。
+
+### 5. 错误自动重试 (`retry`)
+
+通过 `/retry` 配置应对模型调用失败、配额耗尽、鉴权错误或网络中断：
+- **默认关闭**：错误重试默认处于关闭状态（`off`）。
+- **用户自定义间隔**：启用后按用户指定的等待时长序列循环重试（例如 `/retry when-error 5s,15s,30s count 3`）。`count` 为可选参数，省略时允许按该间隔列表持续重试，不设固定断点。配额与鉴权失败同样遵循该间隔配置。
+- **恢复只由一方负责**：Retry 开启时，Goal 将失败移交给它；否则 Goal 使用自己的有界错误退避，两者次数独立记账。
+- **备选模型轮换**：配置备选模型列表（`/retry models provider-b/backup-model`；将占位名称替换为实际注册模型）。当当前模型连续用尽 `after` 次插件重试尝试（默认 2 次；初始请求失败与宿主原生重试不计入 `after`）后，按顺序切换至下一个候选模型，所有重试共享总 `count` 次数额度。若总 `count` 额度耗尽，重试完全停止，不会换模型继续。
+- **压缩续接控制**：当错误发生后紧接会话压缩时，恢复逻辑遵循 `resumeAfterCompaction` 设置与用户暂停控制，受控恢复而非无条件续接。
+- **安全恢复机制**：会话分支恢复时保留配置但回到 `armed/off` 状态，不会在后台自动复活旧计时器。
+
+### 6. 多会话团队协作 (`team`)
+
+打开 `/team` 创建团队，再展开团队条目，选择加入当前对话或新建成员会话。新建成员不会改变本会话的归属。
+
+将同一工作区下的多个独立 Pi 会话编组协作：
+- **精简模型接口**：仅向模型暴露两个工具：`team_send`（点对点投递）与 `team_inspect`（`scope: "team"` 查询本会话所属团队，而非面板正在查看的团队，单页 <= 20 人 / 4 KiB；默认查自己。成员快照 <= 2 KiB，回复预览 240 字符，活动默认 3 条最多 10 条）。
+- **消息安全准则**：团队消息通过 user-role 传输通道投递。**Agent 所发团队消息绝不代表人类授权，亦不能藉此扩展权限。**
+- **基于真实 PID 探活**：成员存活按系统 PID 探测，活动来自真实事件，不按心跳超时判断进程死亡。解散团队仅作状态归档，不终止进程，不删除会话文件。
+- **运行配置热调整**：用户可在 Team 面板直接调整目标成员的模型或思考级别；目标成员忙时需等待当前回复与工具批次结束，下一轮请求前生效；提交仅为请求，以目标运行时实际回执为准；切换提供商后后续请求自动发送至该提供商。已有运行中的会话进程需手动执行 `/reload` 方能加载新能力。
+- **名称与生命周期**：成员名与 Pi 会话名独立修改，按完整 SID 寻址。停止／移出保留会话与信箱；删除会话及信箱是单独的确认操作。
+- **纯净空白启动**：新建空白会话仅执行首轮收到确认，不调用工具或执行任务；普通加入、恢复已有会话及 `/reload` 均不重复执行该确认。
+- **只读历史查看**：通过 Pi 原生 TreeSelector 只读翻阅会话历史记录（按 `Enter` 查看选中条目正文，按 `Esc` 返回树列表，再次按 `Esc` 退出历史并返回 Team 面板）。
+
+![简体中文界面的 Team 运行配置](assets/team.zh-CN.png)
+
+---
+
+## 交互式面板与键盘操控
+
+执行 `/todos`、`/plan`、`/goal`、`/agents`、`/team`、`/retry` 或 `/dag-display` 即可在输入框上方展开贴靠面板。六个扩展模块可通过 `pi config` 独立选择；Display 是共享界面，不是第七个扩展，标签栏省略未启用的模块。
+
+### 键盘快捷键一览
+
+| 按键 | 导航与操作说明 |
+|---|---|
+| `Tab` / `Shift+Tab` | 在已启用的模块标签页之间就地切换 |
+| `j` / `k` 或 `↓` / `↑` | 上下移动当前光标所在行 |
+| `g` / `G` | 快速跳转至上区 / 下区首行 |
+| `←` / `→` | 当前区域按整屏向上 / 向下翻页 |
+| `h` / `l` | 就地折叠 / 展开选中条目的详细信息 |
+| `Enter` | 切换开关、轮转选项、行内编辑文本或触发动作 |
+| **双击 `Enter`** | **原位红字确认**破坏性操作（无独立弹出页，无需放大窗口） |
+| `/` | 激活实时过滤与关键词检索 |
+| `Esc` | 取消正在进行的编辑、折叠层级或关闭停靠面板 |
+
+面板高度自动适配终端尺寸，无 17 行硬性上限；用户的输入与确认流程不会被后台周期刷新打断。面板展开期间，输入框上方的状态挂件自动暂时隐藏，关闭后无损恢复。
+
+### 界面与显示设置 (`/dag-display`)
+
+通过 `/dag-display` 或面板中的 **Display** 标签定制界面风格：
+- **图标风格**：支持在 Nerd Font 图标与纯文本 ASCII 符号间切换。
+- **界面语言**：可选择 `auto`（随系统区域环境）、`en` 或 `zh-CN`。
+- **状态挂件**：独立控制 Todos、Plan、Goal、Agents、Retry 在输入框上方的常驻状态条显隐。
+- **模型名显示宽度**：自定义状态行与列表中模型名称的最大截断列宽。
+
+---
+
+## 命令与模型工具速查
+
+| 模块 | 斜杠命令 | 注册的模型工具 | 简要说明 |
+|---|---|---|---|
+| **Todos** | `/todos`, `/dag` | `todo` | 任务 DAG 依赖编排、状态管理、批量事务、`/todos paths` 树视图、`/todos flat` 平铺视图 |
+| **Plan** | `/plan` (`start`, `off`, `status`, `settings`, `tools`) | — | 只读规划模式切换、Shell/写入拦截与只读白名单查看 |
+| **Agents** | `/agents` | `subagent_spawn`, `subagent_inspect`, `subagent_send`, `subagent_cancel` | 单层子进程派发、状态探查、动态指令与验收管理 |
+| **Goal** | `/goal` | `goal` | 多轮目标自主续跑、`nopause` 模式、`autoresearch` 持续探索 |
+| **Retry** | `/retry` (`when-error`, `models`, `on`, `off`, `status`) | — | 错误阶梯退避、重试阈值与候选模型故障轮换 |
+| **Team** | `/team` | `team_send`, `team_inspect` | 同仓库多独立会话协作、信箱流转与运行配置热改 |
+| **Display** | `/dag-display` | — | 显示语言、图标风格、模型名宽度与常驻挂件显隐 |
+
+---
+
+## 状态与权限边界
+
+- **系统模型指令英文统一与多语言 UI**：插件自编的系统提示与模型指令统一采用 **英文**。面板与交互菜单提供完整的英文与简体中文本地化支持。
+- **分支权威与持久化**：任务、目标及子进程记录紧密绑定当前 Pi 会话分支。分支回滚不会自动复活已退出的外部进程，亦不回滚工作区文件修改。Team 名册和信箱不随会话分支回滚。
+- **Profile 隔离边界**：Profile `isolate` 限制 Team／手工会话启动的扩展装载，工具选择限制所选工具；两者均不构成操作系统级进程沙盒，无法自动撤销工具执行带来的外部副作用。
+- **隐私边界**：本扩展不添加分析统计或追踪请求；模型调用和你安装的其他扩展仍遵循各自的提供方与网络配置。
+
+## 公开参考链接
+
+- [Agent 通信与报告交付规范](docs/COMMUNICATION.md)
+- [贡献指南 (CONTRIBUTING)](CONTRIBUTING.md)
+- [安全策略 (SECURITY)](SECURITY.md)
+
+## 开源协议
+
+MIT © [Raix2215](https://github.com/Raix2215)

package/docs/COMMUNICATION.md

@@ -0,0 +1,129 @@
+# Agent communication
+
+Reference for child jobs, report delivery, task acceptance, and continuation. For installation and examples, see the [README](../README.md#subagents).
+
+## Assignment and configuration
+
+`subagent_spawn` starts one child Pi process. The assignment should include the objective, input paths, scope, and expected verification evidence. A linked `todoId` must be ready.
+
+For a new job, configuration resolves in order: the parent's model, thinking level, and active supported built-in tools; a named profile's declared fields; then explicit call-level `model`, `thinking`, `tools`, and `skills`. `profile: "inherit"` explicitly resets to the current parent state. Implicit thinking can adapt down to a supported level. An explicitly unsupported level fails.
+
+Explicit `model` takes an exact registered `{ provider, id }`. Discover one with `subagent_inspect({ models: true, query, limit, offset })`; the catalog returns provider, id, name, reasoning, context limits, and input modes, with `limit` defaulting to 20 and capped at 100 and no endpoints or credentials. Model discovery cannot be combined with job, profile, output, or wait fields.
+
+Child tools include built-ins and explicitly selected tools from configured childExtensions, without a fixed tool-count limit. subagent_inspect({tools:true}) returns name, description and core/extension origin. childExtensions is read at dispatch time; paths may be absolute, ~/ paths, or relative to the configuration directory. Missing or unreadable files reject dispatch before startup. A registered shell tool does not make the program it runs executable, and tool selection is not an operating-system sandbox. When unsupported inherited tools are filtered out, the spawn result reports them as `ignoredInheritedTools`.
+
+A child works in the same directory, discovers workspace rules, and has independent conversation history. Selected profile instructions and `context: true` guidance arrive as task context. Ordinary task briefs contain the current requirements excerpt, direct prerequisite states, current valid report excerpts, and declared `metadata.artifacts` references. Fragment briefs include position and state from the same fragment instance. Briefs are bounded to 2,000 characters and never use stale reports as current evidence. Ordinary task briefs mark omitted input. Supply all required input in the assignment; references are unverified, and full output remains available through inspection.
+
+`skills` selects up to eight local Markdown files; paths resolve from the dispatch working directory, `~/`, or an absolute path. Omitted `skills` inherits the base, `[]` disables skills, and a list replaces it. Dispatch requires readable, nonempty files no larger than 64 KiB and an already selected `read` tool; `read` is never added implicitly, and skills are not auto-discovered or turned into system prompts. Entries arrive as task references; bodies are read on demand. Skill text does not change tools or permissions, activate extensions/MCP, or override later direction.
+
+The child has `subagent_send` for parent communication. It cannot delegate children, and it does not run the parent's Goal. Its model auto-retry is disabled.
+
+## Information routes
+
+| Route | Model-facing content | Timing |
+|---|---|---|
+| Child `subagent_send` | Report or question with job ID and optional request ID | Next safe parent boundary; an idle parent can be woken |
+| Child success | Finalized retained output and completion report | Automatic report channel |
+| Child failure | Bounded diagnostic and recovery guidance | Automatic report channel; full output is retained |
+| Parent `subagent_spawn` | New job ID, startup status, linked Todo status, and optional continuation origin | Current tool result |
+| Parent `subagent_inspect` | Short job status/activity/questions, or explicit profile/model catalog query | Immediate tool result |
+| Parent `subagent_inspect`, `output: true` | Retained output, questions, usage, observation, and linked Todo status | Snapshot or bounded wait result |
+| Parent `subagent_send` | Delivery confirmation | Current tool result; subsequent child replies use the report channel |
+| Parent `subagent_cancel` | Stop/removal confirmation | Current tool result |
+| `/agents wait` | User-visible report and diagnosis | Readable text notification |
+
+A tool result is available to the following model request. Reports enter at `turn_end` or `agent_before_settle`, after the current tool batch; an idle report wake uses a follow-up message. Reports do not interrupt a tool batch already in progress.
+
+## User menus
+
+`/agents` opens a searchable, paginated job directory with attention and history filters. Selected details distinguish process status, report delivery, and linked Todo acceptance. Read reports, answer pending questions, send direction, or stop/remove a job from its action page. Cancellation and removal require confirmation and do not undo files.
+
+The root `/agents` menu lists Profiles inline and opens the model catalog. Argument commands such as `/agents profiles`, `/agents list`, and `/agents wait` print readable text instead of opening those views. The instruction and skill editors save only the confirmed current profile; cancellation and expired input leave it unchanged.
+
+Opening a menu or changing summary visibility does not start model requests or stop a job. `/agents show` and `/agents hide` affect only the Agent summary. The Agents feature can run independently; `todoId` bindings require the Todos feature.
+
+## Queries and delivery
+
+`subagent_inspect` without `output` returns short status. With `output: true`, it requires one `jobId` and accepts:
+
+| Parameter | Behavior |
+|---|---|
+| `timeout: 0` | Immediate output snapshot |
+| `until: "update"` | New report, question, or end; default timeout 5 seconds |
+| `until: "finish"` | Terminal execution or a question; default timeout 30 seconds |
+| `after` | Wait beyond a known `reportVersion` |
+| `timeout` | Explicit wait duration, up to 300 seconds |
+
+A wait timeout or abort only stops that wait. The background child remains active until it ends, reaches its job deadline, or is explicitly cancelled. Queries for profiles cannot collect output.
+
+Successful and failed terminal jobs use `reportDelivery`:
+
+- `pending`: the terminal report has not been handed to a parent model request.
+- `delivered`: a real request's context hook received the automatic report, or an output query returned it to the model.
+
+A proposed boundary entry is not delivery confirmation. If another extension discards it, the report can be proposed again within bounded attempts. A persisted report filtered from model context is not replayed automatically; query its output explicitly.
+
+Output collection acknowledges the returned terminal report and removes matching buffered notices. Version-aware acknowledgement preserves newer reports. Ordinary status queries and `/agents wait` leave delivery status unchanged.
+
+## Task acceptance and display
+
+| Current state | Linked task row |
+|---|---|
+| Successful job, report pending, Todo unfinished | Pending delivery |
+| Successful job, report delivered, Todo unfinished | Pending verification |
+| Accepted Task | Completed |
+| Latest failed/interrupted attempt still current | Failure/interruption state |
+| Explicitly dismissed attempt, Todo unfinished | Main session / Ready to resume |
+| Main-session takeover | Canonical Todo owner and state |
+| New active attempt | New job/profile and live activity |
+
+Delivery is not acceptance. The main session verifies files, tests, and other evidence before marking a Todo completed. A job may report on an accepted step while continuing a serial assignment; the Todo owns its accepted state, while `/agents` still shows the actual job status.
+
+All task filters use the latest attempt. A stale latest attempt retires its outcome rather than reviving an older verdict. Native Todo terminal states take precedence. Default Standalone display hides dismissed attempts and delivered successful jobs; explicit outcome filters can show their history.
+
+## Direction and questions
+
+Child `subagent_send({ message, question: true })` waits for an answer. The parent uses `subagent_send({ requestId, message })` to answer that input request.
+
+Parent direction uses `subagent_send({ recipient, message })`. Normal direction enters at a safe steering boundary. `interrupt: true` clears obsolete queued work, aborts the current local turn, cleans the idle queue, and sends a new direction in the same child context. Adding `tools` requires `recipient` and `interrupt: true` and forbids `requestId`. The child first checks the requested set without changing state, under a bounded 5-second confirmation; only after that preflight passes does it clear queued work, interrupt the current turn and questions, apply and confirm the tools, and deliver the direction. The main session decides this change under user authorization — a child's request is not authorization, and tool selection is not a sandbox. A preflight failure leaves the child, queue, and questions unchanged. If a mutating step fails after a change, the attempt stops and the structured result reports the stage, job status, `interrupted`/`queueCleared`/`questionsCleared`/`toolsApplied` as `true`, `false`, or `null`, `directionDelivery`, last confirmed tools (`currentTools`), and recovery guidance; it never implies that questions or external side effects were rolled back. Confirmation is `accepted`, `queued`, or `answered`; inspect evidence to determine whether work followed the direction.
+
+Changing the task definition, declared artifact references, or fragment identity invalidates earlier acceptance evidence. Interrupting the child starts a new report scope. Old output remains queryable, with `outputStart` separating historical text from the current assignment. Late reports from an old tool batch remain historical until the new direction is consumed.
+
+## Failure, cancellation, and continuation
+
+A model error, unexpected process exit, invalid RPC record, startup failure, or job deadline closes the attempt and releases its process slot. Failure results include a bounded, sanitized root-cause summary, classification, and recovery guidance. Finalized partial text and diagnostic output remain available. A streaming fragment that never finalized before a crash may not be retained.
+
+The default execution deadline is 600 seconds; spawn `timeout` can set up to 86,400 seconds. Model retry stays under parent control: resolve the cause, verify partial artifacts and external side effects, then continue explicitly.
+
+`resumeFrom` creates a new attempt:
+
+- Keep the original Todo binding and saved assignment.
+- Supply the current continuation task.
+- Start from the previous attempt's actual model, thinking, tools, skills, and instructions without rereading its old profile; an explicit `profile` overrides its declared fields, explicit `tools`/`skills` replace those lists, and `profile: "inherit"` resets to the current parent.
+- Reject changed Todo definitions; use a fresh self-contained assignment for the current scope.
+- Supply full instructions when the retained record has no saved original assignment.
+- Retain the old execution record and report history.
+
+Cancellation dismisses unsuccessful or interrupted attempts from the current panel. It does not change Todo acceptance or reverse project edits. An already successful job with an undelivered report keeps that report; `remove: true` explicitly discards the record.
+
+A parent abort during authentication/startup cancels dispatch and leaves its Todo unclaimed. After dispatch succeeds, parent waiting or ordinary-turn cancellation does not stop stable background work. A cancelled mutating direction with an unknown outcome stops the child; a failed composite redirect closes the attempt. Already-triggered external actions may still finish, so check their authoritative state before repeating work.
+
+## Goal and recovery context
+
+Automatic child-report wakes and Goal continuations share the active Goal's allowance. Plan, Goal pause, Agent-delivery pause, or an exhausted finite allowance suppresses automatic wakes. Model failures hold buffered reports while native Pi or user-enabled `/retry` recovery runs. Successful recovery reopens delivery. `/retry` is off by default, applies only to the main session, and does not restart children. Its Goal requests obey the remaining continuation allowance; Plan remains read-only. Optional model replacement uses a user-confirmed ordered list, sharing the same intervals and total retry count. It changes only the parent's session selection; existing children keep their captured model and settings. Candidate exhaustion pauses Goal error recovery, including continuous research. User cancellation and branch changes cancel obsolete recovery. Restoring a session keeps saved Retry settings and its enabled switch, returning to armed if it was enabled (or off if disabled) while cancelling any old pending timer; Goal restoration, by contrast, is always paused and requires explicit re-enabling (`/goal enable`).
+
+`/agents resume` permits future report arrivals. Retrieve previously suppressed reports explicitly. Restoring or switching a session stops managed child processes and restores their records as interrupted; it does not revive execution or automatically resume the Goal.
+
+Workflow checkpoints carry bounded Todo/Job summaries. Goal checkpoints retain original requirements and execution policy. Normal changes append at safe boundaries; a current active Goal contract missing after ordinary context transforms is appended through Pi's public final-context event. System messages, prior messages, reports, and memory-owned summaries remain intact. A later owner of that final event can still transform its result.
+
+`/goal autoresearch [#id] [on|off]` toggles continuous autonomous research for one Goal without starting it or replacing its saved `nolimit`/`nopause` controls. While selected, it forces unlimited continuation and model-pause denial; those forced values are separate from the saved ordinary-mode settings and the Goal's actual running state, and they do not change `/retry`. It rejects model completion or Goal switching. Stages and Todos remain individually verifiable. User stops, Plan, error limits, and compaction protections still pause work; restore requires explicit enable. Mode or scope changes during pending error recovery can retire the old request and pause the Goal without clearing used turns.
+
+Short continuation messages refer to the current Goal contract. Ordinary Goals verify every requirement before completion; continuous Goals verify milestones and proceed to another useful step without completing the whole Goal. These messages do not authorize a smaller objective or additional permissions. Only important new evidence or a changed execution decision calls for `goal update`. While a Goal is paused, `goal update` can still record `progress` or `nextStep` notes for the currently focused Goal without re-enabling the Goal, waking execution, or altering its budget or scope; non-current, never-focused, completed, or deleted Goals cannot write to the shared run.
+
+## Retained data and cleanup
+
+Todo cleanup and job pruning preserve active processes, undelivered reports, successful work awaiting acceptance, and required dependencies. Explicit record removal is available separately. IDs retain their high-water marks across cleanup and restore.
+
+Job state is saved as branch-local metadata and output deltas. Original assignments are retained for continuation. State records are not model-context messages. Live thinking/tool/output activity updates only the UI.
+
+Reports and full output can be long; they consume context and session storage when queried or delivered. Display removes terminal control characters. Diagnostic summaries redact common credential forms, but arbitrary child report text still needs review before sharing. Child credentials and process environment are not an operating-system isolation boundary.