@logicseek/hello-cc 1.1.0-rc.8 → 1.1.0

package/CHANGELOG.md

@@ -16,6 +16,113 @@ the release description from the current changelog section. Use
 `npm run release:github` with `GH_TOKEN` or `GITHUB_TOKEN` only for local
 backfills.
 
+## 1.1.0
+
+### Summary
+
+This stable release promotes the multi-provider Web workbench, native Agent
+coordination and project-identity protections developed through rc.9 to the
+npm `latest` channel. Its runtime code is unchanged from rc.9; the stable
+version has its own immutable package, tag and release acceptance receipts.
+
+### Highlights
+
+- Coordinate Codex, Claude and DeepSeek Harness sessions from the Web workbench
+  with project Agent defaults, structured conversations and tool/approval/user
+  input views. Retain terminal and App Server modes, guarded forks, retained
+  drafts, file previews, reconnect and snapshot-gap recovery.
+- Bind project state, managed launches, Web/native sessions and Codex history
+  to the selected directory's filesystem identity. Replacement directories
+  receive separate generations. Private-state v1 migration requires independent
+  root verification and an explicit offline drain; old stores remain preserved.
+- Ship authenticated directory-descriptor handoff helpers for Darwin and Linux
+  on arm64 and x64, with static Linux binaries, executable-mode and source-stamp
+  checks. Missing trusted helpers reject guarded launches without a pathname
+  fallback; operators can pause new launches with `HCC_PINNED_LAUNCH_MODE=hold`.
+- Fence Native, hook and scoped MCP mutations by current ownership, process and
+  runtime/state generations. Journal submissions before admission, recover
+  original IDs and avoid automatically replaying uncertain provider execution.
+- Add opt-in original-App cooperation adapters while retaining the App's own
+  execution. Harness idle-inbox wakeup and Claude hooks/plugins are separate
+  provider paths; a fully idle original Codex App is not automatically awakened.
+- Keep background terminal snapshots asynchronous and bounded, and retain
+  separate ACL cache entries for Number and BigInt stats. Preserve exact inode,
+  change-time and ACL checks, and bounded shim-registration diagnostics.
+
+### Validation
+
+The unchanged rc.9 runtime passed 1,992 local unit tests with three
+platform/privilege skips, all 13 regression stages and 45 browser checks per
+source/temporary installation. Its master CI passed 14 jobs and its immutable
+release/tag CI passed three jobs on their first attempts.
+
+The 1.1.0 version, frozen package, installed-provider checks and final commit/tag
+CI retain separate release receipts. Simulated-provider browser checks remain
+separate from real model calls. CI/platform execution does not establish every
+employee-device, provider, cross-device recovery or business workflow. Existing
+preview archives and their evidence remain unchanged.
+
+## 1.1.0-rc.9
+
+### Summary
+
+This preview binds project state, managed launches and Web/native sessions to
+the selected directory's filesystem identity. Replacing a directory at the
+same pathname no longer authorizes reuse of its old state or Codex history.
+It continues the existing npm preview channel and adds packaged native helpers
+for authenticated tmux directory-descriptor handoff.
+
+### Highlights
+
+- Introduce private-state v2 bindings with positive directory birth-time
+  receipts and separate replacement generations. Preserve the original store;
+  historical v1 upgrades require independent root verification, a matching
+  inspection receipt and an explicit offline drain. Interrupted upgrades remain
+  fenced until a reviewed retry completes.
+- Pass an already-open directory descriptor to the authorized tmux pane through
+  a native broker/client, validating kernel peer identity and the bound receipt
+  before launch. Ship Darwin/Linux arm64/x64 helpers, static Linux binaries and
+  build/package checks; a missing trusted helper rejects the launch without a
+  pathname fallback. `HCC_PINNED_LAUNCH_MODE=hold` pauses new guarded sessions.
+- Recheck selected-directory identity before CLI launches, hook registration
+  and managed discovery. Persist Codex thread-to-root receipts and require an
+  explicit verified thread for terminal resume/fork; pathname-only histories
+  and managed `--last` launches cannot establish that binding.
+- Add a durable Native owner record alongside the existing file-lock guard.
+  Native, hook and scoped MCP mutations recheck runtime/state generations and
+  process identity under the writer fence. Journal CLI submissions before
+  admission and recover with the original ID; uncertain provider execution is
+  not automatically replayed. Retain sandbox and expected-generation checks.
+- Bind Web project/session keys, Codex history and file/context operations to
+  the selected directory and database. Preserve active sessions' original
+  bindings when a replacement is explicitly selected. Keep tmux ownership and
+  cleanup conditional, reject invalid routes before state resolution, and make
+  user-question answers require current control and an explicit submit action.
+- Document the migration, ownership and historical-session boundaries in
+  Chinese and English. Add four-platform helper build/installed-package CI and
+  verify executable modes and source stamps in the frozen npm package.
+- Add bounded, structured shim-registration diagnostics that distinguish
+  provider entry, persisted binding/pane evidence and peer-list database
+  fallback. Public diagnostics retain fixture-owned booleans and finite enums.
+- Keep separate ACL cache entries for Number and BigInt filesystem stats.
+  Alternating validation paths reuse unchanged results while preserving exact
+  inode and change-time checks; permission and ACL changes still force a fresh
+  inspection in both representations.
+
+### Validation
+
+The rc.9 source passed 1,992 local unit tests with three platform/privilege
+skips and all 13 regression stages. The integration browser baseline passed
+45 checks each for source and temporary npm installations. These checks use real
+HTTP, WebSocket and SQLite with simulated providers, cover desktop and 390px
+layouts, and retain separate cleanup and source-hash receipts.
+
+Native helper formats, executable permissions, C-source stamps and packed-file
+hashes are checked separately from platform execution. Final source-commit CI,
+the immutable rc.9 archive and tag acceptance retain their own receipts.
+These checks do not establish real-model calls, device upgrades or business
+acceptance. Existing released archives and their evidence remain unchanged.
+
 ## 1.1.0-rc.8
 
 ### Summary

