@logicseek/hello-cc 1.0.0 → 1.0.2-dsh.3

package/docs/dsh.zh-CN.md

@@ -0,0 +1,139 @@
+# DeepSeek Harness 接入
+
+[English](dsh.md) | 中文
+
+DeepSeek Harness（`dsh`）可以与 Claude Code、Codex 共用 hello-cc 的项目任务、消息、协作锁和交接。现在有三个入口：官方 hooks 兼容桥、原生 Cordis 协作插件，以及 hello-cc 持有的 ACP 后台 worker。
+
+运行时基线固定为 `@deepseek-ai/dsh@0.2.0-rc.2`，相关插件使用相同版本。需要 Node.js 24+，并确认 `PATH` 中的 `node` 也符合要求，因为 dsh 通过 `/usr/bin/env node` 启动。此版本提供 Web/headless/SDK/ACP profile，没有内置 TUI。
+
+支持 Linux 和 macOS；Windows 使用 WSL，不支持原生 Windows shell。容器验证与实际设备验收分别记录。
+
+代码已在本地实现并做真实 DeepSeek 模型验收，尚未发布新的 npm 版本。验证源码时，用本仓库的 CLI：
+
+```bash
+node /absolute/path/to/hello-cc/bin/hcc.mjs --root /path/to/project dsh setup --mode cordis
+node /absolute/path/to/hello-cc/bin/hcc.mjs --root /path/to/project dsh status
+node /absolute/path/to/hello-cc/bin/hcc.mjs --root /path/to/project dsh web -- --port 8080
+```
+
+下文 `hcc` 指包含这些代码的 CLI。已有的全局 `hcc` 未必包含此接入。
+
+## 选择入口
+
+| 入口 | 适用场景 | 会话由谁持有 |
+| --- | --- | --- |
+| `hcc dsh web --mode cordis` | 在 Harness Web 中对话，模型直接使用 `hcc_*` 协作工具 | Harness；一个服务可承载多个 Agent/工作区 |
+| `hcc dsh web --mode hooks` | 保留官方 Claude hooks 兼容路线，模型用带身份的 hcc CLI 命令协作 | Harness；默认模式 |
+| `hcc native start --provider dsh` | 从 hello-cc CLI/Web 管理提示、回执、中断和关闭 | hello-cc 专属 ACP worker；每个 worker 一个独立进程 |
+
+Cordis 模式与 hooks 模式共用同一任务总线，但对同一个会话只允许一个注入器。ACP worker 使用自己的 native 生命周期与 scoped MCP 能力，不给它额外加载 Cordis/hooks 协作注入器。
+
+## Harness Web 与 Cordis 插件
+
+先配置 Harness 模型凭据。默认 DeepSeek provider 使用已有 `DEEPSEEK_API_KEY`，启动器保留凭据和 provider 路由环境变量。可以使用已有安装，或自行安装固定版本：
+
+```bash
+npm install -g @deepseek-ai/dsh@0.2.0-rc.2
+cd /path/to/project
+hcc dsh setup --mode cordis
+hcc dsh status
+hcc dsh web -- --port 8080
+```
+
+打开 Harness 输出的 URL，创建真实会话，并将项目设为会话工作区。仅启动服务不会创建 Agent peer。需要 hello-cc 控制台时另开 `hcc web --local`；dsh 筛选显示原始会话 ID，可以查看状态和发送项目消息。
+
+Cordis 插件使用 `agent/created` 的等待式初始化、`agent/pre-step` 的决定链、`agent/status`/`agent/disposed` 和工具事件。每次执行从 `exec.agent` 获取固定项目与 peer，不读取服务级 `HCC_PEER`。插件提供：
+
+| 工具 | 用途 |
+| --- | --- |
+| `hcc_state` / `hcc_task_list` / `hcc_inbox` | 读取项目状态、任务和本会话收件箱 |
+| `hcc_task_next` | 继续当前任务或认领待办，不自动完成任务 |
+| `hcc_message_send` | 以本 Agent 身份发送项目协作消息 |
+| `hcc_handoff` | 记录所持任务的交接内容 |
+| `hcc_lock_acquire` / `hcc_lock_release` | 获取/释放本 peer 的作用域协作锁 |
+| `hcc_result_list` / `hcc_result_record` | 读取/记录本地验证证据，不代表发布或业务验收 |
+
+底层复用 CLI/MCP 的事务、任务归属和锁规则。上下文与工具输出默认各限制 16,000 字符；过长输出明确标记截断，未完整投递的消息保留未读。工具参数的长度、数量和归属由服务再次验证。消息只在 Harness 提交对应 `user/message` 记录后 ACK；拒绝首轮、准备失败和取消不会提前 ACK。
+
+插件委托 `next()`，保留现有 deny/ask 权限决定。关闭 Agent 只更新其自身 peer；卸载时移除监听与工具注册，并使旧的执行权限失效。重新加载时，既有 Agent 在下一个等待式 pre-step 重新取得身份。异常退出后，只有核实原进程已退出或 PID 已被复用时，同一会话才能恢复 Cordis 归属；活跃或无法验证的 owner，以及 hooks/native 冲突绑定仍会被拒绝。发送项目消息本身不会唤醒持续空闲的 Harness 会话；它在下一步骤进入上下文，或在活动轮次的停止边界继续处理。
+
+## 配置模式与参数
+
+```text
+hcc dsh setup [--mode hooks|cordis|off]
+hcc dsh status [--dsh-bin PATH]
+hcc dsh web [--mode hooks|cordis|off] [--dsh-bin PATH] [--dsh-home PATH] -- [dsh arguments]
+```
+
+首次默认 `hooks`，以后不带 `--mode` 时沿用托管配置记录的选择。`status` 校验内容与可执行文件，不发模型请求。
+
+```bash
+hcc dsh setup --mode hooks    # 官方兼容桥
+hcc dsh setup --mode cordis   # 原生协作插件
+hcc dsh setup --mode off      # 项目 overlay 不再加入协作插件
+hcc dsh web --dsh-bin '/opt/harness/bin/dsh' --dsh-home '/path/to/dsh-home' -- --port 8080 --no-open
+hcc dsh web --help            # hello-cc 帮助
+hcc dsh web -- --help         # Harness Web 帮助
+```
+
+`--dsh-bin` 是文件路径，`--dsh-home` 设置子进程 `DSH_HOME`；相对路径按执行目录解析。所有 Harness 参数放在 `--` 后，按原顺序传递，包括额外 `--patch`。模式变更影响后续启动，关闭当前自有 runtime 后重新启动才会生效。已有 hooks/native 会话不会被强行改绑为 Cordis；切换时使用新会话，保留旧会话的协作数据。
+
+托管文件如下：
+
+| 文件 | 用途 |
+| --- | --- |
+| `.hello-cc/dsh/hooks.json` | hello-cc 专用 SessionStart/UserPromptSubmit/PreToolUse/PostToolUse/Stop hooks |
+| `.hello-cc/dsh/cordis.patch.yml` | 只加载选定注入器；off 为无插件 overlay |
+| `.hello-cc/dsh/managed.json` | 模式、归属、路径、基线版本与 SHA256 |
+
+Setup/disable/re-enable 幂等。升级或移动源码后可再次 setup 刷新绝对路径；手工修改、外来内容、符号链接、硬链接或归属冲突会保留原文件并返回错误。定制配置放在独立 overlay。Setup 不安装 dsh，不改用户 home，不复制密钥，不导入整份 Claude/Codex hooks。
+
+每个 Agent 的真实 `session_id` 和绝对 `cwd` 路由到该工作区自己的 `.hello-cc/mesh.db`，不向父目录找项目。原始非 UUID ID 会保留，hash 碰撞、重复会话别名或其他 live transport 归属都会被拒绝。hooks 与 Cordis peer 禁止被 detected stop/restart 或 tmux attach 改成终端；服务日志面板仍可作为独立 shell peer。
+
+hooks 基线 rc.2 会等待 SessionStart 返回后注入首轮，PreToolUse 用于活动跟踪，PostToolUse/Stop 用于消息投递；官方桥不消费 PreToolUse 的 `additionalContext`。这条兼容路线的 ACK 发生在 hook 输出成功后；Cordis 的 ACK 发生在对应上下文记录提交后。
+
+## ACP 后台 worker
+
+```bash
+hcc native up
+hcc native start --peer dsh-reviewer --provider dsh
+hcc native send --peer dsh-reviewer --from coordinator --body '审查当前改动，报告验证结果'
+hcc native deliveries --peer dsh-reviewer
+hcc native events --peer dsh-reviewer
+hcc native interrupt --peer dsh-reviewer
+hcc native close --peer dsh-reviewer
+hcc native start --peer dsh-reviewer --provider dsh --binary /absolute/path/to/dsh --resume last
+```
+
+默认从 PATH 查找官方 `dsh`；不在 PATH 时用 `--binary /absolute/path/to/dsh` 指定 launcher。worker 使用独立 `dsh --profile acp` 进程；send 返回入队回执，只有权威 prompt 完成事件才代表投递完成。恢复保留 provider session 身份和已有会话记忆；ACP 不回放整个 transcript，也不提供 fork/steer。Web 中使用 native 专属会话入口及审批响应，不能用 detected 注册状态操作代替 worker 生命周期。详见 [Native worker](native.zh-CN.md)。
+
+## 可安装 bundle 与验收
+
+包声明 `dsh.bundle`，overlay 位于 `lib/integrations/dsh.bundle.yml`，类型声明位于 `lib/integrations/dsh-cordis.d.ts`。元数据声明 `engines.dsh=0.2.0-rc.2`；插件还实际检查 agent/agent-loop/tools/session 包版本，遇到不匹配会在注册前拒绝启动。
+
+本地项目 overlay 已可用。setup 的 managed manifest 记录 Cordis 模块位置；从源码切换到 npm 安装目录时会校验并迁移未编辑的配置，保留用户编辑过的文件。需要 profile 级安装时，先生成包含最新源码的 tarball，再通过官方包管理入口安装：
+
+```bash
+npm pack --ignore-scripts
+dsh plugin --profile web add /absolute/path/to/logicseek-hello-cc-1.0.1.tgz
+```
+
+Harness 的 pnpm 策略要求明确允许原生依赖构建。若首次 add 返回 `ERR_PNPM_IGNORED_BUILDS`，在所选 profile 的 `pnpm-workspace.yaml` 中合并以下配置，然后重跑同一 add 命令；默认位置是 `~/.dsh/profiles/web/pnpm-workspace.yaml`，自定义 DSH_HOME 时以该目录为准。保留文件中已有设置，只批准候选包使用的固定版本：
+
+```yaml
+allowBuilds:
+  node-pty@1.2.0-beta.15: true
+```
+
+安装后由 Harness profile 的 `dsh.profile.bundles` 选择包；不要再同时加载项目 Cordis/hooks overlay。bundle 已通过实际 npm 安装、官方 add/重复 add/remove、隔离 profile 加载和真实模型工具调用。2026-10-02 已安装到本机真实 desktop profile 并热加载，配套 ACP 使用既有 DeepSeek 路由完成真实工具调用；初次桌面 sub2api 模型返回账户仅允许 Codex 官方客户端的 403；随后桌面默认模型已变为官方 DeepSeek，沿用当时配置的新建会话完成 hcc_state、hcc_message_send 和真实 completed 回合。原 sub2api 路由限制仍存在。npm 尚未发布。profile 插件安装/移除由 Harness 管理，项目 overlay 则使用 `setup --mode off` 关闭。
+
+验证记录见 Cordis/native 验收 (源码目录: `docs/verification/2026-10-02-dsh-cordis-native.md`)、兼容桥记录 (源码目录: `docs/verification/2026-10-02-dsh-official-bridge.md`) 和详细接入计划 (源码目录: `docs/plans/2026-10-02-dsh-integration.md`)。真实模型验收在临时项目和自有进程中完成；既有会话与模型凭据保留；本机实际安装记录见 Mac 接入验收 (源码目录: `docs/verification/2026-10-02-dsh-device-install.md`)。尚未发布/部署，也没有跨设备验收或真实业务签收；隔离订单样例已完成报告、证据、交接、解锁与任务结束验证。
+
+可用下面的安装验收脚本重现 npm 安装、官方 `plugin add` / 重复 add / remove，以及安装后的公共 CLI。`--run-live` 会沿用已有 DeepSeek 认证，验证 ACP 权限拒绝和一个隔离订单汇总任务；没有该参数时不调用真实模型。脚本只使用本次创建的 HOME、DSH_HOME、项目和进程。
+
+```bash
+node scripts/dsh-installed-acceptance.mjs /absolute/path/to/isolated-dsh-install \
+  --run-live --output-dir /absolute/path/to/acceptance-output
+```
+
+输出包含候选 tarball、SHA256 与安装回执、脱敏命令日志和正确的订单报告。权限探针在私有 profile 中为一个测试文件设置 ask 策略，实际收到 ACP 请求后拒绝并检查文件未生成；订单样例证明本地协作闭环，不替代真实业务签收。

