@logicseek/hello-cc 1.0.5 → 1.1.0-rc.3

package/docs/native.zh-CN.md

@@ -48,6 +48,38 @@ npm install --no-save --package-lock=false @anthropic-ai/claude-agent-sdk@0.3.28
 已有独立回执 (源码目录: `docs/verification/2026-10-02-native-web-claude-default-sdk.json`)，不代表
 发布包或员工设备已完成安装验收。
 
+## 从 Web 新建
+
+运行 `hcc web`，选择项目，再点击“新建 Agent”。Codex、Claude 和 DeepSeek Harness
+默认使用“后台 Agent”，创建 native worker 并按需启动或复用该项目的独立 native
+runtime。无需先运行 `hcc native start`；上述 provider 安装和认证要求仍然适用。
+
+顶部“设置”可保存项目默认 provider，以及各 provider 的默认模型和项目内工作目录。
+新建表单会预填这些值；未设置工作目录时使用项目根目录。worker 继续共享所选项目的
+HCC 任务和消息总线。要在根目录之外工作，先选择或添加相应项目。“模型（可选）”
+留空时使用 provider 当前配置，填写时需使用该 provider 支持的模型值；“名称（可选）”
+留空时自动生成 peer 名称。
+
+这些默认值只用于后续 Web 新建 native worker，不改变既有 worker、恢复或 CLI 启动。
+配置由项目数据库保存，跨浏览器读取；并发保存发生冲突时需重新载入核对。详情见
+[项目启动默认值](web-handoff.zh-CN.md#项目-agent-启动默认值)。
+
+“新建 Agent”创建新 native 会话；项目栏“历史”中的“HCC 保留历史”可查看已保存的
+worker，并显式恢复已关闭的 worker。恢复保留原 peer 和 provider 会话 ID，重新核对
+所有权后启动新执行器。CLI resume 继续可用。“高级选项”保留终端 CLI、Codex App
+Server 及各自原有的历史恢复操作。Shell 使用终端，DeepSeek Harness 使用后台 worker。
+
+创建后在同一 Web 会话内发送提示、查看投递回执或处理审批。创建 worker 不代表模型
+任务已经完成。关闭页面或停止 Web 都保留独立 native runtime 和 worker；不再需要时
+明确关闭 worker。下方带日期的既有验收记录不代表这个新建入口已通过真实模型或发布
+验收。详细操作见 [Web 指南](web-handoff.zh-CN.md)。
+
+顶部“文件”可浏览项目文件与生成产物，也可显式上传新文件（最大 10 MiB）或编辑完整
+UTF-8 文本（最大 1 MiB），无需创建 worker。同名上传不覆盖，文本保存会检查版本；
+冲突或回执不确定时保留草稿。这些操作不会把文件发送给模型。详情见
+[文件与产物预览](web-handoff.zh-CN.md#浏览文件与产物)及
+[上传与编辑](web-handoff.zh-CN.md#上传与编辑项目文件)。
+
 ## CLI 使用
 
 在需要共享状态的项目目录中运行，或使用已有全局 `--root`、`--db` 指定项目和数据库。
@@ -80,7 +112,7 @@ hcc msg inbox --peer coordinator
 | `hcc native deliveries` | 可选 `--peer NAME`，查看投递回执 |
 | `hcc native events` | 必须 `--peer NAME`；可选 `--after ID`，查看有界事件历史 |
 | `hcc native requests` | 必须 `--peer NAME`；查看与该执行器、会话、turn 绑定的待处理请求 |
-| `hcc native respond` | 必须 `--peer NAME --request ID --decision accept\|decline\|cancel`；权限子集或问题答案通过 `--response-file JSON` 提交 |
+| `hcc native respond` | 必须 `--peer NAME --request ID --decision accept\|decline\|cancel`；权限子集、问题答案或 MCP 表单内容通过 `--response-file JSON` 提交 |
 | `hcc native interrupt` | 必须 `--peer NAME`；可选 `--turn ID`，请求中断活动 turn |
 | `hcc native close` | 必须 `--peer NAME`，关闭该 worker 持有的连接或进程 |
 | `hcc native down` | 请求关闭 worker 和停止 runtime，返回停止请求回执 |
@@ -135,6 +167,11 @@ hcc native start --peer codex-reviewer --provider codex --resume last
 的连接恢复会话历史，不是附着已有的活动 TUI 或桌面实例。HCC 无法证明外部应用
 没有独立打开同一个保存会话，因此不要同时在 owned runtime 外写入该会话。
 
+新保存的 worker 还记录工作目录的文件系统身份；即使路径文字未变，恢复前也必须
+重新匹配该身份。缺少此证据的旧 worker 仍可在 HCC 历史中读取，但不能自动恢复；
+人工核验与关联流程尚未实现。Web 历史会先标为不可恢复，native 服务在实际接纳时
+再次校验。
+
 worker 获得明确的 `HCC_ROOT`、`HCC_DB`、`HCC_PEER`、`HCC_NATIVE_OWNER`。provider hook
 必须匹配该 peer 的 native transport owner。native hook 路径只刷新 owner 心跳和续
 期其锁，不覆盖 provider binding 或进程身份、不再次注入 inbox、不 ACK 消息，也
@@ -147,12 +184,16 @@ ID。观察窗口不能应答，控制权切换后旧窗口的 epoch 失效。
 
 | Provider | 已接入的人工交互 |
 | --- | --- |
-| Codex | 命令/文件审批、所请求文件与网络权限的子集、明确的 turn/session 有效期、选项/自由输入/敏感问题，以及单次空表单 MCP 工具确认 |
+| Codex | 命令/文件审批、所请求文件与网络权限的子集、明确的 turn/session 有效期、选项/自由输入/敏感问题，以及单次空表单 MCP 工具确认与常用 MCP 表单字段 |
 | Claude | SDK 工具权限 callback，批准原始输入本次执行，不改写工具参数 |
 | dsh ACP | 选择 provider 提供的 `allow_once`，不自动选择 `allow_always` |
 
 rc.2 的 ACP 审批可能只携带工具 ID。适配器会关联同一 session/turn 的工具更新以展示操作输入；等待后仍缺输入或输入被截断时可以拒绝，允许会返回 `NATIVE_APPROVAL_CONTEXT_MISSING`。实际安装与拒绝证明见 dsh 验收 (源码目录: `docs/verification/2026-10-02-dsh-cordis-native.md`)。
 
+Native 审批卡片先显示工具、命令或文件路径和内容预览，并明确本次授权范围。
+完整操作详情可以展开，状态刷新保留展开状态；ACP 缺少操作输入或单次批准选项
+时禁用批准按钮，仍可拒绝。长内容预览会明确提示缩短，完整参数继续可查看。
+
 Codex 交互会话在 thread start/resume 的私有配置中显式开启
 `features.default_mode_request_user_input` 和 `features.request_permissions_tool`，
 使执行模式下的模型能够调用提问和权限请求工具。Web 专用 App Server 的 start、resume、
@@ -184,19 +225,34 @@ hcc native respond --peer codex-reviewer --request REQUEST_ID --decision accept
 hcc native respond --peer codex-reviewer --request REQUEST_ID --decision cancel
 ```
 
-响应文件只允许 `permissions`、`scope`、`answers`。不能添加原请求没有的路径或
+响应文件只允许 `permissions`、`scope`、`answers`、`content`；MCP 表单用 `content` 对象提交原字段名和类型，例如 `{"content":{"project":"demo","count":2,"enabled":false}}`。不能添加原请求没有的路径或
 网络权限；授予文件权限时必须保留原请求的 deny 条目。所有问题都需明确回答；
 请求参数被截断时，只能拒绝或取消。动态工具与账号 token 刷新尚未接入。
 
 Codex MCP 工具审批使用 `mcpServer/elicitation/request`，与命令/文件审批的返回结构
 不同。HCC 对显式 MCP 工具确认提交单次 action/content，不写入 session/always 授权。
-任意表单字段和 URL 身份认证尚不支持批准，可明确拒绝或取消。
+标准 `form` 模式支持字符串、数值/整数、布尔值、单选和字符串枚举多选，包含标题、说明、默认建议值、必填项、长度/数值/选择数量范围及常用邮箱/URI/date/date-time 格式校验。可选字段只在勾选填写后发送；布尔值需明确选择是或否。字段数量上限 50、单字段选项上限 100、字符串上限 8192 个 UTF-16 单元，表单结构与应答内容各限 65536 字符。
+
+Web 刷新执行状态时在页面内存中保留填写内容；提交、请求消失或切换会话后清除，不写入浏览器存储、HCC 事件或投递回执。页面整体重载不会恢复这些答复。此约束针对 HCC 的交互应答路径；provider 自身记录及模型输出继续按其原有行为处理。服务端重复校验内容，审批继续绑定原 executor/session/turn/request；错误输入保留请求供修正。嵌套对象、任意数组、未知约束和 OpenAI 扩展表单模式仍不可批准，页面显示原因并提供拒绝/取消。此能力未改变动态工具或 token 刷新的接入边界。
+
+带原 thread/turn 标识的 MCP `url` 请求现在可在 Web 打开授权页面。界面显示 MCP 服务和目标域名，当前控制者明确点击后先保留空白标签页；原执行器接受同一个请求后才跳转，过期或被拒绝的请求会关闭空白页。弹窗被拦截时保留待处理请求，允许弹窗后可重试。仅允许 HTTPS 或 loopback HTTP，拒绝带用户名/密码的 URL、其他协议、缺少 elicitation 标识或被截断的请求；拒绝/取消始终可用。新标签页不保留 opener 或 referrer。loopback 地址需在执行器所在电脑的浏览器访问，HCC 不把本地授权回调代理到另一台设备。
+
+打开只回传 `{ "action": "accept" }`，不代表身份认证完成。需在外部页面完成操作，再返回查看原任务的 provider 结果。HCC 不推测授权完成事件，也不在表单中收集凭证；授权 URL、设备码消息、elicitation 标识和元数据仅存在于实时待处理请求，不留在 HCC 交互事件或浏览器存储中。provider 自身日志/历史和外部授权浏览器仍按各自规则处理。账号登录、token 刷新、`openai/userVerification` 与外部授权完成 API 属于独立的未接入能力。
+
+浏览器复现：设置 `HCC_ACCEPTANCE_PLAYWRIGHT` 指向 Playwright 模块，再执行 `node scripts/web-mcp-form-acceptance.mjs --run-browser`；`HCC_ACCEPTANCE_CHROME` 可指定 Chrome 路径。该脚本用模拟 provider、真实 HTTP/SQLite/native runtime 和隔离浏览器，不调用模型。表单验收见 `docs/verification/2026-10-02-mcp-form-web-validation.md`。
+
+真实模型与浏览器验收使用 `node scripts/web-mcp-form-live-acceptance.mjs --run-live`，同样需要设置 `HCC_ACCEPTANCE_PLAYWRIGHT`，可选 `HCC_ACCEPTANCE_CHROME`、`HCC_ACCEPTANCE_TMUX`、`--codex-bin PATH` 与 `--output NEW_FILE`。默认只打印帮助；显式运行会使用当前模型和账号的额度。脚本让安装版 Codex 调用隔离 stdio MCP 工具，通过实际 Web 操作完成工具确认、字段填写和提交，核对原类型答复、模型文件落盘，以及 Web 关闭后原 native 执行器继续执行；另覆盖 Web-owned App Server 路径，没有注入模型输出或 App Server 请求。
+
+此验收分别隔离 HCC 的用户目录、Codex home、项目、tmux socket 和浏览器 profile。已配置的外部认证辅助程序可在原用户目录下只读运行，以保持当前账号的正常凭据获取；不更改原 provider、模型、登录状态或原配置。回执记录源码摘要、实际检查、清理结果及原配置/认证/shell 配置摘要核对，`--output` 必须使用新路径，既有回执不会覆盖。验收工具日志只包含合成表单值，直接答复不应被误当成真实业务数据。
+
 
 ## 当前边界
 
 - 尚未实现接管或 attach 已有 Codex/Claude/dsh TUI、桌面会话；这些会话继续使用原
   transport。
-- Web 可发现并控制同一项目的现有 native worker，提供消息、回执、中断和明确关闭。
+- Web 可新建 Codex、Claude、dsh native worker，也可发现并控制同一项目的现有 worker，
+  提供消息、回执、中断和明确关闭。“历史”提供 HCC 保留事件与已关闭 worker 的显式恢复；
+  记录不是 provider 完整历史，活跃或停止未确认的 worker 不可从此入口恢复。
   关闭页面或 Web runtime 保留独立 native worker；支持与当前执行器、turn 绑定的人工应答。
   使用方式见 [Web 继续本地任务](web-handoff.zh-CN.md#本地-native-worker-接手)。
 - Codex、Claude 和 dsh native worker 自动获得项目与 peer 受限的 HCC MCP；
@@ -246,8 +302,82 @@ Web 验证覆盖服务与 bridge 控制接口，尚不等于完整浏览器操
 
 
 真实模型与浏览器人工交互可使用 `scripts/web-native-interaction-acceptance.mjs`。
-默认只显示帮助；`--run-live --provider codex|claude|all` 才调用模型。
+默认只显示帮助；`--run-live --provider codex|claude|dsh|all` 才调用模型。
 设置 `HCC_ACCEPTANCE_PLAYWRIGHT`，以及按需设置 `HCC_ACCEPTANCE_CHROME`。
 `--claude-package DIR` 可将已经安装的 SDK 包链接到隔离 worker 项目，由默认加载器
 解析，不注入 query 函数。脚本验证明确批准与拒绝、原会话续接，退出后关闭测试
 进程并清理临时 provider home；使用现有认证和调用额度。它不连接现有用户会话。
+
+`--provider dsh --dsh-bin /absolute/path/to/dsh` 使用已安装的公开 launcher 和现有
+`DEEPSEEK_API_KEY`。脚本在私有 ACP profile 中通过公开 `tools/pre-execute` 策略
+让两个指定验收文件的写入请求审批；审批请求来自真实模型工具调用，不注入 ACP 请求。
+验证批准后写入、拒绝后文件不存在、释放 Web 控制后原 session 本地续接，另检查
+桌面和 390px 手机审批卡片。真实结果见 dsh Web 交互回执 (源码目录: `docs/verification/2026-10-02-native-web-dsh-final-snapshot-interactions.json`)。
+
+
+## 安装包验收
+
+`scripts/native-installed-acceptance.mjs` 对已经安装的 HCC 包执行验收，通过公开
+`hcc native` 命令启动 daemon 和三个 provider。先把本地包与可选的 Claude SDK
+安装在同一个独立 npm prefix；脚本使用 SDK 默认包解析，不注入 adapter 或 query
+函数。不加 `--run-live` 只显示帮助，不调用模型。
+
+```sh
+npm install --prefix /absolute/path/to/acceptance-prefix \
+  /absolute/path/to/hello-cc.tgz @anthropic-ai/claude-agent-sdk
+
+HCC_ACCEPTANCE_PLAYWRIGHT=file:///absolute/path/to/playwright/index.mjs \
+HCC_ACCEPTANCE_CHROME=/absolute/path/to/chrome \
+node /absolute/path/to/acceptance-prefix/node_modules/@logicseek/hello-cc/scripts/native-installed-acceptance.mjs \
+  --run-live --codex-bin /absolute/path/to/codex \
+  --dsh-bin /absolute/path/to/dsh --archive /absolute/path/to/hello-cc.tgz \
+  --browser --task --output /absolute/path/to/receipt.json
+```
+
+验收覆盖三个已安装 provider 的关联回复与 ACK、重复提交、连续上下文、owned
+close/resume、中断，以及一次明确拒绝 Codex 越界写入审批。先通过人工控制入口给每个 worker 授权限定任务，再由模型通过 MCP 沿
+`Codex → Claude → dsh → Codex` 发消息并消费回复。浏览器检查 SDK 默认加载、
+明确批准文件写入、桌面和手机渲染、释放控制权，以及关闭 Web 后原会话本地续接。
+`--task` 增加独立文件协作样例：Codex 实现金额计算，通过五个合同测试，再通过
+模型发出的交接消息让 Claude 写出审查文件。这个样例与生产业务的用户验收分开。
+
+脚本使用现有认证和调用额度。HCC 全局 HOME、provider home、tmux server 和项目
+使用私有验收目录；复制到私有配置中的 Codex 凭据命令，仅在读取现有凭据时保留
+原 HOME，原配置保持不变。退出后清理自有进程与临时凭据。回执记录包 SHA-256、
+provider 版本、源码摘要、浏览器证据和清理结果；脚本不会发布 npm 包或部署到
+员工设备。
+
+通过已认证的 native CLI/Web 控制入口提交的任务，持久记录为人工请求；共享 HCC
+消息总线送达的内容保持 peer 消息身份，即使发送方自称 `web` 或 `shell`。旧回执
+迁移后仍按 peer 消息处理。来源区分不授予工具权限，写入等受控操作仍需审批。
+委派文件任务时，先由用户明确授权接收 agent 的限定任务，再发送 peer 交接。
+
+## 有界稳定性验收
+
+安装包验收可加 `--stability`，在基础生命周期和跨 provider 通信之后运行持续负载：
+
+```sh
+node /absolute/path/to/acceptance-prefix/node_modules/@logicseek/hello-cc/scripts/native-installed-acceptance.mjs \
+  --run-live --codex-bin /absolute/path/to/codex --dsh-bin /absolute/path/to/dsh \
+  --archive /absolute/path/to/hello-cc.tgz --stability \
+  --stability-cycles 6 --stability-burst 2 --stability-idle-ms 30000 \
+  --stability-resume-every 2 --output /absolute/path/to/stability-receipt.json
+```
+
+三个 provider 同时工作，每轮先向各 worker 排队投递整组消息。每条要求模型从
+历史中回忆原始随机标记和上一条消息的票据，验证串行处理顺序与上下文保留。
+每轮还重复提交同一提交 ID，核对只产生一条回复与一个 ACK；定期关闭并恢复
+worker，在中点正常重启自有 daemon，再验证原 session 和历史。空闲窗口继续
+检查控制接口、pending 请求与会话身份。结束时核对持久投递、数据库完整性、
+事件保留上限与无回复循环。回执保留每条实际回复、失败状态和自有进程内存
+采样，不自动重放失败任务，也不把同轮重新尝试改写为成功。
+
+默认 6 轮、每 worker 每轮 2 条、每轮空闲观察 30 秒、每 2 轮恢复。参数限制为
+1–24 轮、1–4 条、0–300000 毫秒和 1–24 轮恢复间隔；这些选项必须与
+`--stability` 一起使用。这是有界真实模型负载验收，不能代替 24 小时 soak、
+并发容量测量或内存泄漏证明。DSH 单次恢复成功也不能单独解释历史恢复波动。
+
+`--stability-only` 与 `--stability` 一起使用时，只建立三个真实会话并运行稳定性
+负载，跳过基础中断、命令审批和模型 MCP 通信场景；回执明确标记该范围。
+适合已有独立生命周期/交互回执时单独补做持续负载，不能把跳过项算作通过。
+发生任一错误时，脚本在关闭自有 worker 前保存会话快照、最近投递和事件。

package/docs/web-handoff.zh-CN.md

@@ -1,6 +1,92 @@
-# Web 继续本地任务
+# Web 新建 Agent、项目文件与继续本地任务
 
-项目仍以 CLI/tmux 作为默认接入。它适合继续已经托管的本地 Codex/Claude/shell：Web 打开同一个 pane，不另起执行器。
+Web 可以直接新建 Codex、Claude 或 DeepSeek Harness 后台 Agent，也可以继续同一项目中已有的 native worker 或受管终端。
+
+## 浏览文件与产物
+
+选择项目后，点击顶部“文件”，即可浏览项目目录并打开已保存的文件，无需先创建 Agent。
+支持逐层进入目录、返回上级、输入项目相对目录和刷新。会话中“引用与执行器能力”的文件
+检索结果也可以直接打开预览；“引用文件”仍然只在消息草稿里加入路径标记。
+
+| 文件类型 | 预览方式 |
+| --- | --- |
+| 文本、源代码 | 显示转义后的原文 |
+| Markdown | 显示基本排版与代码块，可切回源码 |
+| HTML | 隔离的静态预览，可切回源码；脚本、表单、导航和外部资源不运行 |
+| PNG、JPEG、GIF、WebP | 图片预览 |
+| PDF | 浏览器内置查看器；未支持内嵌显示时可下载查看 |
+| SVG | 仅显示源码 |
+| 其他二进制文件 | 提示暂不支持预览，不尝试按文本显示 |
+
+预览只读取当前项目内的普通文件，不修改文件，也不会把内容上传给模型。
+`dist`、`build` 等产物目录可以浏览；运行状态、依赖缓存及已知凭据路径不提供预览，
+符号链接和硬链接也不读取。目录每次最多显示 500 项，并提示未完整列出的情况；
+文本超过 1 MiB 时只显示前部并标记截断，截断 HTML 只显示源码。图片和 PDF 最大为
+10 MiB，超过限制会明确提示。文件在读取期间变化时，请刷新后重试。
+
+切换文件、切换项目或关闭预览会使旧请求失效。手机可在目录与预览之间返回切换；
+分屏辅助窗口的文件入口会在同一项目的主窗口中打开。静态预览不会启动生成网页所需的
+开发服务器。
+
+## 上传与编辑项目文件
+
+在“文件”中进入目标目录，选择一个本机文件并核对目标文件名，再点击上传。文件会保存到
+运行 HCC 的机器上当前项目的这个目录，单文件最大 10 MiB；不自动创建目录，不覆盖同名
+文件。上传不是聊天附件发送，不会自动让 Agent 读取文件。要在任务中引用文件，仍需在
+消息中明确引用项目路径。
+
+完整的 UTF-8 文本、源码、Markdown 和 HTML 可以切换到编辑模式，修改后显式保存。
+编辑上限为 1 MiB，截断预览和二进制文件不能在线编辑。UTF-8 BOM 与原有 CRLF 换行会
+保留；混合换行文件会提示保存时统一为 LF。没有编辑过的文本不能重复保存。
+保存前核对读取时的文件版本；
+另一窗口或本地程序已修改文件时，保留草稿并显示冲突，核对磁盘内容后再决定如何处理。
+HCC 的同文件写入会串行化；本地编辑器等其他程序不共享这个锁，因此这不是对任意外部
+写入的系统级原子版本交换。保存通过同目录临时文件替换，避免向读者暴露半写的文本。
+
+切换文件、项目或关闭文件窗口会保留当前页面内的编辑草稿；刷新或关闭整个页面仍可能
+丢失未保存内容。“返回预览”保留草稿，“放弃草稿并重载”会先确认再丢弃。
+遇到断线或写入回执不确定时，使用“读取已保存文件”核对文本，或“核对目标文件”比较
+上传文件的大小和内容哈希；不会自动重发保存或上传。上传回执恢复只在浏览器保存项目
+身份、路径、大小和哈希，不保存上传文件内容。
+
+上传、编辑与预览沿用相同的项目路径限制，不允许修改运行状态、依赖缓存、已知凭据路径、
+符号链接或硬链接。写入固定到经验证的目标父目录身份，不会跟随被替换的项目路径去写
+另一个目录；如果原目录在写入中被移动，需重新选择当前位置并核对写入结果。
+
+## 项目 Agent 启动默认值
+
+顶部“设置”中可保存当前项目的默认 Agent，以及 Codex、Claude、DeepSeek Harness
+各自的默认模型和工作目录。它们保存在所选项目的 HCC 数据库中，可供其他浏览器读取；
+语言、主题、密度和字号仍是当前浏览器的显示偏好。
+
+模型留空表示使用 provider 自身的当前配置；HCC 不会推测该配置中的模型，也不在保存时
+调用模型验证名称。工作目录保存为项目相对路径，`.` 表示项目根目录，其他值必须指向
+现有的项目内目录。新建时会再次检查目录，已经删除或移到项目外的目录不能用来启动。
+
+保存后，“新建 Agent”会预填相应 provider 的模型和目录，本次创建仍可修改。取消后再打开
+会保留尚未提交的草稿；默认值读取或重试不会覆盖已编辑的字段。成功创建后，下一次新建
+重新读取项目默认值。清空模型表示本次使用 provider 默认配置，可以覆盖已保存的项目模型。
+新值只用于后续 Web 新建 native worker；既有 worker、历史恢复、CLI 启动及高级终端/
+App Server 流程各自沿用原有配置。此处不管理 provider 登录、API key、端点、环境变量
+或全局配置文件。
+
+保存使用版本校验。其他窗口先保存后，当前窗口会显示冲突并保留输入，需重新载入并
+核对最新值；不会静默覆盖其他窗口的修改。“恢复初始值”先重置表单，保存后才生效。
+如果保存响应因断线而不确定，先重新读取配置核对结果。
+
+## 新建后台 Agent
+
+运行 `hcc web`，选择项目，再点击“新建 Agent”。选择 Codex、Claude 或 DeepSeek Harness 后，默认使用“后台 Agent”；无需预先运行 `hcc native start`。对应 CLI 或 Claude SDK 仍需已安装，身份认证沿用运行 hello-cc 的环境，Web 不代为安装或登录。
+
+工作目录使用该项目为此 provider 保存的默认值，未设置时为项目根目录，可改为项目内的子目录；worker 仍共享所选项目的任务、消息、锁和交接。需要在另一个项目工作时，先切换或添加该项目。模型预填项目中保存的默认值，也可在本次创建时修改或清空；留空使用 provider 当前配置，填写时应使用该 provider 支持的模型值。名称可留空自动生成。
+
+“新建 Agent”用于创建新的 native worker；恢复已关闭的 worker，请使用项目栏“历史”中的“HCC 保留历史”。既有 `hcc native start` 和 `--resume last` CLI 继续可用。创建后在同一 Web 会话内发送提示、查看回执和处理审批；创建成功不代表已经运行模型任务。关闭页面或停止 Web runtime 都不会停止独立的 native runtime/worker，需要明确执行关闭操作。
+
+“高级选项”保留终端 CLI、Codex 的结构化 App Server 及它们原有的恢复流程。Shell 使用终端，DeepSeek Harness 使用后台 Agent。以下交接说明分别适用于这些执行方式。
+
+## 继续已有终端
+
+CLI/tmux 适合继续已经托管的本地 Codex/Claude/shell：Web 打开同一个 pane，不另起执行器。
 
 运行 `hcc web` 后选择已有会话。选中项和未发送草稿按项目保存于当前浏览器；刷新会恢复原位置。第一个 Web 连接取得控制，其他窗口可观察，点击“接管浏览器控制”后才可写入。服务端检查控制 epoch，旧窗口不能继续输入、改变终端尺寸、修改该 peer 或处理审批。本地 tmux client 仍可直接输入，Web 会显示其连接状态。
 
@@ -10,13 +96,19 @@
 
 ## Codex 结构化界面
 
-新建会话时选择 Codex，再把“Codex 接入方式”切换为“结构化 App Server（显式启用）”。需要本地已安装且支持 App Server 的 `codex`，登录和模型环境来自启动 hello-cc 的进程。hello-cc 不自动登录、不更改信任配置、不探测未公开的 TUI 内部 endpoint。
+在“新建 Agent”中选择 Codex，展开“高级选项”并选择结构化 App Server。需要本地已安装且支持 App Server 的 `codex`，登录和模型环境来自启动 hello-cc 的进程。hello-cc 不自动登录、不更改信任配置、不探测未公开的 TUI 内部 endpoint。
 
 可先运行 `hcc doctor --codex --json` 查看只读诊断。它分别报告已安装版本、CLI help 声明的 App Server 启动参数、hooks 配置与项目中的 hook 调用记录；这些事实不等于完整 RPC 能力、hooks 已受信任、stdout 投递成功或模型已接收。版本/help 探测使用独立临时 HOME/CODEX_HOME 并清理，防止 Codex 启动文件触碰用户目录；hooks 配置仍从原路径只读检查。没有充分回执的状态显示 `unknown`，不会自动触发 hook 或修改 trust。普通 `hcc doctor` 仍只检查数据库。
 
+升级 Codex 前可运行 `npm run codex:protocol -- --codex-bin /absolute/path/to/codex --out /tmp/hcc-protocol-new`。输出目录必须不存在；工具使用隔离 HOME/CODEX_HOME 生成官方 TypeScript 和 JSON Schema，记录版本/文件指纹并检查交接所依赖的协议子集。不兼容时返回非零退出码，未接入请求单独列出；生成成功不代表真实模型或外部授权验收。安装包内也可直接运行 `node /absolute/path/to/hello-cc/scripts/codex-protocol.mjs`。详见 `docs/codex-protocol.md`。
+
 结构化界面提供消息、当前 turn 状态、追加指令、轮次中断、计划、差异和人工交互。命令/文件审批以及空表单 MCP 工具确认由当前控制窗口明确批准本次或拒绝。文件与网络权限可逐项勾选，并明确选择本轮或会话有效期；只能授予原请求的子集。问题支持选项、其他/自由输入和敏感答案，需逐题明确填写。接管控制本身不会批准工具。
 
-表单输入与焦点会跨状态刷新保留，直接答案不写入 HCC 状态、事件、回执或浏览器存储。原 turn 完成、中断成功、provider 解决请求或执行器关闭后，请求卡片失效；旧控制窗口不能用过期 epoch 应答。参数被截断时只能拒绝或取消。任意 MCP 表单字段、URL 登录、动态工具及账号 token 刷新尚未接入。
+表单输入与焦点会跨状态刷新保留，直接答案不写入 HCC 状态、事件、回执或浏览器存储。原 turn 完成、中断成功、provider 解决请求或执行器关闭后，请求卡片失效；旧控制窗口不能用过期 epoch 应答。参数被截断时只能拒绝或取消。MCP 支持下述标准表单和带原 thread/turn 标识的 URL 请求；嵌套对象、任意数组等复杂结构、动态工具及账号 token 刷新尚未接入。
+
+MCP URL 请求显示授权目标，当前控制窗口点击“打开授权页面”后，原执行器接受请求才跳转。弹窗被拦截时不提交请求；过期请求不会打开授权地址。仅允许 HTTPS 或 loopback HTTP，链接带用户名/密码、其他协议、请求标识缺失或参数截断时保留拒绝/取消入口。loopback 地址需在执行器所在电脑打开，其他设备无法通过 HCC 代理本地授权页。
+
+打开页面只表示同意发起外部流程，不表示认证成功。请在外部页面完成操作，再返回关注原任务结果；新页面不保留 opener/referrer。URL、设备码消息和元数据不进入 HCC 交互事件或浏览器存储，实时待处理请求仍可供控制窗口查看。账号登录、token 刷新和 OpenAI 用户验证扩展不包含在此能力内。
 
 运行中发消息使用 steer；空闲时开始新 turn。中断当前轮与终止执行器是不同操作。turn 完成不自动把 hcc task 标记为验收完成。
 
@@ -26,9 +118,13 @@
 
 关闭浏览器后 App Server 仍由 hello-cc runtime 管理；停止 runtime 会关闭它。新 runtime 不会自动重启 App Server 或重放未确认消息，可以从已保存 thread 显式恢复。
 
+MCP 标准表单可以直接在 Web 填写文本、数值、是/否和单选/多选；两种执行器共用校验，答复仍回到同一请求。状态刷新保留页面内的填写内容，可选项不自动发送默认值；页面重载会清空答复。未支持的模式或结构会说明原因，保留拒绝/取消入口。实现和验收范围见 `docs/verification/2026-10-02-mcp-form-web-validation.md`。
+
+真实模型复现脚本为 `scripts/web-mcp-form-live-acceptance.mjs --run-live`：先由本地 Codex 实际发起 MCP 交互，再从桌面/手机 Web 提交，核对同一 native 执行器继续完成和交回本地；另覆盖 Web-owned App Server。环境变量与隔离/账号范围见 `docs/native.zh-CN.md` 的真实模型与浏览器验收说明。成功以该次回执为准，默认运行只打印帮助，不调用模型。
+
 ## 本地 native worker 接手
 
-先用 `hcc native start --peer codex-worker --provider codex` 启动后台任务，再打开 Web 的同一项目。Web 自动发现实际仍由 native runtime 持有的 worker，显示其原 peer/session、事件和投递回执；发送、中断和明确关闭都通过原 runtime 执行，不新建 provider 子进程。Claude/dsh worker 也走这条路径，按实际能力显示中断操作。
+已有 worker 可以继续从 CLI 启动，例如 `hcc native start --peer codex-worker --provider codex`，再打开 Web 的同一项目；也可直接使用上方的新建入口。Web 自动发现实际仍由 native runtime 持有的 worker，显示其原 peer/session、事件和投递回执；接手已有 worker 后的发送、中断和明确关闭都通过原 runtime 执行，不另建 provider 子进程。Claude/dsh worker 也走这条路径，按实际能力显示中断操作。
 
 发送成功先显示队列回执；执行器接收、运行和完成分别使用实际投递状态。断线或不确定结果保留 submission ID，刷新不会重放消息。native runtime 重启或 worker 被替换时，旧 Web 视图及其控制凭证失效，重新发现当前 worker 后才能操作。
 
@@ -38,16 +134,30 @@
 
 ## 历史、协作工具与结果审阅
 
-项目栏“Codex 历史”可分页浏览当前项目已保存的 thread，读取上下文，再显式恢复或分叉。恢复仍要求旧执行器已确认停止；分叉生成新的 thread/peer，原任务 owner 不变。有正在托管的源会话时，分叉也必须取得该会话的浏览器控制。历史读取不会启动模型 turn。
+项目栏“历史”默认打开“HCC 保留历史”，可按 Codex、Claude、DeepSeek Harness 筛选当前项目的 native worker，查看已保留的 provider 事件与投递回执。native runtime 离线时仍可读取已保存记录；浏览历史不会启动 provider 或模型 turn。
+
+worker 列表最多显示最近 100 项，超过时提示截断。事件每页 100 条，可以前后翻页；投递回执显示该 worker 最新 100 条。当前存储只保留整个项目最近约 2,000 条 provider 事件；这不是 provider 的完整对话档案。历史中可能没有最初输入、早期已裁剪事件或尚未被 HCC 记录的输出。DSH ACP 恢复本身也不代表原始对话重放。
+
+恢复前先明确关闭原 worker，再选中历史项并确认。后端只接受已记录为 `closed`、原 peer/provider/session 与 owner 仍一致的记录；运行中、断连、失败或退出未确认的记录不能从此入口恢复。恢复沿用原 peer、provider 会话和工作目录，创建新的 native 执行器；不会重放已处理或投递状态不明的消息，尚未执行的队列消息会按现有 native 队列规则继续。provider 安装和账号要求仍然适用，DSH 还需实际 ACP runtime 声明 resume 能力。
+
+恢复请求只提交一次。断线或响应丢失后，页面保留原恢复记录，通过刷新查找同一 peer 的新执行器；不会自动重新恢复。浏览器刷新后也可继续检查结果。恢复成功仅表示执行器已接入，Claude SDK 的会话初始化仍可能等到第一条新提示后才确认。
+
+选择“Codex 已保存会话”，可分页浏览当前项目已保存的 thread，读取上下文，再显式恢复或分叉。恢复仍要求旧执行器已确认停止；分叉生成新的 thread/peer，原任务 owner 不变。有正在托管的源会话时，分叉也必须取得该会话的浏览器控制。历史读取不会启动模型 turn。
 
 Web 专用 Codex App Server，以及由 HCC 托管的 Codex/Claude/dsh native worker，自动接入 [项目与 peer 受限的 MCP 协作工具](mcp.zh-CN.md)。配置只传给对应执行器或 worker，不写全局 provider 配置；关闭 worker 前撤销其临时权限。模型可查询任务与 inbox、领取任务、发送消息、写 handoff、获取/释放自己的资源锁和记录本地证据；不替用户执行发布或业务验收。
 
-会话栏“结果审阅”汇总结构化 command 的退出码与输出、turn 差异、模型通过 MCP 提交的本地证据，以及人工添加的验收记录。命令退出成功仅说明该命令成功；人工填写“通过”必须附证据引用。界面分别展示本地验证、发布部署、业务验收，并注明记录来源。turn 完成、测试记录或人工验收均不自动改变 hcc task 状态。记录保存于项目数据库 events 中，`gc --history` 保留结果审计记录和最小提交去重凭据。
+会话栏“结果审阅”汇总结构化 command 的执行状态与退出码、是否有 turn 差异、模型通过 MCP 明确提交的本地证据，以及人工添加的验收记录。自动结果仅在实时观察到新 turn 开始后归属当前任务；缺失该事件时，不会从历史快照补认任务证据。自动结果在项目数据库 events 中只保存中性标题、状态、退出码和来源 ID，不保存命令、输出或差异正文；正文仍可在可用的执行器会话或 provider 历史中查看。命令退出成功仅说明该命令成功；人工填写“通过”必须附证据引用。界面分别展示本地验证、发布部署、业务验收，并注明记录来源。turn 完成、测试记录或人工验收均不自动改变 hcc task 状态。`gc --history` 保留结果审计记录和最小提交去重凭据。
+
+## Codex 账号与限额
+
+Web 专用 Codex 和原生 Codex worker 新增只读“账号与限额”面板，观察窗口也可刷新。它显示本执行器的登录/供应商认证状态、可获取的订阅窗口、重置时间和读取时间；缺失或不支持的配额保持未知，账号切换与执行器替换拒绝旧查询结果。此操作不新建任务或 turn，也不提供登录、退出或 token 管理。未登录时需在运行任务的电脑完成本地 Codex 登录。使用方式、接口身份和真实/模拟验收边界见 [账号与限额说明](codex-account.zh-CN.md)。
 
 ## 验收边界
 
+以下既有记录分别对应当时的执行器、交接和交互流程，不代表新增的统一“新建 Agent”、项目启动默认值、文件上传编辑、HCC 历史或 Web native 恢复入口已完成真实模型或发布验收。
+
 本地验证包含真实 SQLite/HTTP、模拟交互请求、隔离 tmux 与桌面/手机浏览器。安装版 Codex 0.144.6 的协议验收另行覆盖 initialize、thread/start/list、10 个 MCP 工具发现和实际 `hcc_state` 读回；此协议检查不调用模型，可用 `node scripts/web-handoff-installed-acceptance.mjs` 重现。
 
-真实模型验收已在隔离项目和 Codex home 中完成“本地 → Web → 本地”三段文件任务，全程保持原 Codex 进程和 thread；关闭 Web runtime 后仍可继续。可用 `scripts/web-native-model-acceptance.mjs` 在明确需要真实模型调用时重现。三种 provider 的真实生命周期、模型 MCP 发信、回复/ACK 和无回复循环另有独立回执。交互表单另有 11 项模拟 provider 浏览器检查。真实 Codex 已经完成“提问 → Web 答复 → 指定文件权限 → 本轮授权 → 写入所选答案 → 后续请求拒绝 → 本地继续”的验收；默认加载的 Claude SDK 已完成真实 Write 工具批准、拒绝和本地续接。dsh 的真实权限弹窗尚无本轮浏览器验收。完整结果与运行条件见 本地验收记录 (源码目录: `docs/verification/2026-10-02-web-local-task-handoff.md`)。
+真实模型验收已在隔离项目和 Codex home 中完成“本地 → Web → 本地”三段文件任务，全程保持原 Codex 进程和 thread；关闭 Web runtime 后仍可继续。可用 `scripts/web-native-model-acceptance.mjs` 在明确需要真实模型调用时重现。三种 provider 的真实生命周期、模型 MCP 发信、回复/ACK 和无回复循环另有独立回执。交互表单另有 11 项模拟 provider 浏览器检查。真实 Codex 已经完成“提问 → Web 答复 → 指定文件权限 → 本轮授权 → 写入所选答案 → 后续请求拒绝 → 本地继续”的验收；默认加载的 Claude SDK 已完成真实 Write 工具批准、拒绝和本地续接。dsh 已完成真实 ACP 写入的 Web 批准、拒绝和原 session 本地续接，审批卡片另通过桌面与 390px 手机检查；仅在隔离 profile 中对指定验收文件设置公开审批策略。完整结果与运行条件见 本地验收记录 (源码目录: `docs/verification/2026-10-02-web-local-task-handoff.md`)。
 
 任意未托管 TUI/普通终端的活动执行器迁移、私有 daemon endpoint、任意协议版本的完整兼容矩阵，以及发布安装和真实业务验收仍在本次证据范围之外。

package/lib/cli/app.mjs

@@ -90,6 +90,9 @@ import { assignTeamWorkers, expandTeamWorkers, inferTeamItems } from '../core/co
 import { autoPeerBasis, autoPeerKind, autoPeerProviderSession, autoPeerResumeId, autoPeerSessionId, readAncestorCliInfo, resolveCurrentPeer, resumeIdFromArgs, shortHash } from '../integrations/peers/identity.mjs';
 import { inspectProviderProcess } from '../integrations/peers/processes.mjs';
 import { registerProjectActivity } from '../runtime/projects.mjs';
+import { migrateLegacyProjectState } from '../runtime/state-migration.mjs';
+import { projectDbPath } from '../runtime/paths.mjs';
+import { ensureDshIntegration } from '../integrations/dsh.mjs';
 
 // Lazy-load lib modules (they may import node-pty which needs to be optional)
 const _libDir = path.resolve(fileURLToPath(import.meta.url), '..', '..');
@@ -505,8 +508,9 @@ function webErrorStatus(err) {
   if (!(err instanceof CliError)) return 500;
   if (err.code === 'REGISTRY_BUSY') return 503;
   if (err.code === 'CODEX_START_FAILED') return 503;
+  if (err.code === 'PROJECT_PATH_CHANGED') return 409;
   if (err.code.startsWith('CODEX_') || ['STALE_CONTROL_EPOCH', 'UNKNOWN_CONTROL_CLIENT'].includes(err.code)) return 409;
-  if (['BAD_ARGS', 'BAD_REQUEST', 'PEER_IDENTITY_REQUIRED', 'REQUEST_TOO_LARGE'].includes(err.code)) return 400;
+  if (['BAD_ARGS', 'BAD_REQUEST', 'PEER_IDENTITY_REQUIRED', 'REQUEST_TOO_LARGE', 'INTERACTION_RESPONSE_INVALID'].includes(err.code)) return 400;
   if (['PEER_IDENTITY_MISMATCH', 'TASK_OWNED', 'TASK_OWNER_MISMATCH', 'LOCK_OWNED', 'PROJECT_NOT_REGISTERED', 'PROJECT_PATH_FORBIDDEN', 'RUNTIME_ADMIN_REQUIRED'].includes(err.code)) return 403;
   if (err.code.startsWith('NATIVE_')) return err.code === 'NATIVE_RUNTIME_OFFLINE' ? 503 : 409;
   if (['NOT_FOUND'].includes(err.code)) return 404;
@@ -574,11 +578,49 @@ function formatHookEventName(hookType) {
 }
 
 function writeGuidance(ctx) {
-  return writeGuidanceForRoot(ctx.root);
+  return writeGuidanceForRoot(ctx.root, { expectedSnapshot: ctx.initialRootIdentity });
 }
 
-function removeGuidanceBlocks(ctx) {
-  return removeGuidanceBlocksForRoot(ctx.root);
+function removeGuidanceBlocks(ctx, options = {}) {
+  return removeGuidanceBlocksForRoot(ctx.root,
+    { expectedSnapshot: ctx.initialRootIdentity, ...options });
+}
+
+function cmdMigrateState(ctx, args) {
+  if (wantsHelp(args)) {
+    console.log(`${CLI_NAME} migrate-state --offline --yes\n\n` +
+      'Stop all old hello-cc Web, Native, PTY, tmux, hook and external database writers first. ' +
+      'This command verifies known process evidence, snapshots SQLite including WAL, and leaves the old directory untouched.');
+    return;
+  }
+  const opts = parseOpts(args, { booleans: ['offline', 'yes'] });
+  validateOpts('migrate-state', opts, ['offline', 'yes']);
+  if (opts.offline !== true || opts.yes !== true) {
+    throw new CliError('STATE_MIGRATION_OFFLINE_REQUIRED',
+      'Stop every old project-state writer, then acknowledge downtime with migrate-state --offline --yes');
+  }
+  const result = migrateLegacyProjectState(ctx.root, {
+    confirmedOffline: true,
+    // The operator's explicit --offline assertion covers external writers
+    // that cannot be discovered reliably across supported platforms. The
+    // migrator still checks known runtime, PTY and SQLite peer evidence.
+    assertOffline: () => true
+  });
+  let dshRebuilt = false;
+  if (result.dsh) {
+    try {
+      ensureDshIntegration({ ...ctx, dbPath: projectDbPath(ctx.root) }, { mode: result.dsh.mode });
+      dshRebuilt = true;
+    } catch (error) {
+      throw new CliError('STATE_MIGRATION_DSH_REBUILD_REQUIRED',
+        `Project state migrated to ${result.stateDir}, but DSH configuration needs rebuilding. ` +
+        `Run ${result.dsh.rebuildCommand}. Original data remains at ${result.sourceDir}.`,
+        { cause: error });
+    }
+  }
+  printResult(ctx, { ...result, dsh_rebuilt: dshRebuilt },
+    () => `project state migrated: ${result.stateDir}\nlegacy source kept: ${result.sourceDir}` +
+      (dshRebuilt ? '\nDSH integration rebuilt for the new private path' : ''));
 }
 
 // ─── hcc doctor ─────────────────────────────────────────────────────────────
@@ -593,6 +635,7 @@ async function dispatch(ctx, rest) {
   if (command === 'update') return cmdUpdate(ctx, args);
   if (command === 'uninstall') return cmdUninstall(ctx, args);
   if (command === 'init') return cmdInit(ctx, args);
+  if (command === 'migrate-state') return cmdMigrateState(ctx, args);
   if (command === 'register') return cmdRegister(ctx, args);
   if (command === 'join') return cmdJoin(ctx, args);
   if (command === 'env') return cmdEnv(ctx, args);

package/lib/cli/commands/coordination.mjs

@@ -163,8 +163,13 @@ export function createCoordinationCommands(deps) {
     const kind = opts.kind || 'ask';
     const runtime = opts.inject ? readRuntime(ctx) : null;
     const db = connect(ctx);
-    touchCurrentPeer(db, ctx, identity, null, 'shell');
-    const id = sendMessage(db, sender, recipient, taskId, kind, body);
+    let id;
+    try {
+      touchCurrentPeer(db, ctx, identity, null, 'shell');
+      id = sendMessage(db, sender, recipient, taskId, kind, body);
+    } finally {
+      db.close();
+    }
     let injected = false;
     if (opts.inject) {
       await injectPeer(ctx, recipient, body, !opts['no-enter'], runtime, sender);
@@ -184,8 +189,13 @@ export function createCoordinationCommands(deps) {
     const kind = opts.kind || 'broadcast';
     const runtime = opts.inject ? readRuntime(ctx) : null;
     const db = connect(ctx);
-    touchCurrentPeer(db, ctx, identity, null, 'shell');
-    const id = sendMessage(db, sender, 'all', taskId, kind, body);
+    let id;
+    try {
+      touchCurrentPeer(db, ctx, identity, null, 'shell');
+      id = sendMessage(db, sender, 'all', taskId, kind, body);
+    } finally {
+      db.close();
+    }
     let injected = 0;
     let skipped = 0;
     if (opts.inject) {

package/lib/cli/commands/dsh.mjs

@@ -14,7 +14,7 @@ function defaultHelp() {
     '       hcc dsh status [--dsh-bin PATH]',
     '       hcc dsh web [--mode hooks|cordis|off] [--dsh-bin PATH] [--dsh-home PATH] -- [dsh web arguments]',
     '',
-    'Setup writes project-local configuration under .hello-cc/dsh/. Modes: hooks (default), cordis (native tools), off.',
+    'Setup writes managed configuration under the selected private state directory. Modes: hooks (default), cordis (native tools), off.',
     'Web starts the official dsh web runtime; its real sessions join hello-cc through the selected integration.',
     'Pass runtime arguments after --, for example: hcc dsh web -- --port 8080',
     'Show dsh web help: hcc dsh web -- --help',

package/lib/cli/commands/gc.mjs

@@ -25,7 +25,8 @@ import {
 } from '../../core/coordination/gc-plan.mjs';
 import { runOptimisticEvidenceMutation } from '../../core/coordination/optimistic-evidence.mjs';
 import { peerEvidenceAllowsReap } from '../../core/peers/evidence.mjs';
-import { runtimePath, globalRuntimePath } from '../../runtime/paths.mjs';
+import { globalRuntimePath } from '../../runtime/paths.mjs';
+import { resolveProjectDatabase } from '../../runtime/project-path.mjs';
 import { readRuntime, reclaimRuntimePointerFiles } from '../../runtime/state.mjs';
 import { runtimeRequest, runtimeBufferGcUnavailable } from '../../runtime/client.mjs';
 import { collectBufferEvidence } from '../../runtime/buffer-evidence.mjs';
@@ -57,6 +58,10 @@ export function createGcCommands(deps) {
 // stale bufs) so automatic background gc bounds DB growth without deleting
 // user-meaningful history.
 // `db` is used open; the caller owns its lifecycle.
+function bufferDirectory(ctx) {
+  return path.join(resolveProjectDatabase({ root: ctx.root, createStateDir: false }).stateDir, BUFS_DIR_NAME);
+}
+
 function captureGcClockSubject(db, {
   bufferGcCutoffs,
   olderThanDays,
@@ -263,12 +268,16 @@ function captureRequiredBufferDirectoryComponent(component, description) {
 function captureOptionalBufferDirectory(root, directoryName) {
   const requestedRoot = path.resolve(root);
   const canonicalRoot = fs.realpathSync.native(requestedRoot);
-  const stateDirectory = path.join(canonicalRoot, '.hello-cc');
+  const stateDirectory = resolveProjectDatabase({ root: canonicalRoot, createStateDir: false }).stateDir;
   const directory = path.join(stateDirectory, directoryName);
   const components = [
-    captureRequiredBufferDirectoryComponent(canonicalRoot, 'Project root'),
-    captureRequiredBufferDirectoryComponent(stateDirectory, 'Project state directory')
+    captureRequiredBufferDirectoryComponent(canonicalRoot, 'Project root')
   ];
+  try {
+    components.push(captureRequiredBufferDirectoryComponent(stateDirectory, 'Project state directory'));
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+  }
 
   let stat;
   try {
@@ -623,10 +632,6 @@ function runGcWithHistorySnapshot(ctx, db, {
   return results;
 }
 
-function bufferDirectory(ctx) {
-  return path.resolve(path.join(ctx.root, '.hello-cc', BUFS_DIR_NAME));
-}
-
 function bufferDirectoryPaths(directory) {
   try {
     return fs.readdirSync(directory).map((name) => path.resolve(directory, name));
@@ -654,16 +659,16 @@ function localBufferEvidence(ctx, db, directory, unknownTracker = null, candidat
   });
 }
 
-function runtimePointerPresent(ctx) {
+function runtimePointerPresent(localPointer) {
   return Boolean(process.env.HCC_RUNTIME_URL ||
-    fs.existsSync(runtimePath(ctx)) ||
+    fs.existsSync(localPointer) ||
     fs.existsSync(globalRuntimePath()));
 }
 
-function reclaimUnavailableRuntimePointers(ctx, { dryRun = false } = {}) {
+function reclaimUnavailableRuntimePointers(localPointer, { dryRun = false } = {}) {
   if (process.env.HCC_RUNTIME_URL) return { allowed: false, gcCutoffs: [] };
   const gcCutoffs = [];
-  const result = reclaimRuntimePointerFiles([runtimePath(ctx), globalRuntimePath()], {
+  const result = reclaimRuntimePointerFiles([localPointer, globalRuntimePath()], {
     dryRun,
     onReclaim: ({ gcCutoff }) => {
       if (Number.isSafeInteger(gcCutoff)) gcCutoffs.push(gcCutoff);
@@ -713,15 +718,17 @@ function deferredPreparedBufferGc(prepared, graceActive = false) {
 }
 
 async function prepareManualBufferGc(ctx, db, { retentionSec, dryRun }) {
-  const directory = bufferDirectory(ctx);
+  const stateDir = resolveProjectDatabase({ root: ctx.root, createStateDir: false }).stateDir;
+  const directory = path.join(stateDir, BUFS_DIR_NAME);
+  const localPointer = path.join(stateDir, 'runtime.json');
   const unknownTracker = new Map();
   const pointerGcCutoffs = [];
   const recoverRuntimePointers = () => {
-    const recovery = reclaimUnavailableRuntimePointers(ctx, { dryRun });
+    const recovery = reclaimUnavailableRuntimePointers(localPointer, { dryRun });
     pointerGcCutoffs.push(...recovery.gcCutoffs);
     return recovery.allowed;
   };
-  const pointerPresent = runtimePointerPresent(ctx);
+  const pointerPresent = runtimePointerPresent(localPointer);
   let runtime = null;
   try { runtime = readRuntime(ctx); } catch (error) {
     if (pointerPresent && !recoverRuntimePointers()) {