package/README.md

@@ -207,6 +207,8 @@ generic session-isolation assumptions.
 - [User Guide](docs/guide.md): setup, Web console, workflows, coordination
   semantics, and environment behavior.
 - [Command Reference](docs/commands.md): compact public command list.
+- [Project directory identity and private state](docs/private-state.md): v2
+  bindings, replacement generations, offline upgrades and verified Codex history.
 - [DeepSeek Harness](docs/dsh.md): hooks/Cordis collaboration, ACP workers,
   project setup and Web launch, with real-model and local-package acceptance evidence.
 - [Native Workers](docs/native.md): HCC-owned Codex, Claude SDK, and dsh ACP

package/README.zh-CN.md

@@ -186,6 +186,8 @@ hcc task done --id 1 --summary "Done"
 - [文档目录](docs/README.zh-CN.md)：全部用户文档和实现文档入口。
 - [用户指南](docs/guide.zh-CN.md)：安装、Web 控制台、协作流程、协作语义和环境变量行为。
 - [命令参考](docs/commands.zh-CN.md)：紧凑公共命令清单。
+- [项目目录身份与私有状态](docs/private-state.zh-CN.md)：v2 绑定、替换目录分代、
+  离线升级及已核实的 Codex 历史边界。
 - [DeepSeek Harness 接入](docs/dsh.zh-CN.md)：hooks/Cordis 协作、ACP worker、
   项目配置与 Web 启动；附真实模型和本地包验收记录。
 - [Native 后台 worker](docs/native.zh-CN.md)：HCC 持有的 Codex、Claude SDK、dsh ACP

package/docs/README.md

@@ -17,6 +17,8 @@ authenticated selection of any existing server directory are accepted risks.
   workflow, stable peer identity, and environment behavior.
 - [Command Reference](commands.md): compact list of public commands and the
   intended use of each command group.