package/docs/guide.md

@@ -40,12 +40,70 @@ the supported downgrade contract.
 
 ## Install, Update, And Uninstall
 
+### Prerequisites
+
+Install Node.js 24 or newer from the official Node.js packages or a Node
+version manager. Browser-controllable terminals also require `tmux`:
+
+```bash
+# Debian / Ubuntu
+sudo apt-get update
+sudo apt-get install -y tmux
+# Fedora / RHEL
+sudo dnf install -y tmux
+# Older RHEL / CentOS
+sudo yum install -y tmux
+# Alpine
+sudo apk add tmux
+# Arch Linux
+sudo pacman -S --needed tmux
+# openSUSE
+sudo zypper install tmux
+# macOS only
+brew install tmux
+```
+
+On Linux, use the distribution package manager, not Homebrew. A root shell can
+omit `sudo`. WSL follows the matching Linux distribution instructions inside
+WSL; native Windows shells are not supported.
+
+`hcc web` can attempt to install tmux when a supported package manager and
+sufficient privileges are available. Manual installation is the deterministic
+choice for servers, containers, and non-interactive sudo configurations.
+
+### Install And Verify
+
 Install hello-cc globally:
 
 ```bash
 npm install -g @logicseek/hello-cc
 ```
 
+If npm reports `EACCES`, use a Node version manager or configure a user-owned
+npm prefix. Do not use `sudo npm install -g`, because it can create root-owned
+package and configuration files.
+
+Verify every prerequisite and the installed CLI:
+
+```bash
+node --version
+npm --version
+tmux -V
+hcc --version
+hcc --help
+```
+
+The Node version must start with `v24` or a newer major. Every command above
+must exit successfully before starting a managed terminal.
+
+To avoid a global install, use:
+
+```bash
+npx @logicseek/hello-cc web
+```
+
+### Update And Uninstall
+
 Update an existing global install:
 
 ```bash

package/docs/guide.zh-CN.md

@@ -36,12 +36,67 @@ v1 会把恢复的数据库重新迁移到 schema v7；用旧版本 hello-cc 打
 
 ## 安装、更新和卸载
 
+### 前置依赖
+
+通过 Node.js 官方软件包或 Node 版本管理器安装 Node.js 24 或更新版本。浏览器可
+控制的终端还需要 `tmux`：
+
+```bash
+# Debian / Ubuntu
+sudo apt-get update
+sudo apt-get install -y tmux
+# Fedora / RHEL
+sudo dnf install -y tmux
+# 旧版 RHEL / CentOS
+sudo yum install -y tmux
+# Alpine
+sudo apk add tmux
+# Arch Linux
+sudo pacman -S --needed tmux
+# openSUSE
+sudo zypper install tmux
+# 仅 macOS
+brew install tmux
+```
+
+Linux 必须使用当前发行版的系统包管理器，而不是 Homebrew。root shell 可以省略
+`sudo`。WSL 用户应在 WSL 内部按对应 Linux 发行版安装；不支持原生 Windows
+shell。
+
+当存在受支持的包管理器且权限足够时，`hcc web` 可以尝试自动安装 tmux。对于
+服务器、容器和非交互式 sudo 环境，手动安装是确定性更高的方式。
+
+### 安装和验证
+
 全局安装 hello-cc：
 
 ```bash
 npm install -g @logicseek/hello-cc
 ```
 
+如果 npm 报 `EACCES`，请使用 Node 版本管理器或配置用户自有的 npm prefix。
+不要使用 `sudo npm install -g`，否则可能产生 root 所有的包和配置文件。
+
+验证全部前置依赖和 CLI：
+
+```bash
+node --version
+npm --version
+tmux -V
+hcc --version
+hcc --help
+```
+
+Node 版本应为 `v24` 开头或更高主版本；启动托管终端前，上述命令都应成功退出。
+
+不全局安装时可以使用：
+
+```bash
+npx @logicseek/hello-cc web
+```
+
+### 更新和卸载
+
 更新已有的全局安装：
 
 ```bash

