cmdr-mcp 0.1.0 → 0.1.1

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
     {
       "name": "cmdr",
       "source": "./plugins/cmdr",
-      "version": "0.1.0",
+      "version": "0.1.1",
       "description": "Local multi-agent squads with durable messages, roles and lifecycle reminders."
     }
   ],

package/README.md

@@ -8,7 +8,7 @@
 
 Requires macOS or Linux and **Node.js ≥22.5** (24 recommended). Git contains source and plugin metadata; generated bundles are included only in npm distribution packages.
 
-The npm package is **`cmdr-mcp`**; the CLI and host plugin remain **`cmdr`**. After the first registry release, install with:
+The npm package is **`cmdr-mcp`**; the CLI and host plugin remain **`cmdr`**. Install with:
 
 ```sh
 npm install --global cmdr-mcp
@@ -26,7 +26,7 @@ For distribution, `npm pack` (or `npm publish`) runs `prepack` to build the four
 
 ```sh
 npm pack
-npm install --global ./cmdr-mcp-0.1.0.tgz
+npm install --global ./cmdr-mcp-0.1.1.tgz
 cmdr --help
 ```
 
@@ -97,6 +97,19 @@ Exactly seven MCP tools are exposed, independently of the host:
 
 Every successful tool result includes identity, recommended wait and unread count. Reports carry their status in `message.data.status`. Unread messages are retained across daemon restarts; reads mark them delivered and leave history. There is no processing acknowledgement: if a host crashes after delivery, use history to recover the work.
 
+## Installation diagnostics and member CLI
+
+If cmdr tools are absent, inspect the host's actual plugin cache with `cmdr doctor --plugin-root /path/to/cached/plugin`. Add `--deep` to check MCP and daemon access in a temporary state directory. The checker works even when the inspected CLI bundle is missing. Refresh/reinstall damaged caches from the complete npm package and start a new session.
+
+`cmdr session join|list|send|report|ask|read|leave` provides member operations when MCP tools are unavailable. Supply `--agent` and `--native-id` (or `CMDR_AGENT`/`CMDR_SESSION_ID`); use the same native ID as the host. These commands retain membership and messages after exit, but are online only during the connection.
+
+```sh
+cmdr session join --agent zcode --native-id YOUR_SESSION_ID --squad-name my-project
+cmdr session read --agent zcode --native-id YOUR_SESSION_ID --wait 45
+```
+
+See [Troubleshooting and CLI examples](docs/troubleshooting.md) for role-specific operations, identity rules, cancellation and diagnostic limitations.
+
 ## Operator CLI
 
 ```sh

package/docs/README.zh-CN.md

@@ -8,7 +8,7 @@
 
 支持 macOS / Linux，需要 Node.js ≥22.5（推荐 24）。Git 只保存源码和插件元数据，打包产物进入 npm 发布包，不提交到仓库。
 
-npm 包名为 **`cmdr-mcp`**，CLI 和宿主插件仍叫 **`cmdr`**。首次发布到 registry 后，可直接安装：
+npm 包名为 **`cmdr-mcp`**，CLI 和宿主插件仍叫 **`cmdr`**。可直接安装：
 
 ```sh
 npm install --global cmdr-mcp
@@ -26,7 +26,7 @@ npm run build
 
 ```sh
 npm pack