+- [Project directory identity and private state](private-state.md): state locations,
+  v2 generations, cold migration receipts, launch holds and Codex history identity.
 - [DeepSeek Harness](dsh.md): project setup, hooks/Cordis collaboration, ACP workers,
   installable bundles, and session routing boundaries.
 - [Native Workers](native.md): owned background workers, provider adapters,

package/docs/README.zh-CN.md

@@ -14,6 +14,8 @@ provider peer ID 已变更且不会映射旧 ID；受保护接口使用 Runtime
 - [用户指南](guide.zh-CN.md)：安装、启动、Web 控制台、协作语义、工作流、稳定
   peer 身份和环境变量行为。
 - [命令参考](commands.zh-CN.md)：公共命令的紧凑清单，以及每组命令的用途。
+- [项目目录身份与私有状态](private-state.zh-CN.md)：状态位置、v2 分代、冷停机
+  迁移回执、暂停新启动和 Codex 历史身份。
 - [DeepSeek Harness 接入](dsh.zh-CN.md)：项目配置、hooks/Cordis 协作、ACP worker、
   可安装 bundle 与会话路由边界。
 - [Native 后台 worker](native.zh-CN.md)：后台 worker 所有权、provider adapter、

package/docs/commands.md

@@ -21,6 +21,22 @@ hcc uninstall [--purge --yes]
 hooks, shims, and the shell PATH entry; add `--purge --yes` only when you also want to remove the
 current project's `.hello-cc` data and guidance blocks.
 
+## Offline State Migration
+
+```text
+hcc --root DIR migrate-state --offline --yes
+hcc --root DIR --json migrate-state --inspect-private-binding
+hcc --root DIR migrate-state --upgrade-private-binding --offline --yes --assert-historical-root --expect-receipt=SHA256
+```
+
+The first command snapshots retained project-local state into private storage.
+The other two inspect and explicitly upgrade an existing private v1 directory
+binding. Independently verify the historical root, back up its state and stop
+all writers before an upgrade; the inspection receipt is not historical-root
+proof. Interrupted publication stays fenced until a reviewed retry completes.
+See [Project directory identity and private state](private-state.md) for recovery
+boundaries, v2 replacement generations and `HCC_PINNED_LAUNCH_MODE=hold`.
+
 ## Read-only Diagnostics
 
 ```text

package/docs/commands.zh-CN.md

@@ -19,6 +19,20 @@ hcc uninstall [--purge --yes]
 只有在确定也要删除当前项目的 `.hello-cc` 数据和指导块时，才加
 `--purge --yes`。
 
+## 离线状态迁移
+
+```text
+hcc --root DIR migrate-state --offline --yes
+hcc --root DIR --json migrate-state --inspect-private-binding
+hcc --root DIR migrate-state --upgrade-private-binding --offline --yes --assert-historical-root --expect-receipt=SHA256
+```
+
+第一条命令将保留的项目局部状态制作快照，迁入私有目录。后两条用于检查并
+明确升级已有私有 v1 目录绑定。升级前独立核实历史根目录、备份状态，并停止
+全部写入者；检查回执不证明当前目录就是历史根。发布中断时保留封锁标记，
+经核实的重试完成后才恢复访问。恢复边界、v2 替换目录分代和
+`HCC_PINNED_LAUNCH_MODE=hold` 见[项目目录身份与私有状态](private-state.zh-CN.md)。
+
 ## 只读诊断
 
 ```text

package/docs/dsh.md

@@ -20,6 +20,12 @@ Below, `hcc` means a CLI containing these changes. An older global installation
 
 macOS 1.0.5 upgrades use a stable boot-session identity. Follow the [process identity migration notes](macos-process-identity.md) and restart owned runtimes normally.
 
+Project state may resolve to private v2 storage. The `.hello-cc` paths below are
+logical project-state paths; managed setup and session routing use the resolved
+store. Stop Harness and other state writers before a migration. Existing private
+v1 bindings require the explicit historical-root inspection and upgrade receipt
+flow in [Project directory identity and private state](private-state.md).
+
 ## Choose An Entry Point
 
 | Entry | Use | Lifecycle owner |