package/docs/mcp.md

@@ -0,0 +1,9 @@
+# Executor-scoped MCP coordination
+
+Web-owned Codex App Server executors and HCC-hosted Codex/Claude/dsh native workers receive a dedicated stdio MCP server. Its temporary capability binds the project root, database, peer, worker owner and live runtime process identity. Configuration is passed through the provider session API; it does not modify global provider configuration, authentication or trust settings.
+
+Tools expose coordination state, tasks, inbox, message sending, handoff, owned resource locks and local result records. They reuse the existing business commands. Model arguments cannot change the project/database/peer, force another peer's lock, or record publication/business acceptance. Task claiming, handoff and evidence recording never mark a task done automatically.
+
+The internal entry point is `hcc --root PROJECT --db DATABASE mcp serve --peer PEER`. A private executor-issued capability is required; `--peer` alone grants no authority. Every call verifies the live executor and its database binding, and writes check ownership again in their business transaction. Closing the executor revokes and removes its capability. Unix permissions are 0700 for the temporary directory and 0600 for the capability file.
+
+Native workers acquire the scoped capability before startup and revoke it before shutdown or failed-start cleanup. Codex uses thread config, Claude uses SDK mcpServers and dsh uses ACP session mcpServers. Arbitrary external CLI/TUI processes do not receive this capability automatically. See [the Chinese tool reference](mcp.zh-CN.md) for individual tools, [native workers](native.md) for provider approval behavior, and [Web handoff](web-handoff.zh-CN.md) for result review and lifecycle boundaries.

