cmdr-mcp 0.2.0 → 0.4.0

package/.claude-plugin/marketplace.json

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

package/README.md

@@ -8,7 +8,23 @@
 
 Requires macOS or Linux and **Node.js ≥22.5** (24 recommended). The development branch contains source and plugin metadata. npm packages and the generated `marketplace` branch include the runtime bundles.
 
-The npm package is **`cmdr-mcp`**; the CLI and host plugin remain **`cmdr`**. Install with:
+**One-command setup (0.4.0):** replace `claude-code` with `codex` or `zcode` for your host.
+
+```sh
+npx -y --package=cmdr-mcp@latest cmdr setup --agent claude-code
+```
+
+Setup installs the runtime, skill, MCP and hooks while preserving existing settings. Repeat to upgrade; add `--dry-run` to preview. Open a new session and complete any host trust prompts. For a built checkout, use `plugins/cmdr/bin/cmdr setup --agent …`.
+
+For skill files only:
+
+```sh
+npx skills add njugray/cmdr --skill cmdr
+```
+
+The skill requires a working cmdr runtime and MCP connection. Use setup or the native plugin below for those components. See [installation details](docs/setup.md).
+
+The npm package is **`cmdr-mcp`**; the CLI and host plugin remain **`cmdr`**. For a global CLI and native plugin installation:
 
 ```sh
 npm install --global cmdr-mcp
@@ -26,7 +42,7 @@ For distribution, `npm pack` (or `npm publish`) runs `prepack` to build the four
 
 ```sh
 npm pack
-npm install --global ./cmdr-mcp-0.2.0.tgz
+npm install --global ./cmdr-mcp-0.4.0.tgz
 cmdr --help
 ```
 
@@ -78,10 +94,10 @@ Joining by name atomically creates or finds a persistent channel and defaults to
 2. The commander inspects `list`, then `send`s clear tasks with acceptance criteria.
 3. Executors `read`, immediately acknowledge with `report(status="working", reply_to=<command id>)`, do the work, then report done/failed/cancelled with the same `reply_to`.
 4. Executors use `ask` when blocked; the commander responds with `send(type="answer", reply_to=<ask id>)`.
-5. Use `join(..., standby="auto")`, then inspect `list` for listener health. With `can_auto_respond=true`, end the idle turn. Unsupported hosts remain manual; the skills bound fallback polling to two waits and explain manual continuation.
+5. Use `join(..., standby="auto")`. Claude/ZCode then arm `listener.arm.command` with its indicated native tool. Inspect `list` for listener health. With `can_auto_respond=true`, end the idle turn. Unsupported hosts remain manual; the skills bound fallback polling to two waits and explain manual continuation.
 6. `leave` preserves queued messages. Commander departure orphans the squad; `leave(dissolve=true)` disbands it.
 
-cmdr connects existing sessions and never creates agents. The opt-in Codex adapter uses the shared app-server public transport for managed wakeup. Claude, ZCode and other hosts currently report `wake_mode=manual`. See [Long-running collaboration](docs/long-running-collaboration.md) for capabilities, recovery, handover and compatibility requirements.
+Codex wakes through app-server proxy or the `codex queue` fallback. Claude uses Monitor and ZCode uses background Bash completion through the built-in `cmdr standby watch`; re-arm after task termination. See [Long-running collaboration](docs/long-running-collaboration.md) for capabilities, recovery, handover and compatibility requirements.
 
 ## Tools
 
@@ -160,6 +176,6 @@ npm run verify:zcode   # optional: requires the locally installed ZCode desktop
 
 For development, `claude --plugin-dir ./plugins/cmdr` loads the plugin directly. Installed hosts use cached copies: reinstall/refresh after changing a plugin. Version numbers come from `package.json`; after same-version changes, restart the daemon explicitly. Generated bundles and third-party license notices are ignored by Git and included in the npm package.
 
-v1 is single-machine, single-user, Unix-socket-only. There is no network listener, remote transport, automatic Agent launching or executor-to-executor messaging. Host GUI interaction and live model behavior are distinct from the automated runtime checks; see the [verification record](docs/implementation.md).
+v1 is single-machine, single-user, Unix-socket-only. There is no network listener, remote transport or executor-to-executor messaging. Agent session creation is outside the current scope. Host GUI interaction and live model behavior are distinct from the automated runtime checks; see the [verification record](docs/implementation.md).
 
 [MIT](LICENSE)

package/docs/README.zh-CN.md

@@ -8,7 +8,23 @@
 
 支持 macOS / Linux，需要 Node.js ≥22.5（推荐 24）。开发分支保存源码和插件元数据；npm 发布包及自动生成的 `marketplace` 分支包含完整运行时。
 
-npm 包名为 **`cmdr-mcp`**，CLI 和宿主插件仍叫 **`cmdr`**。可直接安装：
+**一条命令完整安装（0.4.0）**，将 `claude-code` 换成实际使用的 `codex` 或 `zcode`：
+
+```sh
+npx -y --package=cmdr-mcp@latest cmdr setup --agent claude-code
+```
+
+安装器会安装运行时、技能、MCP 和 hooks，并保留已有配置。重复执行可升级，增加 `--dry-run` 可预览。完成后新开会话并处理宿主信任提示。构建后的源码可直接运行 `plugins/cmdr/bin/cmdr setup --agent …`。
+
+只安装技能文件时使用：
+
+```sh
+npx skills add njugray/cmdr --skill cmdr
+```
+
+技能需要可用的 cmdr 运行时和 MCP 连接，可通过 setup 或下面的原生插件方式安装。配置位置、升级和恢复见[安装说明](setup.md)。
+
+npm 包名为 **`cmdr-mcp`**，CLI 和宿主插件仍叫 **`cmdr`**。需要全局 CLI 或原生插件时也可安装：
 
 ```sh
 npm install --global cmdr-mcp