package/docs/dsh.zh-CN.md

@@ -20,6 +20,11 @@ node /absolute/path/to/hello-cc/bin/hcc.mjs --root /path/to/project dsh web -- -
 
 macOS 从 1.0.5 起使用稳定的启动周期标记。升级时按[进程身份迁移说明](macos-process-identity.md)正常重启所管理的运行时，保留身份无法比较的旧进程。
 
+项目状态可以解析到私有 v2 目录。下文 `.hello-cc` 路径表示逻辑项目状态位置；
+受管理 setup 和会话路由使用解析后的状态目录。迁移前应停止 Harness 和其他
+状态写入者。已有私有 v1 绑定必须经过明确核实历史根目录的检查与回执升级流程，
+详见[项目目录身份与私有状态](private-state.zh-CN.md)。
+
 ## 选择入口
 
 | 入口 | 适用场景 | 会话由谁持有 |

package/docs/native.md

@@ -16,6 +16,25 @@ 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.
 
+## Runtime ownership and directory identity
+
+The runtime retains its file-lock ownership guard and adds a durable SQLite
+owner fence. The owner records runtime generation, mesh database, private-state
+generation, root directory identity and process PID/start token/command hash.
+Native writes and derived hook/scoped MCP writes recheck that owner under the
+shared writer fence. A live or unverified owner blocks takeover; a successor can
+claim released state or an owner proven to have exited. Directory replacement
+and stale executor capabilities cannot authorize writes to the successor.
+
+Old runtime pointers without a directory identity receipt or owner fence are
+rejected with `PROJECT_PATH_CHANGED` or `NATIVE_OWNER_UNVERIFIED`, respectively.
+Stop the old runtime using its running build and confirm exit before starting a new one. Native
+provider processes use their scoped HCC MCP tools; ordinary `hcc` commands from
+that environment are rejected with `NATIVE_CLI_SCOPE_REQUIRED`. These checks
+retain the existing sandbox-policy and expected-runtime-generation rules.
+See [Project directory identity and private state](private-state.md) for v1
+binding upgrade receipts and replacement generations.
+
 ## Session fork and retries with the original ID
 
 `hcc native fork --parent codex-reviewer --peer codex-branch` invokes the provider's
@@ -221,7 +240,8 @@ 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
+`<resolved-project-state>/native/` (project-local or private storage described
+above) 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.

package/docs/native.zh-CN.md

@@ -14,6 +14,23 @@ Native 模式运行由 HCC 创建并持有的后台 worker。共享 peer、任
 不代表 host 会把多条待处理消息塞进同一个 turn。ACP 的 resume 和 session close
 取决于 provider 声明的扩展；不能把 ACP resume 等同于重放原始会话历史。
 
+## Runtime 所有权与目录身份
+
+Runtime 保留原有 file-lock owner 保护，并增加持久化的 SQLite owner 校验。
+owner 保存 runtime generation、mesh 数据库、私有状态 generation、根目录身份
+以及进程 PID、启动标记和命令哈希。Native 写入及派生 hook/scoped MCP 写入在
+同一个 writer fence 中复核 owner。存活或无法核实的 owner 阻止接管；后继进程
+只能接管已释放或已证实退出的 owner。目录替换或旧执行器 capability 不能授权
+写入后继状态。
+
+旧 runtime pointer 缺少目录身份回执或 owner fence 时分别被
+`PROJECT_PATH_CHANGED` 或 `NATIVE_OWNER_UNVERIFIED` 拒绝。
+先用正在运行的旧版本停止它，确认退出后再启动新版本。Native provider 子进程
+通过其 scoped HCC MCP 工具协作；在该环境中直接调用普通 `hcc` 命令会收到
+`NATIVE_CLI_SCOPE_REQUIRED`。原 sandbox policy 和 expected runtime generation
+规则继续生效。v1 绑定升级回执和替换目录分代见
+[项目目录身份与私有状态](private-state.zh-CN.md)。
+
 ## 会话 fork 与原 ID 重试
 
 `hcc native fork --parent codex-reviewer --peer codex-branch` 使用 provider 自身的