package/docs/mcp.zh-CN.md

@@ -0,0 +1,23 @@
+# 受执行器约束的 MCP 协作工具
+
+Web 专用 Codex App Server，以及由 HCC 托管的 Codex/Claude/dsh native worker，都会获得专用 stdio MCP 配置。它固定项目 root、数据库、peer、worker owner 和活动 runtime 进程身份。配置通过 provider 会话 API 传入，不写用户的全局配置、账号或信任设置。
+
+| 工具 | 作用 |
+| --- | --- |
+| `hcc_state` | 查询当前项目/peer 的协作状态 |
+| `hcc_task_list` / `hcc_task_next` | 查询任务，返回已有任务或领取一个待办 |
+| `hcc_inbox` | 读取当前 peer inbox，不自动确认消息已处理 |
+| `hcc_message_send` | 以当前执行器 peer 身份写入项目消息总线 |
+| `hcc_handoff` | 记录已归属任务的工作、测试和风险 |
+| `hcc_lock_acquire` / `hcc_lock_release` | 获取或释放当前 peer 的资源锁 |
+| `hcc_result_list` / `hcc_result_record` | 读取结果记录，写入已归属任务的本地证据 |
+
+模型不能通过工具参数更换项目、数据库、peer，不能强制夺取别人的锁。每次调用检查原执行器仍存活且数据库 binding 仍由它持有；写入还在业务事务内复核身份与任务归属。执行器关闭、peer 被替换或能力凭据被撤销后，旧 MCP 进程不能继续写入。
+
+内部入口为 `hcc --root PROJECT --db DATABASE mcp serve --peer PEER`。它需要执行器创建的临时私有 capability 文件及 token，单独填写 `--peer` 不授予身份。文件权限在 Unix 为目录 0700、文件 0600，执行器退出后删除。手工启动不会注册或覆盖已有 peer。
+
+MCP 复用现有任务、消息、锁与 handoff 命令的业务规则。工具返回成功只说明对应协作操作完成；不会自动把任务改为 done。`hcc_result_record` 只报告本地证据，模型填写的记录会注明来源，不代替 Web 中人工记录的发布部署或业务验收。
+
+native worker 在启动前建立受限 capability，关闭 worker 或启动失败清理前撤销。Codex 通过 thread config、Claude 通过 SDK mcpServers、dsh 通过 ACP session mcpServers 接入。任意外部 CLI/TUI 不会自动获得此权限。发信等写操作仍可能需要 provider 人工审批，处理方式见 [Native 指南](native.zh-CN.md)。
+
+三种模型使用 MCP 发送协作消息的真实回执见 跨 provider 通信验收 (源码目录: `docs/verification/2026-10-02-native-live-communication.json`)。模型发信、接收方回复、ACK 和无回复循环均有单独检查；这不代替发布安装或业务任务验收。