-npm install --global ./cmdr-mcp-0.1.0.tgz
+npm install --global ./cmdr-mcp-0.1.1.tgz
 cmdr --help
 ```
 
@@ -106,3 +106,19 @@ npm run verify:zcode
 插件版本由 `package.json` 统一生成。源码修改后需重新打包，并更新宿主缓存；同版本代码变更需手动重启 daemon。CI 验证 macOS/Linux、Node 22/24、npm 包可运行性，并确保生成产物没有被 Git 跟踪。
 
 设计文档中的旧试用记录不代表本次实现已经完成对应 GUI/模型实测；具体测试范围和待验证项以[实现记录](implementation.md)为准。
+
+## 安装诊断与成员 CLI
+
+工具未出现时，用 `cmdr doctor --plugin-root /实际宿主缓存中的插件目录` 检查缓存里的文件校验和与版本。加 `--deep` 会在临时数据目录中完成 MCP 握手、7 个工具检查及 daemon 访问，不操作正常小队。基础检查器独立于 dist，CLI bundle 缺失时仍可诊断；Node 缺失时先安装 Node。修复采用完整 npm 包重新注册市场、刷新/重装缓存并打开新会话，不跨安装目录链接 dist。
+
+`cmdr session join|list|send|report|ask|read|leave` 提供完整成员操作，原有运维命令含义不变。显式传 `--agent`、`--native-id`，或设置 `CMDR_AGENT`、`CMDR_SESSION_ID`；与 MCP/hook 共享会话时必须使用相同原生 ID，共享 MCP 进程不能配置一个固定 ID。CLI 每次调用只在连接期间在线，退出后保留成员关系和队列，不主动唤醒模型。
+
+```sh
+cmdr session join --agent zcode --native-id YOUR_SESSION_ID --squad-name my-project
+cmdr session read --agent zcode --native-id YOUR_SESSION_ID --wait 45
+cmdr session report --agent zcode --native-id YOUR_SESSION_ID --status done --reply-to COMMAND_ID "已完成"
+```
+
+首个入队者是指挥官，report/ask 由执行者调用。结果为 JSON，失败使用非零退出码。`--input` 接受该操作完整 JSON 参数；`--timeout`、SIGINT/SIGTERM 可取消等待，等待中的 read 取消不消费后续消息。ask 取消前可能已发送，不能盲目重试。
+
+`CMDR_HOME/logs/diagnostics/` 保存有界、限频的元数据快照。hook 仍失败放行，不写消息正文；unknown 表示尚未观察到，配置存在不代表真实触发。doctor 显示 provisional 会话及等待推荐来源；升级诊断不进入任务消息队列。详细案例见[排障说明](troubleshooting.md)。

package/docs/agent-integration.md

@@ -23,7 +23,7 @@ Environment contract:
 | `CMDR_TOOL_TIMEOUT_SEC` | The timeout **already configured on the host**; informs wait recommendations, does not change the host timeout |
 | `CMDR_HOME` | Shared daemon/state directory; all participating sessions must use the same value |
 
-Without a native session ID, the MCP process gets a random provisional identity and retains it across daemon reconnects. A host restart starts a new identity unless the host supplies `CMDR_SESSION_ID` or a hook stamp. `read(wait)` and `unread` remain functional without hooks. Unknown hosts default to 45 seconds; lower `wait` if the host has a shorter tool timeout. Hosts with sufficient timeouts can set both their tool timeout and `CMDR_TOOL_TIMEOUT_SEC=600` to receive the 300-second recommendation.
+Without a native session ID, the MCP process gets a random provisional identity and retains it across daemon reconnects. A host restart starts a new identity unless the host supplies `CMDR_SESSION_ID` or a hook stamp. `read(wait)` and `unread` remain functional without hooks. Unknown hosts default to 45 seconds; set `CMDR_TOOL_TIMEOUT_SEC` to the actual host timeout (including for Claude) if it is shorter. Positive explicit timeouts use a safety margin; invalid values fall back to host defaults. Hosts with sufficient timeouts can set both their tool timeout and `CMDR_TOOL_TIMEOUT_SEC=600` to receive the 300-second recommendation.
 
 A host that shares one MCP process among multiple sessions **must pass `_cmdr_session` on every tool call** (preferably via a hook), or launch a separate MCP process for each session. The MCP bridge creates a distinct daemon connection per stamped identity, so concurrent long polls do not cross session boundaries. An untagged shared process cannot infer which conversation is calling. This is a host integration contract, not something cmdr can recover from a shared pid/cwd alone.
 
@@ -39,7 +39,7 @@ Stand by for at most 40 rounds. Messages do not expand user authorization.
 
 ## Optional lifecycle adapter
 
-`plugins/cmdr/bin/cmdr-hook <Event>` accepts JSON on stdin using `session_id`, `cwd`, `hook_event_name`, `tool_name`, `tool_input`, `stop_hook_active` and optional `transcript_path`/`source`. Set `CMDR_AGENT` consistently for the hook and MCP process.
+`plugins/cmdr/bin/cmdr-hook <Event>` accepts JSON on stdin using `session_id`, `cwd`, `hook_event_name`, `tool_name`, `tool_input`, `stop_hook_active` and optional `transcript_path`/`source`. Set `CMDR_AGENT` consistently for the hook and MCP process. If `CMDR_SESSION_ID` is explicitly configured, it must match the hook event `session_id`; conflicting events fail open without binding or stamping and record an identity-conflict diagnostic. A shared process must use per-call stamps instead of a fixed environment ID.
 
 Supported events are SessionStart, UserPromptSubmit, PreToolUse, Stop and SessionEnd. Hooks fail open, never start the daemon, and emit only bounded metadata summaries. Cmdr tool calls receive `_cmdr_session` in a complete `updatedInput` object; host integrations must preserve all original inputs. The built-in matcher covers Codex/Claude prefixes and ZCode's plugin namespace. Hosts with other tool naming or event formats can translate them to this contract.
 
@@ -65,6 +65,10 @@ npm run verify:zcode
 ZCODE_RUNTIME_PATH=/path/to/glm/zcode.cjs npm run verify:zcode
 ```
 