@@ -188,7 +205,8 @@ HCC 不为只读 worker 注入自有的任务／锁／结果写操作 MCP，也
 `status.shutdown_error` 报告错误；处理所报问题后，再次执行 `native down`。
 
 事件保留语义输出和完成证据，不把 token delta 持久化为投递回执。runtime 状态位于
-`<project>/.hello-cc/native/`，协作记录仍写入所选 HCC 数据库。控制接口是独立于 Web
+`<解析后的项目状态目录>/native/`，可以是项目局部或上方说明的私有状态；协作记录
+仍写入所选 HCC 数据库。控制接口是独立于 Web
 终端传输的本地认证 API；其 runtime pointer 和日志属于项目私有状态。
 
 ## 如何理解投递回执

package/docs/private-state.md

@@ -0,0 +1,115 @@
+# Project directory identity and private state
+
+English | [中文](private-state.zh-CN.md)
+
+Use a build containing the commands below; an older global installation may not
+include them. These instructions describe state handling, not a receipt for an
+installation, model call or production migration.
+
+## Directory selection and state location
+
+HCC binds a selected project to its canonical directory and filesystem identity
+(`dev`, `ino`, and `birthtimeNs`). It checks that identity again before opening
+state, launching a session and admitting managed mutations. A replacement at
+the same pathname is a different project directory. `PROJECT_PATH_CHANGED`
+requires selecting the current directory again; retained sessions keep their
+original binding.
+
+Stable trusted projects may keep state under `<project>/.hello-cc`. Projects that
+need private state use `~/.hello-cc/projects/<SHA256-of-canonical-root>/`. Once a
+private binding is established, it remains authoritative even if permissions
+change or its directory disappears. HCC refuses to silently fall back to an
+old project-local database.
+
+Private binding format v2 records the full directory identity and requires a
+positive filesystem birth time; an unavailable or zero value is rejected. If original A
+has a valid v2 binding and the same path is later occupied by B, explicit Web
+selection can provision B under
+`~/.hello-cc/projects/<hash>.generations/<generation>/`. A's state directory and
+root manifest are retained; the original authority marker is fenced against
+older readers. B receives separate state and a separate managed tmux namespace.
+Missing, conflicting or unbound generation records require recovery rather
+than automatic reuse. This binding version is separate from the mesh database
+schema version.
+
+## Migrating project-local state
+
+When HCC reports `STATE_MIGRATION_REQUIRED`, stop every writer before moving
+the retained project-local store into private state. Include Web and Native
+runtimes, PTY/tmux sessions, hooks, Harness processes and external database
+clients. Back up the project-local store and any existing private state,
+authority markers and generation records.
+
+```sh
+hcc --root /absolute/path/to/project migrate-state --offline --yes
+```
+
+The migrator checks known runtime/PTY/mesh process evidence, snapshots SQLite
+including WAL, validates the snapshot and leaves the source directory intact.
+`--offline` is the operator's assertion that all writers have stopped; observed
+process records cannot establish the absence of unregistered writers. Managed
+DSH artifacts are verified and archived, then rebuilt for the private path.
+Edited managed DSH artifacts, unsafe filesystem entries or a source changing
+during the snapshot fail closed.
+
+## Upgrading a historical private v1 binding
+
+`STATE_BINDING_UPGRADE_REQUIRED` means an existing private store lacks v2's
+birth-time binding. Matching pathname, device and inode alone cannot identify
+historical A. Independently verify A and cold-drain its writers before upgrade.
+If the path now holds B, restore and verify A at that path first; selecting B
+cannot upgrade A's historical v1 metadata automatically.
+
+Inspect without changing the binding:
+
+```sh
+hcc --root /absolute/path/to/project --json migrate-state --inspect-private-binding
+```
+
+The result reports `status` and, when required or pending, a SHA256 `receipt`.
+The receipt describes the currently observed metadata; it does not prove that
+the current directory is historical A. After independent verification, backup
+and cold drain, copy the exact receipt into:
+
+```sh
+hcc --root /absolute/path/to/project migrate-state \
+  --upgrade-private-binding --offline --yes --assert-historical-root \
+  --expect-receipt=COPY_THE_INSPECTION_SHA256
+```
+
+Upgrade checks known writers both before and after publication, durably fences
+v1 readers first, then writes the v2 root manifest and removes the pending
+fence. It updates binding metadata without copying the store. A publication or
+second offline-check failure leaves access fenced. Inspect again and retry
+with the same verified root and a matching receipt; preserve all evidence if
+manual recovery is reported. Do not fabricate markers or purge a historical
+store to make an upgrade pass. Older readers can reject v2 state, so drain old
+builds before switching execution.
+
+## Pausing new launches
+
+`HCC_PINNED_LAUNCH_MODE` accepts `pinned` (also the default when unset) or `hold`.
+`hold` rejects new guarded session launches with `PINNED_LAUNCH_PAUSED`; it does
+not terminate existing processes or revoke a launch already prepared. Invalid
+values are rejected. A provider environment that strips HCC variables cannot
+clear the parent process's hold. Maintenance workers used for pinned file and
+guidance operations remain available.
+
+Set this environment on the invoking HCC process. Changing a later shell's
+environment does not update a running Web or Native runtime. A hold is not a
+substitute for stopping every writer before migration.
+
+## Codex terminal history
+
+HCC's Codex history controls require a persisted thread-to-root identity receipt.
+Built-in new/fork launches record the resulting thread's original directory;
+resume and fork verify both that identity and the explicit thread ID. The Web
+history list omits unverified or conflicting entries and reports their count.
+An old cwd string, imported peer row or manually assembled command does not
+establish a verified root. `CODEX_HISTORY_UNVERIFIED` and conflicting bindings
+require manual review; HCC provides no automatic historical association command.
+
+Terminal `codex resume --last` and `codex fork --last` cannot establish an exact
+thread and are rejected by these managed controls. Select an explicit verified
+thread ID. [Native workers](native.md) retain their separate saved-worker resume
+and ownership rules, including `native start --resume last`.