package/docs/native.md

@@ -0,0 +1,295 @@
+# Native workers
+
+Native mode runs background workers that HCC creates and owns. HCC keeps the
+shared peer, task, message, lock, and handoff model; each provider adapter owns
+its execution connection and reports structured lifecycle events.
+
+| Provider | Connection | Session identity | Busy-worker input |
+| --- | --- | --- | --- |
+| Codex | Owned `codex app-server` over stdio JSON-RPC | Codex thread ID | Adapter supports `turn/steer` with the active turn precondition |
+| Claude | Optional Claude Agent SDK, persistent streaming input | Claude session ID confirmed by SDK initialization | One submission at a time; steering is unsupported |
+| DeepSeek Harness | Owned `dsh --profile acp` process | ACP session ID | One submission at a time; steering is unsupported |
+
+The HCC host currently dispatches one inbox message at a time to each worker,
+including for Codex. Adapter support for steering does not mean the host sends
+multiple pending inbox messages into the same turn. ACP resume and session close
+depend on the extensions the provider advertises. HCC does not claim that an ACP
+resume replays the original conversation transcript.
+
+## Requirements
+
+Use Node.js 24 or later and a provider installed and authenticated in the same
+environment as HCC. Native mode preserves authentication configuration and does
+not rewrite accounts, provider settings, or the user's home directory.
+
+Codex needs an app-server-compatible CLI. DeepSeek Harness uses its ACP profile;
+the implementation targets `@deepseek-ai/dsh-acp@0.2.0-rc.2`. This mode does not
+connect to a running dsh Web service.
+
+Claude's SDK remains optional and is loaded only when a Claude worker opens.
+For a checkout of this repository, install the documented SDK version explicitly:
+
+```sh
+npm install --no-save --package-lock=false @anthropic-ai/claude-agent-sdk@0.3.287
+```
+
+For a global HCC installation, install that version into the same npm prefix:
+
+```sh
+npm install -g @anthropic-ai/claude-agent-sdk@0.3.287
+```
+
+Alternatively, install the optional SDK in the worker's project:
+
+```sh
+cd /absolute/path/to/worker-project
+npm install --no-save --package-lock=false @anthropic-ai/claude-agent-sdk@0.3.287
+```
+
+The default loader first checks HCC's installation, then the worker project's
+node_modules, so a global HCC can use a project-local SDK. HCC never installs
+packages automatically. Missing SDKs produce installation guidance; errors from
+a found SDK's exports or dependencies retain their original cause. A separate
+real Web approval receipt (source checkout: `docs/verification/2026-10-02-native-web-claude-default-sdk.json`)
+exercises this default project lookup without injecting a query function. It
+does not verify a published package or an employee installation.
+
+## CLI
+
+Run commands from the project you want the workers to share, or select it with
+the existing global `--root` and `--db` options.
+
+```sh
+hcc native up
+hcc native start --peer codex-reviewer --provider codex
+hcc native start --peer claude-reviewer --provider claude
+hcc native start --peer dsh-reviewer --provider dsh
+hcc native send --peer codex-reviewer --from coordinator --body "Review the current changes and report concrete findings."
+hcc native status
+hcc native deliveries --peer codex-reviewer
+hcc native events --peer codex-reviewer --after 0
+hcc native requests --peer codex-reviewer
+hcc native respond --peer codex-reviewer --request REQUEST_ID --decision accept
+hcc msg inbox --peer coordinator
+```
+
+`start` starts the project's native runtime when needed. Workers share its HCC
+message bus even when `--cwd DIR` selects another working directory. `--model
+MODEL` selects a provider-supported model. `--binary PATH` overrides the Codex
+or dsh executable. Claude uses the SDK and rejects `--binary`.
+
+| Command | Options / behavior |
+| --- | --- |
+| `hcc native up` | Start or reuse the project's background runtime |
+| `hcc native status` | Inspect persisted worker state and runtime identity |
+| `hcc native start` | Required `--peer NAME --provider codex\|claude\|dsh`; optional `--cwd DIR --model MODEL --resume last`; `--binary PATH` is available only for Codex and dsh |
+| `hcc native send` | Required `--peer NAME --body TEXT`; optional `--from NAME --task ID`; returns a durable message/submission receipt |
+| `hcc native deliveries` | Optional `--peer NAME`; inspect delivery receipts |
+| `hcc native events` | Required `--peer NAME`; optional `--after ID`; inspect a bounded event history |
+| `hcc native requests` | Requires `--peer NAME`; inspect pending requests bound to this executor, session and turn |
+| `hcc native respond` | Requires `--peer NAME --request ID --decision accept\|decline\|cancel`; use `--response-file JSON` for permission subsets or answers |
+| `hcc native interrupt` | Required `--peer NAME`; optional `--turn ID`; request interruption of the active turn |
+| `hcc native close` | Required `--peer NAME`; close that worker's owned connection/process |
+| `hcc native down` | Request worker closure and runtime shutdown; returns a stop-request receipt |
+
+The `native down` receipt confirms the stop request, not completed shutdown.
+Inspect `native status` to check the outcome. If provider shutdown fails, HCC
+retains runtime ownership and reports the error in `status.shutdown_error`;
+resolve the reported problem and retry `native down`.
+
+Worker events retain semantic output and completion evidence; token deltas are
+not persisted as delivery receipts. The runtime keeps local state under
+`<project>/.hello-cc/native/` and coordination records in the selected HCC
+database. Runtime control is a local authenticated API, separate from the
+browser terminal transport. Treat its local runtime pointer and log as private
+project state.
+
+## Reading delivery receipts
+
+A successful `native send` queues a message. It does not mean the provider has
+read it, completed it, or returned a business result.
+
+| State | Meaning |
+| --- | --- |
+| `queued` | Stored on HCC's message bus, waiting for dispatch |
+| `dispatching` | HCC started handing the submission to its adapter; provider admission is still pending |
+| `submitted` | The adapter queued/wrote the prompt, without a provider admission receipt |
+| `accepted` | Provider-confirmed admission or matching provider output establishes that this submission/turn is being processed; work is still pending |
+| `completed` | An authoritative matching main-turn result reports success; HCC acknowledges the message and can write an automatic reply for a non-reply message |
+| `failed` | A definitive rejection or unsuccessful main-turn result; not a successful acknowledgement |
+| `uncertain` | A timeout, lost process/connection, or runtime restart left the outcome unknown; automatic retry could duplicate work |
+
+An SDK consuming an input iterator proves transport submission, not provider
+acceptance or a completed model turn. Claude advances from `submitted` to
+`accepted` after matching assistant output is observed. Claude reports its
+actual session ID on initialization, so a freshly
+opened worker can legitimately have a null session ID until its first prompt.
+An interrupt request does not cancel an SDK input that is still queued and does
+not itself complete a delivery. Only a matching main-turn result settles it.
+
+An inbox message with `kind: 'reply'` is still delivered as context and
+acknowledged after its main turn succeeds. Its output remains in `events`, but
+HCC does not automatically generate another reply, preventing reply loops.
+For other message kinds, a successful main turn with output writes an automatic
+reply to the sender.
+
+For an uncertain delivery, inspect `deliveries`, `events`, and provider state
+before sending a replacement. HCC leaves uncertain deliveries out of automatic
+retries. Runtime restart records in-flight work as uncertain rather than
+pretending it failed or completed.
+
+## Ownership, hooks, and permissions
+
+Resume an HCC-owned saved session with the same peer and provider:
+
+```sh
+hcc native close --peer codex-reviewer
+hcc native start --peer codex-reviewer --provider codex --resume last
+```
+
+An explicit saved ID is accepted only when it matches HCC's record for that peer
+and provider. Resume restores a conversation through a newly owned connection;
+it does not attach to an existing live TUI or desktop instance. HCC cannot prove
+that an external application has independently opened the same saved session,
+so do not open the same conversation concurrently outside the owned runtime.
+
+Native workers receive a worker-specific `HCC_ROOT`, `HCC_DB`, `HCC_PEER`, and
+`HCC_NATIVE_OWNER`. A provider hook must match the peer's native transport owner.
+Its native hook path only heartbeats that owner and renews its locks. It does
+not change provider bindings or process identity, inject another copy of the
+inbox, acknowledge messages, or block a Stop hook. Mismatched owner markers fail
+without falling back to normal terminal-hook delivery.
+
+Providers keep their permission checks. HCC-hosted workers wait for an explicit
+response from the current Web controller or the local CLI when an operation
+requires approval. Closing Web leaves both the worker and its pending requests
+available to the local CLI. Requests expire when their turn ends, interruption
+is accepted, the provider resolves them, or the worker closes. A late request
+from an interrupted turn cannot reopen approval. Direct adapters without a
+hosted responder retain conservative denial.
+
+| Provider | Hosted interaction |
+| --- | --- |
+| Codex | Command/file approval, requested filesystem/network permission subsets with explicit turn/session duration, questions including freeform/secret input, and one-call empty-form MCP tool approvals |
+| Claude | SDK tool permission callback; approval grants the original tool input once without rewriting it |
+| dsh ACP | Offered permission choices; approval selects only `allow_once`, never `allow_always` |
+
+rc.2 may send only a tool-call ID in an ACP approval request. The adapter correlates same-session/turn tool updates to show the operation input. Missing or truncated input still allows rejection; acceptance returns `NATIVE_APPROVAL_CONTEXT_MISSING`. See dsh installed acceptance (source checkout: `docs/verification/2026-10-02-dsh-cordis-native.md`).
+
+Hosted interactive Codex threads explicitly enable
+`features.default_mode_request_user_input` and `features.request_permissions_tool`
+in their private start/resume configuration. Web-owned start/resume/fork uses
+the same switches. These experimental capabilities were exercised in Codex
+0.144.6; they do not write global configuration or grant filesystem/network
+permissions. Approval remains on-request with the user as reviewer.
+Noninteractive direct adapters retain their defaults. The permission form
+shows mirrored legacy and current path entries once, preserving distinct
+access choices, original request indices and denial rules.
+
+Claude keeps `permissionMode: 'default'`; tools already permitted by that mode
+can run. Approval responses are fenced by the runtime generation, worker owner,
+provider, session, turn and request ID. Web observers cannot submit responses;
+a browser that loses control cannot answer with its old control epoch. Direct
+answers, including secrets, are omitted from HCC snapshots, events, delivery
+receipts and browser storage; form drafts remain in browser memory only.
+
+For Codex permissions/questions, use a response file. These are separate
+examples; paths, question IDs and answer labels must match the pending request:
+
+```json
+{"permissions":{"fileSystem":{"read":["/requested/read/path"]}},"scope":"turn"}
+```
+
+```json
+{"answers":{"question-id":{"answers":["An offered label or permitted freeform answer"]}}}
+```
+
+```sh
+hcc native respond --peer codex-reviewer --request REQUEST_ID --decision accept --response-file ./response.json
+hcc native respond --peer codex-reviewer --request REQUEST_ID --decision cancel
+```
+
+Only `permissions`, `scope` and `answers` are accepted in that file. Permissions
+can narrow the request but cannot add paths or network access; requested deny
+entries must be retained when granting filesystem access. Answer every question
+explicitly. Truncated requests can only be declined or cancelled. Arbitrary MCP
+forms, URL authentication, dynamic tools and account-token refresh requests are
+outside this responder's supported interaction set.
+
+## Current boundaries
+
+- Existing Codex/Claude/dsh terminal sessions remain on their original transport;
+  attaching to or taking over an existing TUI/Desktop session is not implemented.
+- Web discovers existing native workers in the same project and exposes messages,
+  delivery receipts, interruption, and explicit closure. Closing the page or Web
+  runtime preserves the independent native worker. Human responses are bound to
+  the current executor and turn. See the [Web handoff guide](web-handoff.zh-CN.md).
+- Codex, Claude and dsh native workers receive project- and peer-scoped HCC MCP
+  configuration. Writes still require provider permission and HCC ownership checks.
+- Provider-internal `SendMessage`, subagent/team discovery, and Codex delegation
+  tools are not exposed as one cross-vendor protocol. HCC routes cross-provider
+  messages through its own durable bus and adapters.
+- Task claiming, file locks, handoffs, and completion checks remain explicit HCC
+  coordination operations; successful prompt execution alone does not prove a
+  task's business acceptance.
+- Adapter tests cover protocol and interaction boundaries. The authenticated
+  checks below provide separate evidence for model execution and scoped MCP;
+  packaged-client installation and business acceptance remain unverified.
+
+
+## Authenticated acceptance on October 2, 2026
+
+Independent temporary projects and provider state directories were used for real
+model calls with Codex 0.144.6, Claude Agent SDK 0.3.287 and DSH 0.2.0-rc.2. The
+session lifecycle receipt (source checkout: `docs/verification/2026-10-02-native-live-lifecycle.json`)
+covers correlated replies and ACKs, idempotent queueing, continuing context,
+owned close/resume and active interruption. A real Codex command approval was
+declined, and its test write outside the allowed sandbox did not occur.
+
+The cross-provider receipt (source checkout: `docs/verification/2026-10-02-native-live-communication.json`)
+covers actual model calls to the scoped HCC MCP message tool along
+`Codex → Claude → dsh → Codex`, receiver model replies, reply consumption and ACK,
+and the absence of automatic reply loops. It also verifies discovery and sending
+through the Web bridge, original provider binding preservation and worker
+survival after closing that bridge. These receipts are separate source snapshots.
+
+Codex MCP tool approvals use `mcpServer/elicitation/request`. HCC submits the
+official action/content response for explicit tool confirmations without
+persisting session/always authorization. Approving arbitrary form fields or URL
+authentication is unsupported; decline and cancel remain available.
+
+The local validation receipt (source checkout: `docs/verification/2026-10-02-native-live-validation.json`)
+records the unit suite (785 passed, one platform-dependent skip), a 63-module
+static audit, the 13-stage regression and offline harness failure cleanup.
+Each check retains its own execution time and evidence digest.
+
+The opt-in `scripts/native-live-acceptance.mjs` harness defaults to help. It calls
+models and consumes the caller's provider quota only with `--run-live`:
+
+```sh
+node scripts/native-live-acceptance.mjs --run-live --provider all \
+  --codex-bin /absolute/path/to/codex \
+  --dsh-bin /absolute/path/to/dsh \
+  --claude-sdk /absolute/path/to/claude-agent-sdk/sdk.mjs \
+  --permission-probe --cross-provider \
+  --output /absolute/path/to/receipt.json
+```
+
+Use `--communication-only` for the cross-provider test alone. The explicit SDK
+entry was used for Claude acceptance; this does not prove repository-default SDK
+resolution or package installation. The script installs no dependencies, never
+attaches to existing conversations, and closes owned test processes and removes
+credential copies on exit. Web evidence covers its service/bridge control layer,
+not a full browser interaction or published-client acceptance. Real business task
+acceptance remains a separate check.
+
+
+For real model and browser interactions, use
+`scripts/web-native-interaction-acceptance.mjs`. It defaults to help; only
+`--run-live --provider codex|claude|all` invokes models. Set
+`HCC_ACCEPTANCE_PLAYWRIGHT` and optionally `HCC_ACCEPTANCE_CHROME`.
+`--claude-package DIR` links an installed SDK package into the isolated worker
+project for default resolution, without injecting its query function. The
+harness checks explicit approval and rejection and continuing the original
+session. It uses existing authentication/quota, cleans test provider homes and
+processes, and never attaches to existing user conversations.