@@ -26,7 +42,7 @@ npm run build
 
 ```sh
 npm pack
-npm install --global ./cmdr-mcp-0.2.0.tgz
+npm install --global ./cmdr-mcp-0.4.0.tgz
 cmdr --help
 ```
 
@@ -72,7 +88,7 @@ ZCode 桌面端：打开工作区，在 **设置 → 插件 → 创建 → 添
 
 执行方加入后 `report(ready)` 报到，说明目录、能力和当前上下文。指挥官通过 `list` 看成员，用 `send` 下发可验证任务。执行方 `read` 读取任务后立即用 `report(working, reply_to=<command id>)` 接单，再带相同 `reply_to` 汇报 done/failed/cancelled，遇到阻塞用 `ask` 提问；指挥官通过 `send(type="answer", reply_to=<ask id>)` 回答。
 
-加入时设置 `standby="auto"`，然后用 `list` 检查监听健康状态。`can_auto_respond=true` 时可结束空闲回合，由 daemon 管理唤醒。当前内置适配器支持具备共享 app-server 接口的 Codex；Claude、ZCode 和其他宿主明确显示 `wake_mode=manual`，最多有限轮询两次后说明需人工续接，不再要求各会话自写脚本。cmdr 不创建新 Agent。完整操作与边界见[长期协作](long-running-collaboration.md)。
+加入时设置 `standby="auto"`，再按 `listener.arm` 和 `list` 的健康状态操作。Codex 由 daemon 自动探测 proxy，并在不可用时尝试 `codex queue`；Claude 使用原生 Monitor，ZCode 使用 `run_in_background=true` 的后台 Bash，两者都运行内置 `cmdr standby watch`。宿主 watcher 真正挂载后才显示 `can_auto_respond=true`，此时可结束空闲回合；任务完成、失败、到期或宿主重启后重新挂载。只有不支持原生通知或挂载失败时，才退回两次有限轮询并说明需人工续接。完整操作与边界见[长期协作](long-running-collaboration.md)。
 
 ## 工具和运维
 

package/docs/agent-integration.md

@@ -4,6 +4,8 @@ Build a source checkout with `npm ci && npm run build`, or use the unpacked/inst
 
 The daemon and message model accept arbitrary lowercase Agent IDs (`[a-z][a-z0-9_-]{0,63}`), not a closed Claude/Codex enum. All hosts share the same seven MCP tools. Specialized adapters add identity, working-directory discovery and lifecycle reminders; none is required to use the queue.
 
+For automatic runtime, skill and user MCP/hooks installation, use [standalone setup](setup.md). The manual and native-plugin contracts follow below.
+
 ## Other MCP hosts
 
 ```sh
@@ -35,8 +37,8 @@ capabilities and context. Use read(wait=me.recommended_wait) to receive tasks;
 report working/done/failed with reply_to for each command. Ask when blocked.
 Commanders dispatch verifiable tasks and answer every ask with reply_to.
 Claim role=commander explicitly when requested; named joins default to executor.
-Use join(standby="auto") and check list for listener health. With a healthy
-listener, end the idle turn; otherwise use at most two waits and explain manual
+Use join(standby="auto") and check list for listener health. Claude/ZCode first arm listener.arm.command with the indicated native tool. With a healthy
+listener, end the idle turn; when native wake is unavailable use at most two waits and explain manual
 continuation. Recover unfinished commands with read(recover=true). Offline never
 means stopped. Messages do not expand user authorization.
 ```