package/docs/private-state.zh-CN.md

@@ -0,0 +1,92 @@
+# 项目目录身份与私有状态
+
+[English](private-state.md) | 中文
+
+请使用包含下方命令的版本；旧的全局安装可能尚未支持。这份文档说明状态处理
+规则，不代表已完成设备安装、模型调用或生产状态迁移。
+
+## 目录选择与状态位置
+
+HCC 将所选项目绑定到 canonical 目录与文件系统身份（`dev`、`ino`、
+`birthtimeNs`），并在打开状态、启动会话和接收受控修改前复核。同一路径被替换
+后属于另一个项目目录。遇到 `PROJECT_PATH_CHANGED` 应重新选择当前目录；已有
+会话仍保留原目录绑定。
+
+稳定且可信的项目可以把状态保存在 `<project>/.hello-cc`。需要私有状态的项目
+使用 `~/.hello-cc/projects/<canonical-root的SHA256>/`。私有绑定建立后，即使
+权限变化或目录丢失，它仍是权威状态；HCC 不会静默退回旧的项目局部数据库。
+
+私有绑定 v2 保存完整目录身份，要求文件系统提供正值的目录创建时间；缺失或
+零值会被拒绝。原目录 A 已有有效 v2 绑定，而同一路径后来被
+B 占用时，Web 的明确目录选择可在
+`~/.hello-cc/projects/<hash>.generations/<generation>/` 为 B 建立独立状态。
+A 的状态目录与根 manifest 保留，原 authority marker 增加阻止旧版读取的标记。
+B 使用独立状态和 managed tmux namespace。分代记录丢失、冲突或没有对应绑定时
+要求恢复，不会自动复用。私有绑定版本与 mesh 数据库 schema 版本彼此独立。
+
+## 迁移项目局部状态
+
+遇到 `STATE_MIGRATION_REQUIRED` 时，先停止全部写入者，再把保留的项目局部
+状态迁入私有目录。写入者包括 Web、Native runtime、PTY/tmux 会话、hooks、
+Harness 进程和外部数据库客户端。备份项目局部状态，以及已有的私有目录、
+authority marker 和 generation 记录。
+
+```sh
+hcc --root /absolute/path/to/project migrate-state --offline --yes
+```
+
+迁移会检查已记录的 runtime、PTY 和 mesh 进程证据，创建包含 WAL 的 SQLite
+快照并校验，保留源目录。`--offline` 是操作者对全部写入者已停止的断言；已记录
+进程不能证明没有未登记写入者。受管理的 DSH 文件会先验证、归档，再按私有路径
+重建。受管理 DSH 文件被改、文件系统条目不安全或快照期间来源改变时会被拒绝。
+
+## 升级历史私有 v1 绑定
+
+`STATE_BINDING_UPGRADE_REQUIRED` 表示已有私有状态缺少 v2 的目录创建时间绑定。
+仅有相同路径、device 和 inode 不能确认当前目录就是历史 A。升级前应独立核实
+A 的身份，并冷停机全部写入者。若当前路径已是 B，应先在该路径恢复并核实 A；
+选择 B 不会自动升级 A 的历史 v1 元数据。
+
+先检查，保持绑定不变：
+
+```sh
+hcc --root /absolute/path/to/project --json migrate-state --inspect-private-binding
+```
+
+结果包含 `status`；需要升级或尚未完成时包含 SHA256 `receipt`。回执描述当前
+观察到的元数据，不能证明当前目录就是历史 A。独立核实、备份并完成冷停机后，
+把本次准确回执复制到：
+
+```sh
+hcc --root /absolute/path/to/project migrate-state \
+  --upgrade-private-binding --offline --yes --assert-historical-root \
+  --expect-receipt=COPY_THE_INSPECTION_SHA256
+```
+
+升级在发布前后检查已知写入者，先持久化阻止 v1 读取的标记，再写入 v2 根
+manifest，最后清除 pending 标记。它只升级绑定元数据，不复制状态目录。发布
+失败或第二次离线检查失败时，状态仍被封锁。重新检查后，在同一个已核实根目录
+和匹配回执下重试；报告需要人工恢复时保留全部证据。不要伪造 marker 或清空
+历史状态来绕过升级。旧版本可能拒绝 v2 状态，应先停止旧版本的执行再切换。
+
+## 暂停新启动
+
+`HCC_PINNED_LAUNCH_MODE` 只接受 `pinned`（未设置时也是默认行为）或 `hold`。
+`hold` 以 `PINNED_LAUNCH_PAUSED` 拒绝新的受控会话启动，不终止已有进程，也
+不撤销已经准备完成的启动。其他取值被拒绝。provider 环境清除 HCC 变量也不能
+解除父进程的 hold。用于固定目录文件或指导块操作的 maintenance worker 仍可运行。
+
+环境变量应设置在调用 HCC 的进程上；后来修改另一个 shell 的环境不会更新正在
+运行的 Web 或 Native runtime。hold 不能代替迁移前停止全部写入者。
+
+## Codex 终端历史边界
+
+HCC 的 Codex 历史入口要求持久化的 thread 与原根目录身份回执。内置 new/fork
+启动记录最终 thread 的原目录，resume/fork 同时校验目录身份与明确 thread ID。
+Web 历史列表省略未核实或冲突的记录，并返回这类记录的数量。旧的 cwd 字符串、
+导入的 peer 记录或手工拼接命令都不能建立可信绑定。
+`CODEX_HISTORY_UNVERIFIED` 和冲突绑定需要人工审查；HCC 未提供自动关联历史的命令。
+
+终端 `codex resume --last` / `codex fork --last` 无法确定准确 thread，因此被这些
+受控入口拒绝；应选择明确且已核实的 thread ID。[Native worker](native.zh-CN.md)
+采用独立的保存会话与所有权规则，仍支持 `native start --resume last`。