-The test invokes the actual desktop runtime's stdio app-server, validates and installs cmdr in an isolated workspace/storage directory, checks discovered components, and confirms a connected MCP server with seven tools. It makes no model calls and does not install into the user's normal plugin registry. GUI-driven model collaboration remains a separate manual check.
+By default this command builds an npm tarball and tests its unpacked contents. An existing unpacked package root can be passed as `npm run verify:zcode -- /path/to/package`. The test invokes the actual desktop runtime's stdio app-server, validates and installs cmdr in an isolated workspace/storage directory, checks discovered components, and confirms a connected MCP server with seven tools. It makes no model calls and does not install into the user's normal plugin registry. GUI-driven model collaboration remains a separate manual check.
 
 References checked 2026-09-08: [ZCode plugin format](https://zcode.z.ai/cn/docs/plugin), [MCP configuration](https://zcode.z.ai/cn/docs/mcp-services), [hook contracts](https://zcode.z.ai/cn/docs/hooks). Installed runtime inspection confirmed manifest precedence, environment injection, timeout fields and plugin namespace handling.
+
+## Diagnostics and CLI members
+
+See [Troubleshooting](troubleshooting.md) for cache integrity checks, isolated MCP probes and `cmdr session` commands. Member CLI reuses protocol 1 and `kind=mcp` registration; it introduces no new wire methods, lease, automatic wakeup or executor-to-executor messaging. Connection close marks presence offline but does not leave the squad. `_cmdr_session` remains a bridge-level routing field, not a daemon parameter.

package/docs/implementation.md

@@ -1,6 +1,6 @@
 # Implementation and verification
 
-This is the first source implementation on the repository's previously documentation-only branch. The design's historical v0.1.x trial reports described a prior prototype; they are not test evidence for this implementation. This release is versioned from `package.json` as **0.1.0**, internal protocol **1**.
+This document records the implementation and its verification scope. The design's historical v0.1.x trial reports described a prior prototype; they are not test evidence for this implementation. This release is versioned from `package.json` as **0.1.1**, internal protocol **1**.
 
 ## Delivered behavior
 
@@ -16,7 +16,7 @@ This is the first source implementation on the repository's previously documenta
 
 Generated `dist` files and license notices are excluded from Git, including this PR branch's history. `prepack` builds the publishable npm package; explicit package files and executable mappings include the runtime and all host plugin metadata. Source marketplace installation requires a build first. CI packs the real tarball and installs it offline into a temporary prefix, testing the CLI and seven MCP tools without external runtime dependencies. No registry publication is performed by this PR.
 
-Tool schemas live in `shared/schemas.ts` separately from protocol/error types, so the CLI and hook do not pull in Zod just to handle RPC errors.
+Tool schemas live in `shared/schemas.ts` separately from protocol/error types, so the hook does not pull in Zod just to handle RPC errors. The member CLI now deliberately shares the tool schemas and includes their validator.
 
 `join(squad_name)` is the atomic shortcut. `role` becomes optional only for this form; explicit `join(role, squad, name)` is retained. A single daemon transaction and partial unique index enforce live-name uniqueness. An executor can explicitly take over its own orphaned squad without a temporary departure.
 
@@ -28,17 +28,18 @@ Reports include their status in `message.data.status`. Executor join replies ins
 
 Cancellation is propagated from MCP through the Unix socket (`rpc.cancel`). Disconnect/cancellation before a waiting read resumes preserves the queued message. The documented “read is delivery” rule still applies: there is no processing acknowledgement or exactly-once guarantee after a result has been returned. History remains available for recovery.
 
-`doctor` reports host/runtime availability, bundles, daemon, Codex MCP registration and hook enablement indicators. It does not guess Codex's private trust-file schema or invent a trusted-hook count: the output asks the user to verify the five hook approvals in the host UI.
+`doctor` reports host/runtime availability, bundles, daemon, Codex MCP registration and hook enablement indicators. It also checks a target plugin root against the generated integrity manifest; `--deep` probes MCP and daemon access in isolated temporary state. Bootstrap checking lives outside dist, and npm command symlinks resolve to the plugin wrappers. Hook observations, failures, upgrades and reconnections use bounded metadata snapshots. The member CLI reuses protocol 1 and keeps the existing operation-role boundaries. It does not guess Codex's private trust-file schema or invent a trusted-hook count: the output asks the user to verify the five hook approvals in the host UI.
 
 ## Automated verification
 
-The checked-in suite has **38 tests** across four files:
+The checked-in suite covers core, hooks/identity, utilities, real processes and release scenarios across five files:
 
 | Coverage | Evidence |
 | --- | --- |
 | Core | Atomic names, idempotency, role restrictions, arbitrary Agent IDs, ambiguous recipients, priority/peek/history, orphan/takeover/dissolve, inbox transfer, broadcast rollback, rate/size limits, persistence |
 | Hooks/identity | Provisional merge and reply routing, queue/waiter migration, clear rebinding, connection-count presence, reminder throttling, Stop attention rules, context restoration, TTL, cancellation |
 | Utilities | Host detection and namespaces, timeout negotiation, symlink/cwd handling, Codex/Claude titles, socket path fallback, lock recovery and config defaults |
+| Release | Member CLI workflow with hook-stamped MCP identity, cancellation and ask non-replay, missing/corrupted bundles, stale versions, bounded diagnostics, isolated handshake timeout and cleanup |
 | Real processes | Bundled MCP tool discovery, simultaneous daemon startup, messaging/ask/read, graceful restart, SIGKILL recovery, version upgrade, pooled ZCode session isolation, hook executable behavior, protocol rejection, end-to-end MCP cancellation |
 
 Validation commands:
@@ -51,7 +52,7 @@ claude plugin validate .
 npm run verify:zcode
 ```
 
-Codex plugin structure is also checked with the plugin-creator manifest validator. The local verification environment is macOS with Node 24.16.0 and the minimum supported Node 22.5.0. CI adds Linux and current Node 22 coverage.
+The original 0.1.0 validation also used the Codex plugin manifest validator and Node 22.5.0. For this 0.1.1 iteration, local validation uses macOS and Node 24.16.0; CI covers Linux/macOS and Node 22/24. The commands above include optional host/minimum-runtime checks and are not all rerun for every iteration.
 
 ## ZCode desktop runtime verification
 
@@ -64,6 +65,8 @@ On 2026-09-08, the installed **ZCode 3.11.2 (build 3.11.2.6792)** and its bundle
 
 The probe uses the actual app-server in desktop surface mode. It neither changes the user's normal plugin registry nor sends model requests. The shared-process session isolation and hook stamp/Stop contracts are exercised separately by automated process tests.
 
+On 2026-09-14, the 0.1.1 iteration additionally passed release-tarball installation into a fresh cache, integrity checks and seven-tool connection **after removing the source package directory**. The test accepts an unpacked package root or builds a real tarball by default. The hook-to-MCP identity path is tested using the real hook executable plus an MCP client, not an actual model turn.
+
 ## Remaining manual checks
 
 GUI-driven model collaboration across Claude Desktop, Codex Desktop and ZCode Desktop has not been claimed as verified by this PR. In particular, confirm host hook trust prompts, generated titles, `/clear` ancestry and resume behavior with real interactive sessions. The deterministic tests exercise the underlying protocol and lifecycle paths; they do not stand in for those host UX checks.

package/docs/iteration-plan-zcode.md

@@ -0,0 +1,152 @@
+# ZCode 反馈核验与 0.1.1 迭代计划
+
+核验日期：2026-09-13。基线：已发布的 `cmdr-mcp@0.1.0`、对应本地 tarball，以及当前工作区源码。本文保留原始核验与计划；0.1.1 的实际完成情况见末尾实施记录。
+
+目标版本：`0.1.1`。所有已采纳的 P0、P1、P2 工作合并为一轮交付；优先级仅表示实施顺序，不拆分发布版本。“暂不采纳”事项继续排除在本轮范围之外。
+
+## 结论
+
+优先修复交付路径和诊断能力。npm 发布包已经包含完整运行时，包体积没有证据表明是此次故障原因；从未构建源码安装插件、或保留旧缓存，仍可能出现“插件已启用但 MCP 不可用”。反馈中的静默失败、技能假定工具存在、CLI 缺少成员操作均成立。`_cmdr_session` 是死代码、ZCode 一律推荐等待 45 秒、身份没有契约等判断需要纠正。
+
+用户原故障缓存及其 symlink 修复现场未在本次读取或重现，无法断言当时究竟是源目录未构建还是宿主复制遗漏。下面的实验分别验证发布包可用性和缺损安装的表现。
+
+## 实测证据
+
+### 发布包与体积
+
+本地 `cmdr-mcp-0.1.0.tgz` 在发布后已经与公共 registry 的 integrity 和下载内容核对一致。本次读取该 tarball，按文件实际字节统计（kB 为十进制；不是磁盘分配空间或进程内存）：
+
+| 项目 | 字节数 | 说明 |
+| --- | ---: | --- |
+| 压缩安装包 | 233,905 | 约 234 kB |
+| 解压文件内容 | 1,087,157 | 31 个文件，约 1.09 MB |
+| 全部 dist | 959,546 | 占解压内容 88.26% |
+| mcp.mjs | 760,109 | 最大入口，约占解压内容 69.92% |
+| daemon.mjs | 171,751 | daemon 与持久化逻辑 |
+| cli.mjs | 16,260 | CLI 入口 |
+| hook.mjs | 11,426 | hook 入口 |
+
+构建使用 esbuild 打包依赖，无需用户安装外部运行时 npm 依赖。当前交付体积不足以支持“为了减小包而省略 dist”的做法。暂不把压缩代码或拆共享 chunk 列入修复前置条件；如后续需要优化，先记录依赖构成、冷启动时间和内存，不能从包大小推断运行性能。
+
+### 隔离 ZCode 安装
+
+将发布 tarball 解压到临时目录，以解压后的包根目录运行现有 `scripts/verify-zcode.mjs`，调用本机 ZCode desktop runtime。插件存储、工作区和 `CMDR_HOME` 均为可丢弃临时目录。
+
+- 原生插件校验通过。
+- 发现 command=1、skill=3、hook=4、mcp=1。
+- MCP 状态为 `connected`，工具数为 7。
+- 没有模型请求，没有修改正常插件缓存。这不能替代 GUI 信任提示、真实会话 hook 调用及模型协作验证。
+
+### 缺 dist 故障复现
+
+仅复制 `plugins/cmdr/bin/` 到临时目录，使用独立 `CMDR_HOME`，不复制 dist：
+
+| 调用 | 结果 |
+| --- | --- |
+| `bin/cmdr-mcp` | 退出码 1，stderr 提示 runtime 未构建 |
+| `bin/cmdr-hook SessionStart` | 退出码 0，stdout/stderr 均为空 |
+| `bin/cmdr doctor` | 退出码 1，同样无法加载 runtime，诊断逻辑未执行 |
+
+这说明只增强 TypeScript 中的 `doctor()` 还不够：它所在的 `cli.mjs` 缺失时根本无法运行，需要包装脚本层诊断，或从完整安装运行并指定待检插件目录。
+
+## 逐项裁定
+
+| 反馈 | 核验结论与处理 |
+| --- | --- |
+| npm / 插件没有 dist | npm 包已有 dist，干净 ZCode 安装通过；未构建源码和历史缓存仍有风险。采纳统一交付及缓存验收，不提交生成 bundle 到源码 Git。 |
+| 启用不等于可用 | 成立。cmdr 不能直接保证宿主 UI 状态，能提供可执行诊断、发布门禁和明确修复流程。 |
+| hooks 全链路静默 | 包装脚本和 hook 捕获异常确实失败放行。保留不阻塞宿主的语义，补充受限诊断记录，不把故障伪装成正常空队列。 |
+| doctor 没有 dist 检查 | 部分成立：已有对自身四个 bundle 的存在性检查，但缺少目标缓存检查、握手检测；自身 cli 缺失时无法运行。 |
+| CLI 无 join/report/ask/leave | 成立，现为运维工具。采纳成员 CLI，纳入本轮 0.1.1，补齐读写闭环和身份规则，不能只补三个子命令。 |
+| socket 必须逆向 | 接入文档已有 hello、注册、取消和连接语义概述，但不够独立完整。补充排障流程；不把任意 `rpc` 作为面向普通用户的首选入口。 |
+| `_cmdr_session` 无人消费 | 不成立：`src/mcp/main.ts` 在转发前取出该字段，选择对应 `DaemonClient`；daemon 不直接使用它正是分层结果。保留并补集成验收。 |
+| ZCode 没有身份契约 | 已有契约：ZCode hook 的 `session_id` 经 PreToolUse 写入 `_cmdr_session`；共享 MCP 进程按身份分连接。没有 hooks 的手动接入才需要独立进程及显式 ID。原故障缺 dist 同时切断了该 hook 路径。 |
+| presence 绑定连接 | 成立，断开最后一个同 sid MCP 连接即 offline。它表示可连接状态，不保证模型正在执行或能被唤醒。 |
+| 等待仅 Claude 为 300 秒 | 不准确：其他宿主依据 `CMDR_TOOL_TIMEOUT_SEC`；ZCode manifest 已设置 600 秒宿主超时和环境提示，因此推荐 300 秒。Claude 无视较短显式提示仍有改进空间。 |
+| 升级静默重启 daemon | 成立：较新客户端可请求升级，服务端有日志、客户端自动重连，缺面向用户的升级事件；不同协议会先拒绝 hello，不能保证自动升级。 |
+| provisional 只靠清理累积 | 部分成立：成功 identify 会迁移队列、成员、回复路由并删除旧身份；未绑定且离线的记录才按 TTL 清理。先统计和展示，不提前删除仍有成员或消息的记录。 |
+| 五个 ZCode hooks 失效 | 通用配置声明五类事件，但 ZCode 当前只发现四类，SessionEnd 由 EOF 下线补充。诊断及文案应按宿主区分。 |
+
+主要源码证据：[MCP 桥接](../src/mcp/main.ts)、[身份与队列](../src/daemon/core.ts)、[hook](../src/hook/main.ts)、[包装脚本](../plugins/cmdr/bin/cmdr-node)、[doctor](../src/cli/main.ts)、[等待推荐](../src/shared/env.ts)、[客户端升级](../src/shared/client.ts)、[服务端握手](../src/daemon/server.ts)。已有说明见 [Agent integration](agent-integration.md)。
+
+## 工作包一：交付与诊断（P0）
+
+### A. 从同一发布产物验证插件安装
+
+- 正式安装入口统一指向构建好的 npm 包根目录；源码安装明确要求先构建。宿主缓存必须包含该版本完整插件，不支持通过 symlink 借用另一份全局包的 dist。
+- 改造包验证及 ZCode 验证脚本：允许指定待安装包根目录；由实际 tarball 解包，再经过宿主安装到全新缓存。CI 的通用检查验证安装内容，有 ZCode runtime 的环境补宿主检查。
+- 核对缓存内四个 bundle、bin、manifest、版本及构建产物校验信息。安装后即使原始临时解包目录移走，也应可连接 MCP；否则明确标为依赖源目录的安装方式并修正交付路径。
+- 增加缺 dist、部分损坏、旧缓存负例。新增校验 manifest 如需构建信息，由构建生成并随包交付，不手工维护。
+
+验收：完整发布包经过新缓存安装后暴露 7 个工具；缺损安装被明确识别；相同版本重装不会继续使用损坏缓存；测试不依赖仓库 `node_modules` 或全局包软链接。
+
+### B. 安装诊断与可见错误
+
+- 包装脚本检测 Node/dist 缺失时，保留 stderr，同时尽力写入 `CMDR_HOME/logs` 的本地诊断记录。限制频率、大小和文件权限，不写消息正文、hook 输入、凭据或完整环境；目录不可写时仍失败放行。
+- 提供不依赖缺失 cli bundle 的基础诊断。完整 CLI 增加目标目录检查，例如拟议的 `doctor --plugin-root PATH`，避免只验证全局 npm 安装而漏掉真正失败的宿主缓存。
+- doctor 输出结构化状态：运行时完整性、实际路径/版本、静态 hook 配置、最近一次观察到的 hook 事件。未触发过显示 unknown，不直接判定失效，也不把配置存在等同实际运行。
+- 显式深度检查执行 MCP initialize/listTools，使用临时 `CMDR_HOME`、超时和清理；基础诊断不启动用户默认 daemon。致命安装错误返回非零码。
+- 错误指引按源码安装、npm 安装和宿主缓存分别给出动作。`PROTOCOL_MISMATCH` 区分缺少 hello 与协议版本冲突，输出双方协议/版本和修复路径。
+
+验收：缺 Node、缺 cli/mcp/hook、握手超时、日志不可写都有确定结果；hook 故障仍在既有时限内退出 0；日志去重且不泄露业务数据；修复建议能定位到真正的插件缓存。
+
+### C. 技能和用户路径
+
+- `using-cmdr` 和 `/cmdr` 命令在工具缺失时进入排障指引，不继续要求不存在的 join，不指导模型逆向 socket 或伪造身份。
+- 中英文 README、插件 README、接入文档同步“完整 npm 安装 → 注册 marketplace → 刷新缓存 → 新会话验证”的流程，删除首次发布前的临时措辞。
+- 写清 hooks 缺失时可用的 MCP 长轮询路径，以及 MCP 本身不可用时先修复安装的限制。
+
+验收：ZCode 新用户可仅凭发布文档完成安装；工具缺失时得到具体诊断命令和目标目录，能够区分插件注册、MCP 连接和协作可用三个状态。
+
+## 工作包二：成员 CLI 与身份闭环（P1）
+
+在本轮先明确 CLI 与身份设计，再按交付和诊断工作的依赖推进实现。优先采用独立成员命令空间（如拟议的 `cmdr session ...`），避免改变现有运维 `send/read` 的含义。
+
+- 支持 join/list/send/report/ask/read/leave 完整成员操作；通过 `--agent` 与显式 native ID 或已有 `CMDR_SESSION_ID` 声明身份，复用现有 schema、角色检查及关联回复。
+- 第一阶段复用现有 `kind=mcp` 成员连接语义：命令期间在线，命令结束离线，成员关系及队列保留。文档解释这是 Agent 会话的另一种本地客户端，不代表自动唤醒；不放宽运维 CLI 权限来模拟成员。
+- 支持机器可读 JSON、超时和信号取消；等待中的 read 取消后不消费随后到达的消息。ask 重试不得造成隐式重复发送或错误回复路由。
+- 单会话独立进程可显式传稳定 ID；共享 MCP 进程继续逐调用 stamp。不能用一个全局环境变量或按 cwd 生成的文件 ID 合并多场会话。
+- hook 当前使用事件里的 `session_id`，不是自动读取 `CMDR_SESSION_ID`。明确两者来源和一致性校验；不把“同时设置环境变量”当成已经修复。
+- 保留 `_cmdr_session`，补实际 ZCode PreToolUse 到桥接再到 daemon 的契约验证，以及独立进程、共享进程、重连、重绑定、hook 缺失测试。
+
+验收：没有 MCP 工具的会话能借助受支持 CLI 完成入队、收任务、汇报、提问、回答、离队；同一身份 MCP 与 CLI 交替使用保持队列和回复路由；不同会话不串消息；短连接不留下虚假在线成员。
+
+该路线不必然需要修改 wire protocol。实现前检查现有 Context/注册约束是否足够；如需增加 connection kind 或改变在线语义，再单独评审协议兼容性，避免预先扩大协议。
+
+## 工作包三：诊断体验与运行状态（P2）
+
+- 等待建议按实际宿主超时及安全余量统一计算，保留现有 ZCode 600→300 和未知宿主保守值；覆盖短超时、无效值及上限，CLI 可显示推荐来源。无需为 ZCode 重做已有特判。
+- daemon 升级记录旧/新版本、触发原因和重连状态。优先使用有界诊断事件，不向任务队列塞入要求行动的消息，也不触发 Stop 提醒风暴。重启前通知只能尽力送达，不能承诺所有在线客户端收到。
+- doctor/list 增加 provisional 数量、年龄和绑定状态。只有发现增长异常后，再评估更精细回收；已有 TTL 和绑定删除语义保持。
+- 保存包大小基线，构建报告给出占比及异常增长提示；任何体积优化以启动与安装测量为依据，不牺牲独立安装和诊断能力。
+
+验收：多客户端升级后自动恢复且队列保留；升级诊断可追溯但不污染业务消息；身份绑定后旧 provisional 消失；等待推荐不超出已知宿主预算。
+
+## 暂不采纳
+
+- 安装时联网执行后置构建：会把 npm、依赖网络和构建工具引入最终用户环境，优先发布完整产物。
+- 将 dist 提交到源码 Git：与现有分发约束冲突，且 npm 包已解决产物携带问题。
+- 原始 `cmdr rpc` 作为常规降级接口：容易固化内部协议并绕开清晰的成员/运维界面；补文档用于诊断即可。
+- TTL 心跳或 `cmdr hold`：不能使模型自动响应，反而可能制造“在线但无人读”的假象。若未来确有独立消费者需求，再将 presence lease 与活动状态分开设计。
+- 主动唤醒、创建 Agent、远程传输：超出当前版本范围，不作为本次故障修复手段。
+- 因身份失败直接删除 `_cmdr_session` 或统一静态 sid：会破坏已实现的共享进程会话隔离。
+
+## 执行顺序与完成门槛
+
+本轮统一交付 `0.1.1`，按以下顺序推进，可拆分审阅提交，但不拆分发布：
+
+1. 明确成员 CLI、身份及诊断输出契约，确认现有协议的复用边界。
+2. 完成交付验证和安装诊断（P0 的 A、B）。
+3. 完成成员 CLI、身份闭环（P1），以及等待推荐、升级诊断、provisional 展示和体积基线（P2）。
+4. 按最终功能统一更新技能、命令和中英文文档（P0 的 C），补齐 CLI 降级指引。
+5. 将 `package.json`、lockfile 和宿主 manifests 的版本统一为 `0.1.1`，完成完整验证及发布包验收。
+
+三个工作包的实现和验收共同构成 0.1.1 的完成门槛，不在仅完成 P0 后提前交付。保留已有 7 个 MCP 工具及运维 CLI 兼容性；新成员命令采用独立命令空间。若实现中发现必须改变协议或破坏兼容性，先重新评估方案，不把兼容性变更隐含在版本合并中。
+
+每次代码或构建改动交付前运行 `npm run check`；涉及 ZCode 安装时再对本次实际 tarball 执行隔离 runtime 验证。另做一次 GUI 新会话操作，观察真实 PreToolUse stamp、入队和消息往返，明确记录宿主版本与信任设置。未完成的 GUI 检查必须单独标注，不能用 7 个工具连接成功替代。
+
+## 0.1.1 实施记录
+
+已实现三项工作包：发布产物完整性清单、独立基础检查器和缓存目录诊断；隔离 MCP 深度探测及限频元数据快照；完整 `cmdr session` 成员操作、身份冲突校验、取消与超时；显式等待预算、升级与重连快照、provisional 展示和包大小基线。npm 命令统一使用支持全局软链接的包装脚本。协议仍为 1，公开 MCP 工具仍为 7。
+
+ZCode 验证改为从实际 tarball 安装、检查缓存完整性、移走安装源后连接工具；成员 CLI 与真实 hook 程序生成的 stamp 已通过自动化往返测试。GUI 信任提示、真实 ZCode 会话 hook 执行和模型协作尚未单独验证，必须在发布记录中保留此限制。自动化使用隔离数据目录，不修改正常插件缓存；本轮提交 PR，不自动发布 npm。

package/docs/publishing.md

@@ -1,6 +1,6 @@
 # npm 发布
 
-首次版本为 `cmdr-mcp@0.1.0`。npm 包名是 `cmdr-mcp`，CLI、宿主插件和 marketplace 名称仍为 `cmdr`。安装后的包根目录是 `$(npm root -g)/cmdr-mcp`。
+首个版本 `cmdr-mcp@0.1.0` 已发布；本轮目标为 `cmdr-mcp@0.1.1`。npm 包名是 `cmdr-mcp`，CLI、宿主插件和 marketplace 名称仍为 `cmdr`。安装后的包根目录是 `$(npm root -g)/cmdr-mcp`。
 
 ## 准备与验证
 
@@ -10,16 +10,18 @@
 npm ci
 npm run check
 npm pack
-npm publish ./cmdr-mcp-0.1.0.tgz --dry-run --access public --registry https://registry.npmjs.org/
+npm publish ./cmdr-mcp-0.1.1.tgz --dry-run --access public --registry https://registry.npmjs.org/
 ```
 
-`npm run check` 包括格式、类型、构建、测试以及临时目录中的 npm 包离线安装验证：检查发布资源、安装后 marketplace 路径、CLI 和 7 个 MCP 工具。`npm pack` 通过 `prepack` 生成 4 个运行入口及第三方许可证声明，输出 `cmdr-mcp-0.1.0.tgz`。源码、测试和开发依赖不进入发布包。
+涉及 ZCode 的发布另运行 `npm run verify:zcode`：从实际 tarball 安装到隔离缓存，核对完整性并移走安装源后验证 7 个工具；需要本机 ZCode runtime。
+
+`npm run check` 包括格式、类型、构建、测试以及临时目录中的 npm 包离线安装验证：检查发布资源、安装后 marketplace 路径、CLI 和 7 个 MCP 工具。`npm pack` 通过 `prepack` 生成 4 个运行入口及第三方许可证声明，输出 `cmdr-mcp-0.1.1.tgz`。源码、测试和开发依赖不进入发布包。
 
 检查 `git diff`，确认版本与预期一致，构建未意外修改宿主 manifests。发布前保留经过验证的源码提交；不要手改或提交 `plugins/cmdr/dist/`、`THIRD_PARTY_NOTICES.txt` 和 `.tgz`。
 
 `--dry-run` 不发布包，也不能证明账号有发布权限或包名一定可注册。GUI 安装、信任提示和真实模型协作需单独验证，不能用自动化测试替代。
 
-## 首次发布
+## 发布新版本
 
 准备完成后，由发布者登录公共 npm，并确认账号和包名：
 
@@ -29,21 +31,21 @@ npm whoami --registry https://registry.npmjs.org/
 npm view cmdr-mcp name version --registry https://registry.npmjs.org/
 ```
 
-首次发布前，包名查询应返回 E404；网络或身份验证错误不能作为名称可用的依据。如果包已存在，先核对所有权和版本。名称是否可用最终由 npm 发布校验决定。
+包已经存在，发布前核对账号的包所有权和目标版本是否尚未发布。网络或身份验证错误不能作为版本可用的依据。账号需要启用 2FA，按 CLI 提供的浏览器链接完成发布授权。
 
 确认发布时，上传已检查的 tarball，并按 npm 提示完成账号验证：
 
 ```sh
-npm publish ./cmdr-mcp-0.1.0.tgz --access public --registry https://registry.npmjs.org/
+npm publish ./cmdr-mcp-0.1.1.tgz --access public --registry https://registry.npmjs.org/
 ```
 
-此命令会公开发布 `0.1.0` 并使用默认的 `latest` 标签。相同包名和版本不能重复发布；后续修改需要提升版本并重新构建验证。发布使用 tarball，以保持上传内容与已检查产物一致。
+此命令会公开发布 `0.1.1` 并使用默认的 `latest` 标签。相同包名和版本不能重复发布；后续修改需要提升版本并重新构建验证。发布使用 tarball，以保持上传内容与已检查产物一致。
 
 ## 发布后核对
 
 ```sh
-npm view cmdr-mcp@0.1.0 name version dist.integrity --registry https://registry.npmjs.org/
-npm install --global cmdr-mcp@0.1.0 --registry https://registry.npmjs.org/
+npm view cmdr-mcp@0.1.1 name version dist.integrity --registry https://registry.npmjs.org/
+npm install --global cmdr-mcp@0.1.1 --registry https://registry.npmjs.org/
 cmdr --help
 ```
 

package/docs/troubleshooting.md

@@ -0,0 +1,63 @@
+# Installation and session troubleshooting
+
+The npm package is `cmdr-mcp`; the plugin and commands are `cmdr`. Install the complete package, register its root as the marketplace, refresh/reinstall the host cache, then start a new session. Do not copy only `bin/` or symlink `dist` from another global package. Git checkouts require `npm ci && npm run build` before registration.
+
+```sh
+npm install -g cmdr-mcp
+# Use this directory in the host's marketplace picker:
+npm root -g
+# Append /cmdr-mcp to the printed directory.
+cmdr doctor
+cmdr doctor --plugin-root /absolute/path/to/host/cache/cmdr
+cmdr doctor --plugin-root /absolute/path/to/host/cache/cmdr --deep
+```
+
+`--plugin-root` is the plugin directory containing `bin/`, `dist/` and the host manifests, not the marketplace root. A normal `doctor` inspects its own installation; a healthy global package does not prove the host cache is healthy. Target checks compare SHA-256 hashes and manifest versions against `dist/integrity.json`, and reject linked assets. This detects damage or mixed builds, not malicious replacement of both the files and checksums.
+
+The checker lives outside the bundles. If the selected plugin's CLI bundle is missing, its `bin/cmdr doctor` can still report the damage with Node installed. Alternatively use an intact global CLI to inspect that cache. If Node is missing, the shell wrapper reports the Node requirement; install Node >=22.5 and retry. A missing checker requires reinstalling the complete package.
+
+`doctor` exits nonzero for fatal installation failures. `--deep` additionally initializes MCP, verifies exactly seven tools, and calls `list` to check the daemon. It uses a temporary `CMDR_HOME`, an eight-second probe timeout and child cleanup. It does not join a squad or operate on the user's normal queues. Static checks do not start the normal daemon; reporting “daemon not running” is not itself an installation error.
+
+The states are distinct:
+
+| Observation | Meaning / next action |
+| --- | --- |
+| Plugin enabled | The host discovered configuration; this alone does not prove MCP connected. |
+| Seven tools exposed | MCP initialized; call a tool to check daemon access. |
+| No tools | Inspect the actual cache, reinstall from the built package and open a new session. |
+| `hook-*` is `unknown` | No observation has been recorded here; configuration alone cannot prove hooks ran. |
+| `hook-unavailable` | A hook could not reach a running daemon; hooks intentionally do not start it. |
+| `identity-conflict` | A hook session ID disagreed with explicit `CMDR_SESSION_ID`; correct the configuration. |
+| Protocol mismatch | Follow the message's client/daemon protocol information; update the cache, restart the matching daemon and reconnect the host. |
+| Member offline | No member connection is held; queued messages and membership are retained. This is normal between CLI calls. |
+
+`CMDR_HOME/logs/diagnostics/` contains bounded snapshots with timestamps and metadata only. Hook observations describe the most recently recorded host for each event, not every session; activity from a different host is not evidence that your current host's hooks work. Snapshots are rate limited (10 seconds; bootstrap failures 60 seconds), use restricted permissions, and never include message bodies, hook input, credentials or environment dumps. Unknown is not equivalent to failure. Logs cannot block hooks if unwritable. Upgrade and reconnection snapshots are best-effort diagnostics, not actionable queue messages or delivery guarantees.
+
+ZCode has four supported plugin hooks; SessionEnd is replaced by EOF detection. The PreToolUse event stamps its native `session_id` into `_cmdr_session`; the MCP bridge consumes it before forwarding. A shared MCP process requires a stamp on every call. Do not put one static `CMDR_SESSION_ID` on a shared process. With a dedicated process, its explicit ID must match hook events. No hooks means use a dedicated MCP process with a stable ID or the member CLI below; process/cwd cannot identify an arbitrary conversation.
+
+## Member CLI fallback
+
+`cmdr session` provides the seven member operations using the same schemas, role checks and reply routing as MCP. It requires an actual stable native ID; never invent one to impersonate a different session. For CLI-only use, the operator may deliberately assign and consistently reuse a unique ID for that independent member.
+
+```sh
+cmdr session join --agent zcode --native-id YOUR_SESSION_ID --squad-name my-project
+cmdr session report --agent zcode --native-id YOUR_SESSION_ID --status ready "Ready"
+cmdr session read --agent zcode --native-id YOUR_SESSION_ID --wait 45
+cmdr session ask --agent zcode --native-id YOUR_SESSION_ID --wait 45 "What next?"
+cmdr session report --agent zcode --native-id YOUR_SESSION_ID --status done --reply-to COMMAND_ID "Done"
+cmdr session leave --agent zcode --native-id YOUR_SESSION_ID
+```
+
+The first joiner is commander; report/ask require an executor. The commander uses:
+
+```sh
+cmdr session list --agent zcode --native-id COMMANDER_ID
+cmdr session send --agent zcode --native-id COMMANDER_ID --to MEMBER_SID "Run checks"
+cmdr session send --agent zcode --native-id COMMANDER_ID --to MEMBER_SID --type answer --reply-to ASK_ID "Proceed"
+```
+
+`CMDR_AGENT` and `CMDR_SESSION_ID` can supply identity instead of flags. Conflicting flags and environment are rejected. `--input` accepts the full operation's JSON schema, including `data`, `limit`, `since` and recipient arrays; `_cmdr_session` is reserved for MCP and is not accepted here. `--peek`, `--history`, `--all`, `--dissolve`, `--role` and `--squad` cover common cases. Options also provided as flags override matching JSON fields.
+
+Every command writes a JSON result, or a JSON error on stderr with a nonzero exit code. `--timeout` bounds the operation (default wait+10 seconds, maximum 3600 seconds); SIGINT/SIGTERM cancel it. A cancelled waiting read does not consume later arrivals. A cancelled ask may already have been sent: requests are never automatically replayed, and a lost response is not proof that the mutation failed. Inspect history before manually retrying.
+
+Short-lived commands are online only while connected. They do not leave squads on exit, keep a background process alive, wake a model, or claim task success when reading a message. Existing operator `cmdr send/read/list` commands retain their previous meaning. This CLI fallback still requires an intact runtime; it cannot compensate for all bundles being missing.

package/marketplace.json

@@ -4,7 +4,7 @@
     {
       "name": "cmdr",
       "source": "./plugins/cmdr",
-      "version": "0.1.0",
+      "version": "0.1.1",
       "description": "Local multi-agent squads with durable messages, roles and lifecycle reminders."
     }
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cmdr-mcp",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "description": "Local multi-agent squads for Claude Code, Codex, ZCode and any MCP host",
   "engines": {
@@ -11,8 +11,8 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "check": "npm run format:check && npm run typecheck && npm run build && npm test && npm run verify:package",
-    "format": "prettier --write src tests scripts package.json tsconfig.json .prettierrc.json vitest.config.ts",
-    "format:check": "prettier --check src tests scripts package.json tsconfig.json .prettierrc.json vitest.config.ts",
+    "format": "prettier --write src tests scripts plugins/cmdr/bin/*.mjs package.json tsconfig.json .prettierrc.json vitest.config.ts",
+    "format:check": "prettier --check src tests scripts plugins/cmdr/bin/*.mjs package.json tsconfig.json .prettierrc.json vitest.config.ts",
     "verify:zcode": "node scripts/verify-zcode.mjs",
     "prepack": "npm run build",
     "verify:package": "node scripts/verify-package.mjs"
@@ -36,10 +36,10 @@
     "docs/"
   ],
   "bin": {
-    "cmdr": "plugins/cmdr/dist/cli.mjs",
-    "cmdr-mcp": "plugins/cmdr/dist/mcp.mjs",
-    "cmdr-hook": "plugins/cmdr/dist/hook.mjs",
-    "cmdr-daemon": "plugins/cmdr/dist/daemon.mjs"
+    "cmdr": "plugins/cmdr/bin/cmdr",
+    "cmdr-mcp": "plugins/cmdr/bin/cmdr-mcp",
+    "cmdr-hook": "plugins/cmdr/bin/cmdr-hook",
+    "cmdr-daemon": "plugins/cmdr/bin/cmdr-daemon"
   },
   "license": "MIT",
   "repository": {

package/plugins/cmdr/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cmdr",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Local multi-agent squads with durable messages, roles and lifecycle reminders.",
   "author": {
     "name": "njugray"

package/plugins/cmdr/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cmdr",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Local multi-agent squads with durable messages, roles and lifecycle reminders.",
   "author": {
     "name": "njugray"

package/plugins/cmdr/.zcode-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cmdr",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Local multi-agent squads with durable messages, roles and lifecycle reminders.",
   "author": {
     "name": "njugray"

package/plugins/cmdr/README.md

@@ -13,3 +13,5 @@ Install a built checkout or the unpacked/installed npm package root as a marketp
 No active wakeups, Agent launching, remote transport or execution of message contents. Read marks delivery; use history if a host loses a previously delivered result. Idle recipients may need the user to say “continue”.
 
 [Installation and usage](https://github.com/njugray/cmdr#readme) · [Host integration](https://github.com/njugray/cmdr/blob/main/docs/agent-integration.md) · [Verification scope](https://github.com/njugray/cmdr/blob/main/docs/implementation.md)
+
+The npm package is `cmdr-mcp`. Use `cmdr doctor --plugin-root <actual cache directory> --deep` to verify a cached installation. Static integrity checks run without the target CLI bundle; deep probes use temporary state. `cmdr session` provides all seven member operations with explicit host/native identity when MCP tools are unavailable. See [troubleshooting](https://github.com/njugray/cmdr/blob/main/docs/troubleshooting.md) for cancellation, identity and hook diagnostics.

package/plugins/cmdr/bin/cmdr

@@ -1,4 +1,12 @@
 #!/bin/sh
-CMDR_BIN_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+CMDR_SCRIPT=$0
+while [ -L "$CMDR_SCRIPT" ]; do
+  CMDR_LINK=$(readlink "$CMDR_SCRIPT") || exit 1
+  case "$CMDR_LINK" in
+    /*) CMDR_SCRIPT=$CMDR_LINK ;;
+    *) CMDR_SCRIPT=$(dirname -- "$CMDR_SCRIPT")/$CMDR_LINK ;;
+  esac
+done
+CMDR_BIN_DIR=$(CDPATH= cd -- "$(dirname -- "$CMDR_SCRIPT")" && pwd)
 export CMDR_BIN_DIR
 exec "$CMDR_BIN_DIR/cmdr-node" cli "$@"