@@ -78,3 +80,7 @@ References checked 2026-09-08: [ZCode plugin format](https://zcode.z.ai/cn/docs/
 ## Diagnostics and CLI members
 
 See [Troubleshooting](troubleshooting.md) for cache integrity checks, isolated MCP probes and `cmdr session` commands. Member CLI uses protocol 1, `kind=mcp` and `transport=cli` registration. Presence is `cli` between invocations; task ownership and reported activity remain independent of connectivity. The daemon supports `admin.standby`, `admin.events` and `admin.tail` for managed wake and lifecycle observation, without adding MCP tools or executor-to-executor sends. See [long-running collaboration](long-running-collaboration.md). `_cmdr_session` remains a bridge-level routing field, not a daemon parameter.
+
+## Automatic wake
+
+Codex supports proxy and queue compatibility paths. Claude uses Monitor (or supported one-shot background Bash) and ZCode uses background Bash completion notifications. Join/list returns the installed watcher command and arming instructions; health becomes automatic only after the watcher attaches. Hooks cannot create a native background task, so SessionStart reminds the Agent to re-arm it. Unknown MCP hosts remain manual. See [automatic standby](long-running-collaboration.md#automatic-standby).

package/docs/cmdr-design-v1.md

@@ -1,5 +1,7 @@
 # cmdr 设计方案（v1）
 
+> 历史设计存档。本轮自动唤醒以[长期协作](long-running-collaboration.md#automatic-standby)和[实现记录](implementation.md)为准：已移除禁止主动唤醒、所有非 Codex 宿主一律 manual、要求模型循环待命 40 轮等旧限制；新建 Agent 会话不在本轮范围内。下文的原型记录不代表当前实现。
+
 > **cmdr**（Commander）：让同一台机器上的多个 Claude Code / Codex 会话组成"小队"，通过 MCP 工具互相通信。指挥官下发命令、回答询问，执行方报到、汇报、询问；服务端为每个会话维护一个带优先级的消息队列，并通过 hooks 在合适的时机提醒 Agent 读取。
 >
 > **当前实现状态（2026-09-08）**：本仓库已从仅含文档的分支实现 v1 源码、插件与测试，并按新增需求支持 ZCode 桌面端和任意 MCP Agent 接入。本文保留既有设计及原型试用记录；其中历史 v0.1.x 的完成日期、版本号与实测结论不是本次代码的验证凭据。本次具体交付、差异、38 个自动化用例和 ZCode 本机运行时验证见 [实现与验证记录](implementation.md)，新增宿主契约见 [Agent 接入指南](agent-integration.md)。

package/docs/implementation.md

@@ -1,6 +1,6 @@
 # Implementation and verification
 
-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.2.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.4.0**, internal protocol **1**.
 
 ## Delivered behavior
 
@@ -71,19 +71,55 @@ On 2026-09-14, the 0.1.1 iteration additionally passed release-tarball installat
 
 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.
 
-Windows, remote machines and creation of new Agent sessions are outside this Unix-socket scope. Opt-in Codex wakeup uses the existing shared app-server public proxy; unsupported hosts remain manual. Generic compatibility means an open MCP adapter contract, not a claim that every proprietary Agent host has been individually tested.
+Windows, remote machines and creation of new Agent sessions are outside this Unix-socket scope. Codex uses proxy/queue and Claude/ZCode use native notification watchers. Unsupported hosts remain manual. Generic compatibility means an open MCP adapter contract, not a claim that every proprietary Agent host has been individually tested.
 
 
 ## 0.2.0 issue #5 coverage
 
 The regression suites add persisted command ownership and recovery, gated cancellation/reassignment, compact reads, event replay/filtering/retention gaps, commander-free channels, stable role inboxes and revoked old endpoints. Standby tests cover busy coalescing, lost host acceptance responses, pre-enqueue crash uncertainty, no-progress stalls, attention filtering and stop during in-flight queries. Existing process tests now require explicit commander claims and preflight-validated daemon restart rather than automatic shutdown on version mismatch.
 
-The Codex adapter uses the installed CLI's generated public request/response types for the experimental queue contract. No private host SQLite/rollout parsing is used. Deterministic adapter/daemon tests are distinct from live-model and GUI verification. CLI presence is `cli`; task status does not follow socket lifetime. All tests use temporary state, not normal ~/.cmdr data.
+The Codex adapter uses the installed CLI's generated public request/response types for the experimental queue contract. That 0.2.0 proxy-only implementation did not parse private host state; the queue compatibility path below intentionally replaces that restriction. Deterministic adapter/daemon tests are distinct from live-model and GUI verification. CLI presence is `cli`; task status does not follow socket lifetime. All tests use temporary state, not normal ~/.cmdr data.
 
 
 Local verification for 0.2.0 (2026-09-16): `npm run check` passed 79 tests plus offline npm installation and seven-tool discovery; the targeted Node 22.5.0 suite passed 44 tests, including preflight and managed daemon processes. `npm run verify:zcode` validated the native plugin, discovered 1 command / 3 skills / 4 hooks / 1 MCP server, and connected seven tools from a fresh cache after removing the source directory. No model request was made.
 
+## Standalone setup
+
+`cmdr setup` copies a verified runtime to a persistent build directory and installs profile-specific launchers, the `cmdr` skill and user MCP/hooks. Configuration edits preserve unrelated values and support backup/rollback. See [setup](setup.md) for usage and recovery.
+
+The standalone skill owns the role references; the build synchronizes the existing role skill entries from them. Setup tests cover all three hosts, upgrades, configuration preservation, failure recovery and profile isolation. Package verification runs the real npx entry point offline and checks it after removing the npx cache. Host GUI trust and live-model collaboration require separate verification.
+
 A read-only probe of the installed Codex CLI 0.153.4 confirmed that this desktop environment does not expose the CLI's default shared control socket. Live-model wake execution therefore remains unverified here; tests use a deterministic public-protocol host fixture. The adapter reports this transport failure and supports an explicit host-provided socket rather than spawning a competing app-server.
 
 
 Review regression verification for 0.2.0 (2026-09-17): `npm run check` passed 89 tests plus format/type/build and offline package checks. Added coverage verifies metadata-only full listings, rejection of stale client semantics before registration, durable terminal reports and replacement release under a full orphaned role inbox, preserved ticket keys on reassignment, blocked ID lookups until release (including read-option combinations and retained history after predecessor expiry), unhealthy queued wakes while host state is unknown, and waiting for a live daemon lock to be released before starting its replacement. Daemon shutdown closes its server before returning lock ownership. `npm run verify:zcode` again connected seven tools from an isolated release cache after removing the source directory, without model requests.
+
+## 0.3.0 automatic wake iteration — issues #7, #8 and #9
+
+This iteration is isolated on `feat/host-auto-wake`, based directly on `main` (`5368e52`). Standalone setup/skills installation remains on its separate branch. The reported host mechanisms are implemented as follows:
+
+- [#7 Codex queue feedback](https://github.com/njugray/cmdr/issues/7): the previous proxy-only assumption is removed. Auto mode checks the existing proxy, then queue capability. Its read-only state_5/rollout compatibility reader is explicitly version-coupled, scans complete records incrementally and prevents idle inference from partial writes. Delivery stays with the installed queue CLI. Pending requests pin their transport; actual user-message markers reconcile lost responses after restart. Node >=22.12 is required for the fallback's read-only SQLite option; earlier supported Node versions can still use proxy.
+- [#8 Claude Monitor feedback](https://github.com/njugray/cmdr/issues/8): native Monitor runs the built-in watcher. Actionable filtering is shared with adapters and tail. Follow defaults to now; explicit replay cursors remain available. Role-inbox events, direct info and current unfinished work are included; ready/working reports and quiet broadcast info are excluded.
+- [#9 ZCode background completion feedback](https://github.com/njugray/cmdr/issues/9): native background Bash runs the same watcher in one-shot mode. It remains silent until actionable work, then exits and relies on the host's completion notification. Unlike the supplied consuming-read PoC, the shipped watcher observes metadata; the awakened Agent performs read/acceptance. It has a daemon lease, duplicate protection, startup snapshot, expiry and disconnect handling. Join/list/skills and SessionStart now tell the model to arm/re-arm; the previous blanket manual classification and ban on host-side listening are removed.
+
+The [follow-up correction to #8](https://github.com/njugray/cmdr/issues/8#issuecomment-5712342765) identifies report filtering on omitted `data.status` as the cause of missed notifications in the original recipe, rather than a stalled subscription. The shared wake policy now uses the daemon-computed `attn` flag for reports. Default live events and replay both carry `data=null`; `--full` retains the original data. Regression coverage checks all six report statuses with and without data, matching live/replay output, and consecutive actionable reports on the same subscription. No periodic reconnect workaround is added.
+
+The [PR #10 review](https://github.com/njugray/cmdr/pull/10#discussion_r4035173370) also identified repeated one-shot wakes when a blocked executor re-arms with an already accepted command. Attach now records accepted commands without pending cancellation as already seen. They remain owned and recoverable; unread messages, unaccepted work and pending cancellation still notify. Process regressions cover ZCode and Claude's one-shot fallback through blocked → re-arm → daemon restart → answer → cancellation, including unread answers at attach and cancellation whose message has already been read.
+
+New ZCode session creation is deferred by user decision. The app-server prototype, `cmdr zcode create` / `admin.zcode.create` entry points, owned runtime state and dedicated tests have been removed. No CDP desktop adapter is included. Automatic wake for existing Codex, Claude and ZCode sessions remains. Seven public MCP tools, ownership/report semantics, cancellation and generic host IDs remain intact.
+
+**Source-research correction (2026-09-17):** `ZCODE_STORAGE_DIR` does not isolate the session database; the removed prototype and the earlier verification script did not explicitly set `ZCODE_SESSION_DB_PATH`. Earlier descriptions of fully isolated owned storage were too broad. The retained plugin/MCP verification script now explicitly sets a temporary session database and checks that the runtime opened it. A persisted session can be discovered through shared storage when a fresh desktop workspace runtime seeds the task index, but visibility is not ownership transfer. Empty create/read/close does not prove persistence or cross-process recovery. See [ZCode desktop session visibility research](zcode-desktop-session-visibility.md) for source evidence, no-model experiments and the decision to defer creation.
+
+**Desktop entry probe (2026-09-17):** an unmodified ZCode 3.11.2 release launched with an explicit loopback CDP endpoint and disposable desktop/runtime databases accepted external Node calls through its Renderer service proxy to the desktop Host's `createTask`. Two real IDs were returned; `listTasks` and `task_created` events reflected the creations, and the visible sidebar grew from one entry to two without a reload. Workspace runtime PID/generation remained unchanged. This is a verified, opt-in, version-coupled route, not a default public task API or an implemented cmdr desktop adapter. No model turn or cloud remote-control pairing was exercised.
+
+Verification of the independent branch on 2026-09-17 (macOS, Node 24.16.0):
+
+- `npm run check`: **106 tests passed across 12 files**, plus formatting, strict typing, build and offline package/seven-tool discovery. The standalone installation tests belong to the separate setup branch and are not included here.
+- New tests cover proxy→queue selection, conservative busy/partial-record checks, stable request reconciliation, no duplicate submission across daemon restart, host watcher silence/duplicates/re-arming, non-consuming output, role-inbox filtering, manual registration upgrade and broadcast/direct info. The cold-start queue test waits for adapter readiness instead of relying on the test runner's default one-second polling deadline.
+- `npm run verify:zcode`: the installed desktop runtime validated the plugin and cache, discovered 1 command / 3 skills / 4 hooks / 1 MCP server and connected seven tools after source removal. The runtime opened the explicitly configured temporary session database. The script does not create sessions or send model requests.
+- The rebuilt CLI exposes the watcher, omits both standalone setup and new-session creation, and rejects `zcode create` without starting a daemon.
+- Local Codex CLI 0.153.4 exposes queue --thread/--message. The issue's historical end-to-end queue success is retained as field evidence; this iteration did not re-submit into a user's real desktop thread. Claude Monitor and ZCode background-task re-invocation likewise have the issue authors' live PoC evidence; automated watcher tests do not claim a new live-model GUI verification.
+
+Outstanding host acceptance is the real idle→notification→read→working→done loop in refreshed Codex, Claude and ZCode sessions, including a busy-turn backlog and watcher re-arm after native task expiry. Use a disposable channel/workspace and inspect tail/list for acceptance; tool/CLI availability alone is not the success criterion. No normal ~/.cmdr state, installed plugin cache or host trust settings were changed during verification.
+
+Release preparation for 0.3.0 synchronizes npm and host manifests and injects the package version into Vitest, matching the production build so process tests validate the released version rather than the minimum compatible client version. The release is prepared from merged PR #10 in a clean worktree.

package/docs/long-running-collaboration.md

@@ -53,33 +53,70 @@ On startup or after a wake, use ordinary `read` and `read(recover=true)`. Recove
 
 `read` omits squad_summary by default; `list` omits repeated member boards and detailed session fields. Listings never include command bodies, including with full=true. Use read(id=...) for your own messages, or operator tail --full for observation. Use `full=true` / `--full` for expanded metadata and `limit` / `--limit` to bound reads. Do not pipe a consuming read into head: output lost after delivery is recoverable through history/ID lookup, but is no longer unread.
 
-## Managed standby
+## Automatic standby
+
+`join(standby="auto")` requires a confirmed native identity and channel membership. Inspect `list` afterwards. A successful join registers intent; `can_auto_respond=true` requires a healthy delivery adapter or a live host watcher. Unknown hosts remain manual.
+
+| Host | Wake mechanism | What the Agent must do |
+| --- | --- | --- |
+| Codex | Daemon attaches through app-server proxy; falls back to `codex queue` when proxy is unavailable | Join with auto, check health, end the idle turn |
+| Claude Code | Native Monitor emits a notification for each watcher output line | Run `listener.arm.command` with Monitor; re-arm on expiry/exit |
+| ZCode desktop | Native background Bash re-invokes its session when the watcher exits | Run `listener.arm.command` with `run_in_background=true`; re-arm after each notification |
+
+All paths share the same actionable policy: command, cancel, ask, answer, system, terminal/blocked reports, attention-marked info and direct info. working/ready reports and broadcast info without attention are quiet. Commands gated by reassignment remain blocked. Observation does not consume messages or accept tasks. Every wake must be followed by `read` and `read(recover=true)`, cancellation handling, and correlated working/terminal reports.
+
+Report attention comes from the daemon's `attn` flag, computed at enqueue time. Default live and replayed events both omit `message.data`; do not filter those events by `data.status`. Use the built-in `--actionable` filter. `--full` includes the original data when needed. A quiet long-lived subscription does not itself indicate a stalled connection; periodic reconnects are unnecessary.
 
 ```sh
-cmdr standby start --session codex:REAL_THREAD_ID
-cmdr standby status --session codex:REAL_THREAD_ID
-cmdr standby stop --session codex:REAL_THREAD_ID
-cmdr standby resume --session codex:REAL_THREAD_ID
-# Optional explicit local host transport:
-cmdr standby start --session codex:REAL_THREAD_ID --adapter codex --executable /absolute/path/to/codex --socket /absolute/path/to/control.sock
+cmdr standby start --session SID
+cmdr standby status --session SID
+cmdr standby stop --session SID
+cmdr standby resume --session SID
 ```
 
-`join(standby="auto")` registers the same listener. It requires confirmed native identity and channel membership. There is one persisted listener per endpoint, executed by the existing single-instance daemon. Enabled listeners prevent idle daemon exit and recover on daemon restart. Stop disables future checks; it does not retract a wake already accepted by the host. `list`, `status` and `doctor` expose listener health and the latest request. No per-session lockfile, script or private host database parsing is required.
+### Codex: proxy and queue
 
-The built-in Codex adapter uses `codex app-server proxy` against the already running shared local host. It requires runtime support for `thread/read`, `thread/resume`, `thread/queue/list`, `thread/queue/add`, `thread/queue/start` and `thread/turns/list`, including client user-message IDs. The shared control socket must already be exposed by the host; a CLI installation alone is insufficient. Use --socket when the host exposes a nondefault local control socket. The listener never bootstraps a separate host daemon. These experimental queue methods are feature-checked through actual calls; older runtimes or unsupported endpoints show an error and do not claim automatic response. See the [official app-server reference](https://learn.chatgpt.com/docs/app-server) for the public transport and thread status APIs. Queue shapes were checked against this development machine's generated CLI protocol; this is not a claim of support in every Codex release.
+The proxy path connects `codex app-server proxy` to the already running host. It uses thread/read, thread/resume, thread/queue/list, thread/queue/add, thread/queue/start and thread/turns/list. A host that exposes these methods and the control socket can accept a stable client message ID and start that exact queued item. An unloaded thread is resumed in that same host. See the [official app-server reference](https://learn.chatgpt.com/docs/app-server) for the transport and state APIs; experimental queue shapes are checked against the installed CLI, not inferred from this reference.
 
-The adapter queues a metadata wake prompt for the registered existing thread, with a stable request ID, then asks the host to start that exact queued submission. An unloaded existing thread is resumed by its real ID through thread/resume, without supplying model, permission or sandbox overrides. It does not create threads or a separate app-server. Only actionable inbox messages and recoverable commands trigger a wake. working/ready reports and ordinary info do not; done/failed/blocked/cancelled/ask/answer/command do. Send `attention=true` for info that unblocks work. Busy sessions coalesce backlog, and urgent cancel is discovered at the next hook/tool checkpoint. No second competing model process is started.
+A missing socket now triggers a capability check for `codex queue --thread ID --message TEXT`. The queue path submits a metadata-only wake to the existing thread, without model, sandbox, approval or remote overrides. It does not explicitly launch a second app-server or call exec/resume to create a competing session. The CLI's internal transport remains host-owned.
 
-Wake stages are persisted before external calls: requested → accepted → observed. Host queue/history reconciliation distinguishes a lost response from a missing request. A request that might have succeeded is **not automatically resent**. Unknown outcomes show uncertain; accepted wakes with no progress show stalled. Errors are persisted and emitted as lifecycle events. After inspecting the host, the operator can explicitly resolve:
+The compatibility state reader requires Node >=22.12 (Node 24 recommended), because earlier node:sqlite versions lack the readOnly option. It opens `$CODEX_HOME/state_5.sqlite` read-only, resolves the exact thread's rollout_path and incrementally reads complete JSONL records. task_started means busy; task_complete/turn_aborted means idle. It scans the whole existing log once rather than a fixed tail window. Missing records, incompatible schema and unknown state prevent submission and produce concrete errors. This is a version-coupled fallback, not a stable public state API. The check-to-submit race is not atomic; the queue CLI must arbitrate a concurrent user turn.
+
+```sh
+# Automatic selection (default)
+cmdr standby start --session codex:REAL_ID --transport auto
+# Force a known path when diagnosing host capabilities
+cmdr standby start --session codex:REAL_ID --transport queue --executable /absolute/path/to/codex
+cmdr standby start --session codex:REAL_ID --transport proxy --socket /absolute/path/to/control.sock
+```
+
+Wake requests are persisted before delivery: requested → accepted → observed. An unresolved request pins its transport across restarts. Proxy reconciliation searches queue/history by client ID; queue reconciliation recognizes the stable `[cmdr wake UUID]` prefix only in user messages in the rollout. Queue exit 0 confirms submission but provides no queued item ID. Timeout/nonzero exit is uncertain, since delivery may already have happened. No cross-transport or automatic blind replay occurs. Accepted wakes with no progress become stalled. After inspecting the host and actual work:
 
 ```sh
 cmdr standby resume --session SID --resolve accepted
 cmdr standby resume --session SID --resolve retry
 ```
 
-`retry` explicitly permits a fresh wake; it is not evidence the previous attempt failed. After a completed host turn with changed but unfinished work, the listener can issue a recovery wake. Repeated notifications or listener restart do not independently create duplicate requests. Host acceptance is never task acceptance: only the command's correlated report confirms that.
+`retry` explicitly permits a new submission; it does not establish that the earlier one failed. Busy sessions coalesce backlog. Host acceptance remains separate from the command owner's working report.
+
+### Claude and ZCode: native host watchers
+
+Join/list returns `listener.arm` with an absolute installed command, the native host tool and re-arm instructions. The standard command is:
+
+```sh
+cmdr standby watch --session claude:REAL_ID
+cmdr standby watch --session zcode:REAL_ID
+```
+
+Claude uses its **Monitor tool**, not foreground Bash or shell `&`. Each stdout line becomes a native notification, queued into an active turn or opening an idle turn. The reporter's Monitor has a 30-minute lifetime; re-arm when the host reports expiry/exit. If Monitor is absent but the host supports background Bash completion notifications, use `--once` with `run_in_background=true`. If neither mechanism exists, explicitly select manual.
 
-Claude, ZCode and other MCP hosts currently report manual. `can_auto_respond` is true only for an enabled healthy adapter. A queued host submission with unknown runtime state remains unhealthy with can_auto_respond=false; once idle is confirmed, the same submission can start without another enqueue. After registration, check list; starting is not confirmation. With a healthy listener, the model may end its idle turn. Otherwise the skill permits at most two recommended waits, then explains manual continuation. Never promise active wakeup based solely on hooks or a successful send.
+ZCode uses **Bash with run_in_background=true**. Its native task survives the current turn and automatically re-invokes the session on completed/failed/killed. The built-in watcher remains silent during idle periods and exits after printing actionable metadata. It never consumes inbox messages, so a lost output notification still leaves the work available for recovery. On notification: inspect task output, read/recover, handle work, and re-arm. An immediate backlog produces an immediate notification; drain/reconcile it before re-arming.
+
+The command subscribes before inspecting current work, covering startup races, unread messages and read-but-unaccepted commands. At attach, accepted commands without pending cancellation are treated as already known: a blocked executor can re-arm and wait for an answer without repeatedly waking on its own unfinished task. Ownership and `read(recover=true)` remain unchanged; reconcile accepted work on startup or after context loss before arming. Unread answers, new commands and pending cancellation still notify, including cancellation requested after attach.
+
+It renews a 90-second daemon lease every 30 seconds. Exactly one lease owns a member; duplicate watchers are rejected. Only an attached live watcher is healthy. Disconnect removes its lease; a lost heartbeat expires it. A daemon restart closes the command so the host can notify and re-arm. App termination removes the native task; SessionStart reminds the Agent to inspect and re-arm it. A healthy lease establishes that the watcher is running, not that an individual model turn has already started.
+
+Check the host task status before re-arming. Stop disables the lease; its process exits at the next event/heartbeat, which itself may produce one last native notification. Skills do not impose the old two-wait limit when a native watcher is available. Bounded manual polling remains only for unsupported tools or failed arming. No repeating cron/model heartbeat is needed, and no PermissionRequest auto-approval is installed.
 
 ## Lifecycle observation
 
@@ -90,10 +127,12 @@ cmdr tail --for MEMBER_SID --after 123 --follow --json --full
 
 Events have monotonically increasing `event_seq`, timestamp, channel, kind, sender/recipient, message ID, reply_to and applicable reason/data. The stream covers enqueue/read, command acceptance/progress/terminal state, cancellation/reassignment, membership/role changes, connection/hooks and wake requests/acceptance/errors. `--full` includes complete message bodies/data; default text summarizes bodies. `--json` is one JSON event per line. The cursor is an **event sequence**, not a message seq.
 
+Without --after, --follow starts at the current event cursor. `--after now` makes that explicit; non-follow tail still shows recent history. Use `--actionable --for SID --format line` for concise metadata-only wake lines, or --json for structured events. The built-in watcher additionally checks current/recoverable work and tracks health, so prefer it for native host notifications.
+
 A follower subscribes before replay, deduplicates by event_seq, and reconnects with its last cursor. Observer calls never dequeue work. `--for` matches the recipient inbox (including its current commander role inbox); it is separate from observing the whole channel. Historical role-inbox events belong to the role, not permanently to a former commander's sid. Expired cursors produce `retention.gap`; observers can rebuild current work from list/recover. Cursors ahead of this database produce CURSOR_AHEAD instead of silently skipping events.
 
 ## Upgrade and verification boundary
 
 Automatic version-triggered shutdown is disabled, including upgrade requests from old clients. A newer client reports UPGRADE_REQUIRED. The 0.2 daemon rejects clients older than 0.2.0 (and missing/invalid versions) with PROTOCOL_MISMATCH before registration, because the tool semantics changed even though the wire protocol remains 1. Refresh/reinstall stale plugin caches and restart their MCP connections. `cmdr daemon restart` first opens a consistent SQLite backup in a temporary directory with the new bundle, exercising its schema and record readers before stopping the live service. A failed check leaves the old daemon running. Doctor lists connected clients and their versions; cached plugins still need refreshing/reinstalling.
 
-Tests exercise command recovery, role/member handover, cancellation gates, wake failure/reconciliation and CLI/daemon processes in disposable CMDR_HOME directories. They do not demonstrate that every host GUI grants hook trust or that real model turns will always acknowledge work. Real Codex queue execution and Claude/ZCode manual-continuation UX remain separate host checks. Windows, remote transport, new-agent creation and executor-to-executor messaging remain outside this implementation.
+Tests exercise command recovery, role/member handover, cancellation gates, wake failure/reconciliation and CLI/daemon processes in disposable CMDR_HOME directories. They do not demonstrate that every host GUI grants hook trust or that real model turns will always acknowledge work. Real model wake/report cycles remain separate host checks. Windows, remote transport, new-agent creation and executor-to-executor messaging remain outside this implementation.

package/docs/publishing.md

@@ -1,6 +1,6 @@
 # npm 发布
 
-本次发布版本为 `cmdr-mcp@0.2.0`。npm 包名是 `cmdr-mcp`，CLI、宿主插件和 marketplace 名称仍为 `cmdr`。安装后的包根目录是 `$(npm root -g)/cmdr-mcp`。
+本次发布版本为 `cmdr-mcp@0.4.0`。npm 包名是 `cmdr-mcp`，CLI、宿主插件和 marketplace 名称仍为 `cmdr`。全局安装后的包根目录是 `$(npm root -g)/cmdr-mcp`。
 
 ## 准备与验证
 
@@ -10,12 +10,12 @@
 npm ci
 npm run check
 npm pack
-npm publish ./cmdr-mcp-0.2.0.tgz --dry-run --access public --registry https://registry.npmjs.org/
+npm publish ./cmdr-mcp-0.4.0.tgz --dry-run --access public --registry https://registry.npmjs.org/
 ```
 
 涉及 ZCode 的发布另运行 `npm run verify:zcode`：从实际 tarball 安装到隔离缓存，核对完整性并移走安装源后验证 7 个工具；需要本机 ZCode runtime。
 
-`npm run check` 包括格式、类型、构建、测试以及临时目录中的 npm 包离线安装验证：检查发布资源、安装后 marketplace 路径、CLI 和 7 个 MCP 工具。`npm pack` 通过 `prepack` 生成 4 个运行入口及第三方许可证声明，输出 `cmdr-mcp-0.2.0.tgz`。源码、测试和开发依赖不进入发布包。
+`npm run check` 包括格式、类型、构建、测试以及临时目录中的 npm 包离线安装验证：检查发布资源、安装后 marketplace 路径、CLI 和 7 个 MCP 工具。`npm pack` 通过 `prepack` 生成 4 个运行入口及第三方许可证声明，输出 `cmdr-mcp-0.4.0.tgz`。源码、测试和开发依赖不进入发布包。
 
 检查 `git diff`，确认版本与预期一致，构建未意外修改宿主 manifests。发布前保留经过验证的源码提交；不要手改或提交 `plugins/cmdr/dist/`、`THIRD_PARTY_NOTICES.txt` 和 `.tgz`。
 
@@ -36,20 +36,20 @@ npm view cmdr-mcp name version --registry https://registry.npmjs.org/
 确认发布时，上传已检查的 tarball，并按 npm 提示完成账号验证：
 
 ```sh
-npm publish ./cmdr-mcp-0.2.0.tgz --access public --registry https://registry.npmjs.org/
+npm publish ./cmdr-mcp-0.4.0.tgz --access public --registry https://registry.npmjs.org/
 ```
 
-此命令会公开发布 `0.2.0` 并使用默认的 `latest` 标签。相同包名和版本不能重复发布；后续修改需要提升版本并重新构建验证。发布使用 tarball，以保持上传内容与已检查产物一致。
+此命令会公开发布 `0.4.0` 并使用默认的 `latest` 标签。相同包名和版本不能重复发布；后续修改需要提升版本并重新构建验证。发布使用 tarball，以保持上传内容与已检查产物一致。
 
 ## 发布后核对
 
 ```sh
-npm view cmdr-mcp@0.2.0 name version dist.integrity --registry https://registry.npmjs.org/
-npm install --global cmdr-mcp@0.2.0 --registry https://registry.npmjs.org/
+npm view cmdr-mcp@0.4.0 name version dist.integrity --registry https://registry.npmjs.org/
+npm install --global cmdr-mcp@0.4.0 --registry https://registry.npmjs.org/
 cmdr --help
 ```
 
-按照 [安装说明](README.zh-CN.md#安装) 注册安装后的包根目录。已安装宿主有插件缓存，升级后需要刷新或重装；同版本测试代码变动需要重启对应测试 daemon。
+按照[安装说明](README.zh-CN.md#安装)运行 setup 或注册原生插件。原生插件升级后刷新或重装宿主缓存，使用新版本 CLI 执行 `cmdr daemon restart`，再重连 MCP；该命令先做一致性预检，再替换旧 daemon。随后检查监听状态，Claude/ZCode 按 `listener.arm` 重新挂载 watcher。
 
 npm 命令行为参考：[npm publish 官方文档](https://docs.npmjs.com/cli/v11/commands/npm-publish/)。
 

package/docs/setup.md

@@ -0,0 +1,45 @@
+# Standalone setup
+
+Available from cmdr-mcp 0.4.0. Requires macOS/Linux and Node.js >=22.5 (24 recommended).
+
+```sh
+npx -y --package=cmdr-mcp@latest cmdr setup --agent claude-code
+```
+
+Choose `claude-code`, `codex` or `zcode`. Setup installs a persistent runtime, the `cmdr` skill, MCP and user hooks, then checks the seven tools in temporary state. Use the printed CLI path (normally `~/.cmdr/bin/cmdr`), open a new host session and complete any trust prompts. Existing hook opt-outs are preserved. Other MCP hosts use `cmdr config --agent <host-id>`.
+
+To install only the self-contained skill and its role/setup references:
+
+```sh
+npx skills add njugray/cmdr --skill cmdr
+```
+
+Add `-g` for global scope or `--agent <supported-agent>` to select a host. This installs no runtime or MCP configuration; use an existing cmdr integration or run setup. Choose setup or the native plugin for each host to avoid duplicate tools and hooks. Invoke the standalone skill through the host's skill interface or ask “use cmdr to join my-project”.
+
+## Configuration
+
+| Host | MCP configuration | User hooks | Skill |
+| --- | --- | --- | --- |
+| Claude Code (`claude-code`, alias `claude`) | `~/.claude.json` | `~/.claude/settings.json` | `~/.claude/skills/cmdr` |
+| Codex | `$CODEX_HOME/config.toml`, default `~/.codex/config.toml` | `$CODEX_HOME/hooks.json` | `$CODEX_HOME/skills/cmdr` |
+| ZCode | `~/.zcode/cli/config.json`, `mcp.servers` | Same file, `hooks.events` | `~/.zcode/skills/cmdr` |
+
+| Option | Purpose |
+| --- | --- |
+| `--dry-run` | Preview destinations/conflicts without installing runtime or changing host configuration |
+| `--json` | Return paths, changes, warnings and backup location as JSON |
+| `--config-dir PATH` | Select a custom host **user** profile directory; launch the host with that same profile |
+
+`CLAUDE_CONFIG_DIR` is respected; its MCP file is `<CLAUDE_CONFIG_DIR>/.claude.json`. ZCode loads user hooks, not workspace hooks. `CMDR_HOME` selects runtime/state storage (default `~/.cmdr`): build directories live in `runtimes/`, stable profile-specific launchers in `bin/`. They survive npx cache removal and bind the host/state directory, never a fixed session ID. See [host integration](agent-integration.md) for identity and lifecycle contracts.
+
+## Upgrade and recovery
+
+Repeat setup with the newer package to upgrade. Unchanged files stay unchanged; prior runtime directories remain available to existing processes. Setup does not restart the daemon. If it reports `UPGRADE_REQUIRED`, coordinate active work, run `<printed-cli> daemon restart`, then reconnect sessions.
+
+Setup preserves other servers, settings and hooks. Codex retains unrelated TOML text/comments; JSON settings are reformatted without discarding other values. Malformed configuration, an enabled cmdr plugin, an unmanaged cmdr MCP entry or an unrelated skill named `cmdr` stops setup before host changes.
+
+Existing copies/symlinks of this repository's skill are backed up and replaced with a link to the persistent runtime. Shared npx-skills sources are left intact; custom files in an adopted copy remain in its backup. Upgrade setup-managed skills through setup.
+
+Backups live in `<CMDR_HOME>/setup-backups/<run>/`. `restore.json` maps each changed path to its backup (`null` marks a newly created entry). Failed writes are rolled back; concurrent edits are reported for manual recovery. After a crash, inspect that record before retrying. Remove a stale `setup.lock` only after confirming its recorded process has stopped.
+
+For diagnostics, run `<printed-cli> doctor --deep`. Move a damaged runtime directory aside and rerun setup from an intact package. Native plugins require their own cache refresh. For [automatic standby](long-running-collaboration.md#automatic-standby), Claude/ZCode arm `listener.arm.command` with the indicated native host tool; Codex uses daemon-managed proxy/queue delivery. GUI trust, actual hook execution and automatic wake must be verified in the host; setup's isolated MCP check does not establish those capabilities.

package/docs/troubleshooting.md

@@ -86,3 +86,9 @@ Short-lived commands display cli and retain task ownership after exit. They do n
 - Missing runtime or Node now produces one stderr line from the fail-open hook wrapper as well as the bounded diagnostic snapshot.
 
 See [long-running collaboration](long-running-collaboration.md) for adapter requirements and recovery examples.
+
+## Automatic wake diagnostics
+
+- Codex: `standby status --session SID` shows the selected `transport`. Auto mode tries proxy then queue. Missing socket alone no longer establishes that wake is unavailable. Queue compatibility needs Node >=22.12, an available CLI with queue --thread/--message, and readable state_5/rollout lifecycle records in the daemon's CODEX_HOME. Inspect the concrete proxy/queue error before choosing an explicit executable or transport.
+- Claude/ZCode: `wake_mode=claude|zcode` with starting means the native watcher still needs arming. Use the absolute `listener.arm.command` with Monitor or background Bash as specified; shell detachment cannot supply a native completion notification. WATCHER_ACTIVE means inspect/reuse the existing native task. Re-arm after daemon/App restart or native task expiry.
+- `uncertain` is not automatic retry permission. Reconcile host history and cmdr work, then choose standby resume --resolve accepted or retry. CLI acceptance never substitutes for a working report from the member.