package/lib/cli/app.mjs

@@ -91,7 +91,8 @@ 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 { assertPrivateStateOffline, migrateLegacyProjectState } from '../runtime/state-migration.mjs';
+import { inspectPrivateProjectBindingUpgrade, upgradePrivateProjectBinding } from '../runtime/private-state.mjs';
 import { projectDbPath } from '../runtime/paths.mjs';
 import { ensureDshIntegration } from '../integrations/dsh.mjs';
 
@@ -590,13 +591,45 @@ function removeGuidanceBlocks(ctx, options = {}) {
 
 function cmdMigrateState(ctx, args) {
   if (wantsHelp(args)) {
-    console.log(`${CLI_NAME} migrate-state --offline --yes\n\n` +
+    console.log(`${CLI_NAME} migrate-state --offline --yes\n` +
+      `${CLI_NAME} migrate-state --inspect-private-binding\n` +
+      `${CLI_NAME} migrate-state --upgrade-private-binding --offline --yes ` +
+      '--assert-historical-root --expect-receipt=SHA256\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.');
+      'A private binding upgrade requires independent confirmation that the current root is the historical root. ' +
+      'The inspection receipt alone cannot prove this. The ordinary migration snapshots SQLite including WAL ' +
+      'and leaves the old directory untouched.');
     return;
   }
-  const opts = parseOpts(args, { booleans: ['offline', 'yes'] });
-  validateOpts('migrate-state', opts, ['offline', 'yes']);
+  const opts = parseOpts(args, { booleans: ['offline', 'yes', 'inspect-private-binding',
+    'upgrade-private-binding', 'assert-historical-root'] });
+  validateOpts('migrate-state', opts, ['offline', 'yes', 'inspect-private-binding',
+    'upgrade-private-binding', 'assert-historical-root', 'expect-receipt']);
+  if (opts['inspect-private-binding'] === true) {
+    if (opts['upgrade-private-binding'] || opts.offline || opts.yes ||
+        opts['assert-historical-root'] || opts['expect-receipt']) {
+      throw new CliError('BAD_ARGS', '--inspect-private-binding cannot be combined with upgrade options');
+    }
+    const result = inspectPrivateProjectBindingUpgrade(ctx.root);
+    printResult(ctx, result, () => JSON.stringify(result, null, 2));
+    return;
+  }
+  if (opts['upgrade-private-binding'] === true) {
+    const result = upgradePrivateProjectBinding(ctx.root, {
+      confirmedOffline: opts.offline === true,
+      confirmedHistoricalRoot: opts['assert-historical-root'] === true && opts.yes === true,
+      expectedReceipt: opts['expect-receipt'],
+      assertOffline: ({ stateDir }) => {
+        assertPrivateStateOffline(stateDir);
+        return true;
+      }
+    });
+    printResult(ctx, result, () => JSON.stringify(result, null, 2));
+    return;
+  }
+  if (opts['assert-historical-root'] || opts['expect-receipt']) {
+    throw new CliError('BAD_ARGS', 'Private binding options require --upgrade-private-binding');
+  }
   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');
@@ -630,6 +663,14 @@ function cmdMigrateState(ctx, args) {
 async function dispatch(ctx, rest) {
   const command = rest[0];
   const args = rest.slice(1);
+  // Native provider children inherit this marker. The ordinary CLI opens the
+  // mesh database outside the durable native owner transaction, so only the
+  // two owner-fenced entry points may run from that environment.
+  if (process.env.HCC_NATIVE_OWNER &&
+      !(command === 'hook' || (command === 'mcp' && args[0] === 'serve'))) {
+    throw new CliError('NATIVE_CLI_SCOPE_REQUIRED',
+      'Native workers must use their scoped MCP tools; ordinary hcc commands cannot write outside the native owner fence');
+  }
   if (!command || command === '--help' || command === '-h' || command === 'help') return helpMain();
   if (command === '--version' || command === 'version') return console.log(VERSION);
   if (command === 'up') return cmdUp(ctx, args);