@logicseek/hello-cc 1.1.0-rc.1 → 1.1.0-rc.4

package/CHANGELOG.md

@@ -16,126 +16,247 @@ 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-rc.1
+## 1.1.0-rc.4
 
 ### Summary
 
-hello-cc 1.1.0-rc.1 brings project and session navigation, structured
-conversations, recoverable split panes, and bounded rendering to the Web
-workbench. It also brings HCC-owned Codex, Claude and DeepSeek Harness workers
-into the same task, message, handoff and result-review workflow, with explicit
-permissions and delivery receipts. This release is intended for the npm
-`preview` dist-tag and a GitHub prerelease.
+This preview adds guarded forks for owned Codex and Claude sessions, durable
+submission retries, and a persisted Codex read-only policy. It retains the
+session isolation and shutdown fixes from rc.3.
 
 ### Highlights
 
-- Switch between English, Chinese or the system language; choose system,
-  light or dark interface and terminal themes, comfortable or compact spacing,
-  terminal font size and focus mode. Settings apply without replacing active
-  terminal connections or discarding drafts, and remain reachable on mobile.
-- Search sessions by name, task, provider, path or command; combine keywords
-  and provider/activity filters. Project changes clear old session state
-  immediately and ignore delayed responses from the previous project.
-- Read Codex conversations by turn with focused user, assistant, command,
-  file-change and status cards. Preserve reading position, drafts, expanded
-  details and keyboard focus during updates. Keep approvals visible
-  independently of the conversation page.
-- Use the keyboard command palette for project, session and workbench
-  navigation. Search the current terminal scrollback locally with match counts,
-  previous/next navigation, case sensitivity and whole-word matching. The search
-  addon is served locally.
-- Restore a project-specific two-pane workspace with horizontal or vertical
-  layout, adjustable proportions and a saved secondary session. Each pane
-  retains its own connection and draft; viewing the same session twice leaves
-  the secondary pane read-only until an explicit control handoff.
-- Page long Codex timelines and large output segments while keeping all
-  retained content accessible. Copy the complete original text, including
-  content outside the visible segment. Preserve Unicode characters, scroll
-  anchors, tool expansion and drafts across streaming updates.
-- Coalesce Codex text-delta notifications within a bounded 50 ms window while
-  updating internal state immediately. Approvals, completion, errors and
-  connection changes publish promptly. Unchanged native snapshots avoid
-  redundant broadcasts without skipping ownership checks.
-- Manage owned native workers through `hcc native`: Codex App Server, the
-  optional Claude Agent SDK and DeepSeek Harness ACP share HCC coordination
-  while retaining their provider-specific lifecycle and session identity. Web
-  can discover and control an existing native worker without creating a second
-  provider process.
-- Distinguish queued, submitted, provider-accepted, completed, failed and
-  uncertain delivery states. Uncertain submissions are not automatically
-  replayed; runtime restarts preserve the uncertainty needed to avoid duplicate
-  work.
-- Handle supported Codex permission requests, questions and common MCP form
-  fields from Web or the local CLI. Claude responses approve the original tool
-  input once, and ACP approval selects a provider-offered one-time option.
-  Responses remain bound to the current worker, session, turn, request and
-  controller.
-- Give hosted executors a temporary MCP capability scoped to the project,
-  database, peer and live runtime. Coordination tools support tasks, inbox,
-  messages, handoff, owned locks and local result records. Executor shutdown
-  revokes the capability without rewriting global provider configuration.
-- Review local command results, explicitly submitted evidence and manual
-  acceptance records with separate local-validation, publication and
-  business-acceptance categories. A completed model turn or successful command
-  does not automatically complete an HCC task.
-- Include DeepSeek Harness hooks, the Cordis bundle and owned ACP workers,
-  with identity-bound crash recovery and retryable cleanup after temporary
-  database failures.
-- Use macOS `kern.bootsessionuuid` for the boot component of process identity
-  instead of wall-clock boot time. Clock adjustments no longer make the same
-  process appear replaced, while a different boot UUID still identifies a
-  reboot. Missing or malformed boot identity remains unknown.
-- Publish private-state binding manifests atomically, reject legacy-state
-  takeover during interrupted initialization, and recheck the project identity
-  before reading, writing or clearing its runtime state. A reused directory
-  path does not silently inherit the previous project's private state.
-- Validate existing SQLite files without opening and closing an additional
-  descriptor, preserving locks held by another SQLite connection in the same
-  process. File ownership, permissions, identity and sidecar checks remain in
-  place.
+- Fork an idle, owned Codex or Claude session into a distinct worker and provider
+  session. Pending approvals, unresolved deliveries and changing parent bindings
+  prevent a fork. DeepSeek Harness does not currently support native fork.
+- Create Codex workers with `--sandbox read-only`. Resumes and forks retain the
+  saved policy; approval escalation and HCC scoped MCP are disabled for these
+  workers. Codex must confirm the policy before the worker becomes available.
+  This is a provider filesystem sandbox, not an all-tools or network guarantee.
+- Retry an unconfirmed Web submission with its original ID and message after
+  reviewing its receipts. A later edited draft remains intact. Retries require
+  current control and the original executor identity. Older pending records
+  without the required identity remain available for manual review only.
+- Persist the message and its retry identity together; repair the delivery
+  record after interruption without creating a second message. Uncertain
+  provider execution is never automatically replayed.
+- Refresh late DeepSeek Harness tool input on the existing approval request,
+  preserving its identity and oversized-input restrictions.
+- Disable split views when the page lacks the browser session required by its
+  embedded pane. Keep saved layouts for a later authenticated page.
+- Distinguish the active runtime's clock observation from manual GC mutations
+  in regression checks while requiring all other metadata to remain unchanged.
 
-### Compatibility Notes
+### Validation
+
+Validation covers policy persistence, legacy-runtime refusal, fork inheritance,
+submission recovery and browser retry behavior with later draft edits. Source,
+installed-package, CI and real-provider results retain separate receipts; prior
+historical connection-reset and provider failures are not reclassified by a
+passing retry. Existing frozen release archives remain unchanged.
+
+## 1.1.0-rc.3
+
+### Summary
+
+This preview integrates the multi-provider Web workbench with project Agent
+settings, retained native history and project file editing. It also includes
+session isolation and recovery fixes, shutdown quiescence and more precise
+regression diagnostics. A new frozen package preserves the earlier rc.2 archive.
+
+### Highlights
+
+- Create Codex, Claude and DeepSeek Harness Agents from the Web workbench; retain
+  project defaults, explicit native-history restore and directory-bound drafts.
+- Upload project files and edit complete UTF-8 text with revision conflicts,
+  preserved drafts and explicit readback after uncertain writes.
+- Scope login cookies by trusted protocol and port so Web instances on different
+  ports do not overwrite each other's login or logout state. Sign in again after
+  upgrading; arbitrary SSH port remapping is not inferred.
+- Keep the native-worker discovery error and refresh guidance when a restore
+  receipt is absent, instead of failing inside the error handler.
+- Stop admitting background work when administrator shutdown is accepted, then
+  start cleanup after the HTTP response finishes or closes; preserve process
+  identity checks, exit deadlines and independently owned workers.
+- Recognize terminal regression markers split across output chunks and submit
+  fixture input once. Isolate regression HTTP connections and test-owned ports.
+- Add bounded CI task-dispatch and HTTP failure diagnostics without recording
+  request bodies, credentials or query parameters, or retrying failed requests.
+
+### Validation
+
+Release checks compare the package file set, per-file hashes and modes with the
+new frozen rc.3 archive. Source tests, browser checks and installed Harness checks
+retain their exact commit and package receipts. The regression transport changes
+isolate test fixtures; they do not establish the root cause of the earlier macOS
+connection reset. Publication, current-device upgrades and real business calls
+require separate evidence.
+
+## 1.1.0-rc.2
+
+### Summary
+
+This local Web workbench candidate adds project Agent defaults, retained native
+history with explicit closed-worker resume, and project file upload/editing.
+It is based on the 1.0.5 delivery line and retains its process identity, tmux
+snapshot and shutdown fixes. A local candidate does not establish publication.
+
+### Highlights
 
-- Projects under shared or writable ancestors use per-user private state.
-  Existing legacy state in those projects requires an explicit offline
-  `migrate-state --offline --yes` after stopping all writers; it is not silently
-  copied or discarded. Back up both the private store and its authority marker
-  before manual recovery of a replaced project directory.
-- Node.js 24 or newer is required. Linux and macOS are supported host
-  environments; Windows users use WSL. Native Windows shells are outside the
-  supported host contract.
-- Browser-controllable terminals require tmux where documented. `node-pty`
-  remains pinned to `1.2.0-beta.15`; the terminal search addon is pinned to
-  `0.16.0`.
-- Native workers require an installed and authenticated provider. Claude's
-  Agent SDK remains optional and is loaded when a Claude worker starts; HCC
-  does not install it automatically. DeepSeek Harness integration targets
-  `0.2.0-rc.2`.
-- Closing a browser page does not stop a hosted executor. An independent
-  native runtime also survives Web-runtime shutdown; explicitly closing its
-  worker terminates that worker. Web-owned App Server executors remain owned
-  by their Web runtime.
-- Saved-session resume creates a newly owned provider connection and requires
-  the prior owner to be confirmed stopped. It does not migrate an arbitrary
-  live TUI or desktop process, and uncertain owners remain protected.
-- Existing schema v7, Runtime API v2 and provider authentication boundaries
-  continue to apply. Browser control handoff never approves a provider operation
-  by itself. Persisted macOS identities using the older boot-token format remain
-  unknown across the format transition, rather than being treated as confirmed
-  dead.
+- Create Codex, Claude and DeepSeek Harness background Agents from one Web form;
+  save project defaults without changing provider credentials or global settings.
+- Read HCC-retained native events and resume explicitly closed workers with
+  owner, session and working-directory identity checks.
+- Upload new project files up to 10 MiB and edit complete UTF-8 text up to 1 MiB,
+  with revision conflicts, preserved drafts and explicit uncertain-write readback.
+- Bind browser project requests and drafts to the selected directory identity.
+- Preserve native Web connections and control tokens when background discovery
+  overlaps Agent creation or history restore; discard stale discovery results.
+- Recheck provider initialization before rejecting an older snapshot with no
+  session ID, and retain exact project file matches when a wider search times out.
+- Stop admitting background scans as soon as an administrator stop is accepted,
+  and begin cleanup after its HTTP response finishes or closes. Keep existing
+  process identity checks, exit confirmation deadlines and independent workers.
+- Keep the existing terminal/App Server modes, readonly previews and bounded
+  reconnect behavior.
 
 ### Validation
 
-Feature-specific records cover controlled browser interactions, real PTY/tmux
-behavior, provider protocols and selected authenticated model workflows. Each
-record applies to its recorded inputs and scope. The final release record
-identifies the frozen package, platform installations and checks that apply to
-this combined candidate; performance samples are controlled observations, not
-production capacity or long-term memory guarantees.
+The candidate is checked with the full source regression suite, a disposable
+npm installation and desktop/narrow browser flows. Real-provider entry and
+history checks have separate receipts. These checks do not establish a public
+release, a global installation upgrade or real business acceptance.
+
+## 1.0.5
+
+### Summary
+
+macOS process identities use the kernel boot session UUID so changes to the
+reported boot time cannot make a running process appear to have been replaced.
+The issue was observed during post-release sustained acceptance of 1.0.4.
+
+### Highlights
+
+- Preserve process identity across changes to the wall-clock-derived boot time.
+- Keep live processes with an older Darwin identity format protected while their
+  ownership cannot be compared; a format change does not prove that an owner exited.
+- Retain strict process state, start time and zombie checks, with unknown results
+  when a stable boot session identifier cannot be read.
+- Keep the existing npm `latest` release channel.
+- Confirm the original local runtime has exited when its stop response is lost,
+  while preserving unknown owners and replacement runtime pointers.
+- Retain structured shutdown error codes when Node warnings share stderr.
+
+### Validation
+
+Targeted regression tests cover boot identity drift, boot-session changes,
+malformed observations and conservative handling of existing runtime ownership.
+Full source, package, current-device and sustained-run validation are recorded
+separately. The interrupted 1.0.4 sustained run remains a failed attempt.
+The first 1.0.5 candidate passed the current-Mac sustained check; a subsequent
+CI transport timeout exposed the separate stop-confirmation failure. Its
+targeted verification and replacement candidate retain separate evidence.
+
+Existing processes keep the implementation they started with. Quit and reopen
+Harness normally to activate the update. An older active owned runtime should
+finish and stop normally before it is reclaimed; do not force takeover based
+on an incompatible identity marker.
+
+## 1.0.4
+
+### Summary
+
+Session lists no longer run synchronous tmux client probes for each displayed
+terminal. A bounded asynchronous snapshot supplies display information while
+live process and terminal observations continue to guard control actions.
+
+### Highlights
+
+- Share one short-lived tmux display snapshot across sessions. Cold, stale or
+  failed observations remain unknown, and pending probes stop with the runtime.
+- Preserve live checks for terminal control, rebind, stop and ownership.
+- Treat exited macOS zombie processes as dead, so shutdown waits can complete
+  while a parent has yet to reap the PID; malformed observations remain unknown.
+- Include the HTTP method, request path, deadline and elapsed time in runtime
+  request failures, without request bodies, query parameters or credentials.
+- Keep DeepSeek Harness on the existing npm `latest` channel.
+
+### Validation
+
+Targeted tests cover slow probes, stale and failed snapshots, refresh coalescing,
+shutdown and request diagnostics. Full regression, official installed Harness,
+registry readback and current-Mac model checks have separate verification records.
+The earlier 1.0.3 macOS CI timeout remains historical evidence: removing a known
+blocking path does not identify the specific cause of that earlier timeout.
+Regression shutdown tracks the exact fixture process identity, distinguishes
+reused PIDs and zombies, and retains bounded failure diagnostics before cleanup.
+
+## 1.0.3
+
+### Summary
+
+This maintenance release keeps DeepSeek Harness on the normal npm `latest`
+channel and repairs the CLI, native-session and Web regressions identified while
+archiving 1.0.2. It retains the verified Cordis cleanup and recovery behavior.
+
+### Highlights
+
+- Preserve provider process identity during registration and discovery; update
+  owned hooks without discarding unrelated hooks or damaged user configuration.
+- Keep explicit hook database routing and quote generated terminal arguments.
+- Preserve the recorded origin of native submissions across restarts; peer
+  messages cannot gain local-user authority from their sender name or text.
+- Keep managed state directories and database files private without replacing
+  existing data or changing external database parent permissions. Terminal stream
+  buffers follow each session's project.
+- Bound streaming updates and long-message rendering while preserving complete
+  copied content, reader position, approval details and session ownership checks.
+- Isolate request parsing failures, retain local/proxy access contracts, serialize
+  Web startup and resolve terminal assets with npm dependency hoisting.
+- Native runtime ownership uses alternate ports for identifiable unrelated local
+  listeners while keeping one owner per project. Silent or legacy listeners are
+  rejected conservatively, and ownership remains until shutdown completes.
+
+### Validation
+
+The full restored regression suite and the installed official Harness package
+checks run against this composed release. The frozen file manifest and verification
+record live under `docs/verification/`; those source-only records are excluded
+from the npm package. Publication, current-device activation and real-model
+acceptance are recorded separately from source and CI checks.
+
+## 1.0.2
+
+### Summary
+
+DeepSeek Harness now joins hello-cc through project hooks, a Cordis collaboration
+bundle, and owned ACP workers. This release promotes the runtime verified in
+`1.0.2-dsh.3` to the normal npm `latest` channel. Runtime code is unchanged from
+that candidate; version metadata and release documentation identify this release.
+
+### Highlights
+
+- Harness Agents use their exact session and project identity for task, message,
+  lock, result, and handoff operations. Context acknowledgements follow committed
+  model input, and permission decisions retain the Harness policy chain.
+- Owned ACP workers support queued prompts, scoped MCP tools, approvals,
+  interruption, session resume, and shutdown through the CLI and Web interface.
+- Managed project configuration migrates verified paths from source checkouts to
+  installed packages while preserving user edits.
+- Cordis sessions recover after a verified owner process exits; transient
+  database failures during retirement remain retryable while old tool authority
+  is revoked immediately.
+- Node.js 24+ and official Harness `0.2.0-rc.2` are required. Supported hosts are
+  macOS and Linux; Windows uses WSL. Native Windows shells are not supported.
+
+### Validation
 
-Publication readback, registry installation, employee-device acceptance and
-genuine business acceptance remain distinct evidence categories. No result in
-one category automatically establishes another.
+The byte-identical preview runtime passed macOS real-model installation checks
+(11), Linux container installation and deterministic collaboration checks (8 + 7),
+and frozen-package recovery tests (17). Its registry download and all 216
+installed files matched the candidate. This stable package receives independent
+release, installation, and registry readback checks. Other-device and genuine
+business acceptance remain separate stages.
 
 ## 1.0.2-dsh.3
 

package/README.md

@@ -43,20 +43,11 @@ grace. `hcc gc` retains history unless `--history` is explicit. `--tls` encrypts
 the console; `--trust-proxy` requires a fixed `--proxy-origin`. Two risks remain
 intentional: the default listener is plaintext HTTP on `0.0.0.0` for trusted
 LANs, and an authenticated browser may select any existing server directory.
-Managed `.hello-cc` state is private to the current OS user. Keep project roots
-behind cross-user-stable paths for project-local storage. For a root that
-another OS user could replace, hello-cc stores managed state under
-`~/.hello-cc/projects/<root-hash>/` instead. An existing project-local state
-must be migrated explicitly while every old writer is stopped:
-`hcc --root DIR migrate-state --offline --yes`. Migration keeps the original
-directory for recovery. If you set `--db` or `HCC_DB` outside managed state,
-secure that database and its parent directory yourself.
 
 ## Highlights
 
 - **Shared project memory**: peers, tasks, messages, locks, handoffs, and
-  events are stored in a private managed `mesh.db` (project-local for stable
-  roots, otherwise under the current user's home directory).
+  events are stored in `<project>/.hello-cc/mesh.db`.
 - **Real terminal control**: Web attaches to the same local tmux pane as your
   terminal, not a separate browser-only shell.
 - **Claude/Codex awareness**: hooks inject live `hcc` state before model turns,

package/README.zh-CN.md

@@ -37,17 +37,10 @@ unknown 证据获得最长 120 秒宽限。`hcc gc` 默认保留历史，必须
 `--history`。`--tls` 提供传输加密；`--trust-proxy` 必须固定
 `--proxy-origin`。两项风险是有意保留的：默认在可信内网以明文 HTTP 监听
 `0.0.0.0`，且已认证浏览器可以选择服务器上任意已存在目录。
-默认的 `.hello-cc` 状态目录仅允许当前系统用户访问。不要把项目根目录放在
-不可信系统用户可写的位置；如果其他系统用户可替换项目路径，受管状态会改存于
-`~/.hello-cc/projects/<项目根路径哈希>/`。已有项目本地状态不会自动丢弃或迁移：
-先停止所有旧进程及外部数据库写入者，再运行
-`hcc --root 目录 migrate-state --offline --yes`；原目录保留供恢复。
-若通过 `--db` 或 `HCC_DB` 将数据库放在受管状态目录之外，请自行保护数据库及其
-父目录的权限。
 
 ## 特色
 
-- **项目共享状态**：peers、tasks、messages、locks、handoffs 和 events 写入私有的 `mesh.db`；路径稳定时保留项目本地目录，否则存于当前用户的 home 目录。
+- **项目本地共享状态**：peers、tasks、messages、locks、handoffs 和 events 写入 `<project>/.hello-cc/mesh.db`。
 - **Web 控制真实终端**：浏览器 attach 到和本地终端相同的 tmux pane，不是浏览器里另开的临时 shell。
 - **Claude/Codex 感知项目状态**：hooks 会在模型回答前注入实时 `hcc` 状态。
 - **减少编辑冲突**：通过 advisory lock 和 handoff 显式协调多 agent 修改。

package/docs/codex-account.zh-CN.md

@@ -0,0 +1,38 @@
+# Codex 账号与限额
+
+Web 专用 Codex App Server 和 HCC 托管的 Codex Native worker 都提供“账号与限额”折叠面板。打开对应会话后读取该执行器的账号状态，点击“刷新账号与限额”重新查询。观察窗口也可以读取；发送消息、中断或应答审批仍受当前控制权约束。Claude 和 dsh 没有此 Codex 面板。
+
+## 状态怎么理解
+
+- **需要在本地 Codex 登录**：请在运行该任务的电脑完成 Codex 登录，再刷新面板。手机或另一台电脑上的 Web 登录不等于原执行器已登录。
+- **ChatGPT 已登录**：显示 App Server 报告的套餐及可获得的用量窗口、重置时间、可用额度状态。账号已识别不等于真实模型调用已经通过。
+- **供应商自行管理认证**：当前模型供应商不要求 OpenAI 登录。HCC 无法通过此接口确认供应商凭据或剩余配额，需通过该供应商的实际任务验证。
+- **暂不可用 / 此版本未提供限额**：数据缺失或接口不支持，不能理解成零用量或无限额度。API key 和自定义供应商不会显示推测的 ChatGPT 订阅配额。
+- **历史状态，待刷新**：执行器断开或读取失败时，旧用量保留并明确标记，不能作为当前状态。账号变更则清除旧账号的配额，再读当前账号。
+
+多个配额桶分别展示，缺失的窗口保持未知；已读取的 0% 用量会正常显示。界面同时标注账号和限额的读取时间。输出流、刷新和执行器替换不会让旧请求覆盖新状态；切走再返回后，过期响应被丢弃，刷新按钮可继续使用。
+
+## 读取范围
+
+两条公开入口都是需要 Web 认证的只读 GET；请求须携带现有 API 版本头 `X-HCC-API-Version: 2`：
+
+| 会话 | 入口 | 必须匹配的身份 |
+| --- | --- | --- |
+| Web 专用 Codex | `/api/sessions/:id/codex/account` | `root`、当前 `executorId` |
+| 原生 Codex worker | `/api/sessions/:id/native/account` | `root`、当前 `generation`、`owner`、`sessionId` |
+
+身份都通过 query 参数传入。原执行器在查询期间被替换时，响应重新核对身份；旧页面不能借此查询新实例。刷新不提交 turn、task、消息或 mutation receipt，不需要控制租约 token/epoch。
+
+底层仅调用 `account/read`（`refreshToken: false`），以及适用 ChatGPT 订阅时的 `account/rateLimits/read`。账号/限额通知更新当前执行器状态；登录完成通知仍需要读取当前账号后才能显示已登录。并发刷新合并为同一读取，账号变更与通知使旧响应失效。
+
+HCC 投影只保留必要状态。邮箱、凭据 ID、token、额度余额/支出和原始账号错误不进入面板、账号事件或接口响应；账号数据不写入浏览器存储。此功能不提供登录、退出登录、设备码登录、凭据保存或外部 token 刷新。执行器本身的认证生命周期仍由 Codex 管理。
+
+## 协议与验收边界
+
+基线为已安装 Codex 0.144.6；升级检查覆盖 57 项交接契约，其中包含本功能的方法、通知和必要字段。账号 Schema 从官方生成物的 `json-schema/v2/` 读取。运行方式见 [Codex 协议升级检查](codex-protocol.md)。
+
+真实安装版 App Server 已在隔离 HOME/CODEX_HOME 中分别验证 Web 和 Native 的未登录、自定义供应商状态，共 4 项；原执行器/会话保持不变，没有模型调用，也没有读取现有账号。桌面 1440×1000、手机 390×844 和观察窗口通过真实 HTTP/SQLite/JSON-RPC 的浏览器检查；ChatGPT 配额、多窗口、账号变更与不支持接口由模拟 provider 覆盖。这些结果不等于真实 ChatGPT 订阅限额或外部账号业务验收。
+
+浏览器验收入口为 `scripts/web-codex-account-acceptance.mjs --run --output NEW_RECEIPT`，需要通过 `HCC_ACCEPTANCE_PLAYWRIGHT` 和 `HCC_ACCEPTANCE_CHROME` 指定现有 Playwright 模块和 Chrome 可执行文件。脚本使用隔离项目、tmux、HOME/CODEX_HOME 和模拟 App Server，不调用模型；默认仅显示帮助。截图与 JSON 回执写到源码目录之外。
+
+官方接口参考：<https://developers.openai.com/codex/app-server/>。当前 HCC 未实现 `account/chatgptAuthTokens/refresh`；所验收的 0.144.6 生成 Schema 将 `chatgptAuthTokens` 登录模式标为内部使用，后续版本需按其实际生成协议重新评估。

package/docs/codex-protocol.md

@@ -0,0 +1,59 @@
+# Codex protocol generation and upgrade check / 协议升级检查
+
+HCC uses the installed Codex App Server over stdio for structured Web sessions
+and independent native workers. Before upgrading that executable, generate its
+own protocol and check the HCC subset:
+
+```sh
+npm run codex:protocol -- --codex-bin /absolute/path/to/codex --out /tmp/hcc-protocol-new
+```
+
+The output directory must not exist, and its parent must exist. Without `--out`,
+the script retains a new private temporary protocol directory and prints its
+path. From an installed package, the same command is:
+
+```sh
+node /absolute/path/to/hello-cc/scripts/codex-protocol.mjs --codex-bin /absolute/path/to/codex --out /tmp/hcc-protocol-new
+```
+
+The script uses isolated HOME/CODEX_HOME directories and runs only `--version`,
+`app-server generate-ts`, and `app-server generate-json-schema`. Both generators
+include `--experimental` because HCC's interactive thread configuration exposes
+experimental permission and user-input tools. It does not start an App Server,
+call a model, read an account, or modify login/trust configuration.
+
+The output contains:
+
+- `typescript/`: official generated TypeScript bindings.
+- `json-schema/`: official generated JSON Schema documents.
+- `manifest.json`: Codex version, commands, per-file SHA-256, bundle fingerprint,
+  57 HCC contract checks, and unsupported server requests.
+
+The check covers method availability, the thread/turn notifications consumed by
+HCC, human response fields and choices, MCP form/URL identity, and read-only account/quota methods, notifications and fields.
+Account schemas are read from the official `json-schema/v2/` directory. A missing
+contract or a new required response field returns exit code 1. Unsupported
+requests remain listed separately even when the supported subset passes.
+Optional fields do not fail this gate. It is a bounded compatibility check;
+it does not validate every nested request type, replace runtime validation,
+or prove transport/model/business acceptance. Keep the manifest and rerun the
+installed acceptance scripts before accepting a new Codex version.
+
+Official generator reference: <https://developers.openai.com/codex/app-server/>.
+The local official-protocol fixture in `test/fixtures/codex-protocol-0.144.6.json`
+was extracted from installed Codex 0.144.6 on 2026-10-03. It retains method
+registries and the relevant interaction and account schemas, rather than claiming that
+all generated methods are implemented.
+
+## 中文说明
+
+升级 Codex 前运行上述命令，生成的是指定已安装版本自身的协议。协议目录必须是
+新目录；工具不覆盖旧证据。生成物包括官方 TypeScript、JSON Schema 和带版本/
+文件指纹的检查清单。
+
+当前检查覆盖 57 项交接契约：客户端方法、轮次通知、人工答复字段/可选决策、
+MCP 表单/URL 请求身份，以及只读账号/限额的方法、通知和必要字段。账号 Schema
+从官方生成的 `json-schema/v2/` 读取。缺少方法、改变关键决策或新增 HCC 无法答复的必填字段时
+返回非零退出码。账号 token 刷新、动态工具、扩展验证等未接入请求会单独列出，
+不会因为生成成功而被视为已支持。该检查没有把运行时整体迁移为强类型协议，也不
+代表新版本已完成真实模型、外部账户授权、发布或设备验收。

package/docs/commands.md

@@ -14,36 +14,12 @@ authenticated access to any existing server directory are accepted risks.
 
 ```text
 hcc update [--tag TAG] [--registry URL] [--dry-run]
-hcc --root DIR migrate-state --offline --yes
 hcc uninstall [--purge --yes]
 ```
 
-`hcc update` updates the global npm install. If another OS user can replace a
-project path, managed state is kept in a private directory under the current
-user's home. Existing project-local `.hello-cc` data requires an explicit
-offline migration: stop all hello-cc and external writers first, then run
-`migrate-state --offline --yes`. It copies SQLite snapshots (including WAL
-contents) and other validated state, keeps the old directory untouched, and
-rebuilds managed DSH path-bound configuration. Do not restart an old writer
-against the retained directory. `hcc uninstall` removes local hooks, shims,
-and the shell PATH entry; add `--purge --yes` only when you also want to remove
-the selected current project's managed data and guidance blocks. A retained
-legacy migration source is not deleted by purge.
-Private-state creation and purge leave a durable authority marker so a retained
-or newly written project-local database cannot silently become active again.
-After purge, a remaining legacy directory still requires an explicit offline
-`migrate-state --offline --yes`; if no legacy directory remains, a fresh `init`
-creates new private state. If a private store disappears without an explicit
-purge, restore it from backup or use `uninstall --purge --yes` to deliberately
-discard the missing state before starting fresh.
-An interrupted private purge stays marked `purging`; normal access fails closed.
-After confirming old writers are stopped, repeat `uninstall --purge --yes` to
-finish deleting that private store. If the project root is replaced by a new
-directory at the same path, its inode no longer matches the old private binding.
-The CLI intentionally refuses automatic purge or rebinding: preserve and back
-up both the old private store and its `.authority.json` marker, stop all writers,
-and have an operator compare the old and new root identities before a manual
-recovery. Do not delete the marker alone or point the new root at the old data.
+`hcc update` updates the global npm install. `hcc uninstall` removes local
+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.
 
 ## Read-only Diagnostics
 
@@ -78,9 +54,18 @@ Use `--local` to bind only `127.0.0.1`, `--token` or `HCC_WEB_TOKEN` to set an
 explicit token, `HCC_RUNTIME_CA` to trust a private HTTPS Runtime API CA, and
 `--no-token` only in trusted local/test environments. Use `hcc up` only when you
 want coordination without the Web console or shims. Provider shims only join
-projects with a managed `runtime.json` from `hcc web`; they do not use a
+projects with a local `.hello-cc/runtime.json` from `hcc web`; they do not use a
 global runtime to manage arbitrary directories.
 
+One browser can sign in to multiple Web instances on different listener ports
+of the same host without refresh or logout replacing another instance's login.
+Cookie names use the protocol and actual listener port, or the fixed
+`--proxy-origin` protocol and port behind a trusted reverse proxy. Sign in again
+after upgrading; legacy cookies are neither reused nor cleared. This prevents
+accidental collisions and is not a browser security boundary. When separate SSH
+tunnels map the same remote listener port to different local ports, use separate
+browser profiles or hostnames: the direct listener cannot identify that mapping.
+
 ## Native Workers
 
 ```text

package/docs/commands.zh-CN.md

@@ -12,28 +12,12 @@ unknown 证据获得 120 秒宽限；历史清理必须显式使用 `gc --histor
 
 ```text
 hcc update [--tag TAG] [--registry URL] [--dry-run]
-hcc --root 目录 migrate-state --offline --yes
 hcc uninstall [--purge --yes]
 ```
 
-`hcc update` 更新全局 npm 安装。如果其他系统用户可替换项目路径，受管状态会放在
-当前用户 home 下的私有目录。已有项目本地 `.hello-cc` 必须离线迁移：先停止
-所有 hello-cc 进程和外部写入者，再显式执行 `migrate-state --offline --yes`。
-迁移会复制包含 WAL 内容的 SQLite 快照和其他经检查的状态，保留原目录，
-并重建由 hello-cc 管理且绑定旧绝对路径的 DSH 配置。不要让旧版写入者继续写原目录。
-`hcc uninstall` 移除本机 hooks、shims 和 shell PATH 配置；只有在确定也要删除
-当前项目选定的受管数据和指导块时，才加 `--purge --yes`。迁移后保留的旧目录
-不会被 purge 删除。
-新建或 purge 私有数据后仍保留持久的权威标记，防止保留或后来写入的项目本地数据库
-自动重新生效。purge 后若旧目录仍在，必须停止所有旧写入者并显式执行
-`migrate-state --offline --yes`；若旧目录已不存在，可重新运行 `init` 创建新的私有
-状态。如果私有目录未经 purge 就丢失，请从备份恢复，或通过
-`uninstall --purge --yes` 明确放弃已丢失的状态后重新初始化。
-私有状态的 purge 若中断，会保留 `purging` 标记并拒绝正常访问。确认旧写入者均已停止后，
-再次运行 `uninstall --purge --yes` 完成删除。若项目根目录在同一路径被新目录替换，
-新 inode 与旧私有绑定不符；CLI 会拒绝自动 purge 或重绑。请先保留并备份旧私有状态目录
-及其 `.authority.json` 标记，停止所有写入者，由管理员核对新旧根目录身份后再人工恢复。
-不要只删除标记，也不要让新根目录直接使用旧数据。
+`hcc update` 更新全局 npm 安装。`hcc uninstall` 移除本机 hooks、shims 和 shell PATH 配置；
+只有在确定也要删除当前项目的 `.hello-cc` 数据和指导块时，才加
+`--purge --yes`。
 
 ## 只读诊断
 
@@ -64,9 +48,16 @@ runtime 生成 URL token。用 `--local` 可只绑定 `127.0.0.1`，用 `--token
 `HCC_WEB_TOKEN` 可设置显式 token；私有 HTTPS Runtime API CA 用
 `HCC_RUNTIME_CA` 指定。只有在可信本地/测试环境才使用 `--no-token`。
 只想使用本地协作、不需要 Web 或 shims 时，再使用 `hcc up`。provider shim 只会加入
-已经由 `hcc web` 生成受管 `runtime.json` 的项目，不会使用全局 runtime
+已经由 `hcc web` 生成本地 `.hello-cc/runtime.json` 的项目，不会使用全局 runtime
 去管理任意目录。
 
+同一浏览器可以登录同一主机上不同监听端口的多个 Web 实例，刷新或退出其中
+一个不会覆盖另一个的登录。Cookie 按协议与实际监听端口命名；可信反向代理
+使用固定 `--proxy-origin` 的协议与端口。升级后需重新登录，旧版 Cookie 不会
+被复用或清除。这用于避免实例间的意外覆盖，不是浏览器安全隔离边界。
+若多个 SSH 隧道把相同的远端监听端口映射到不同本地端口，应使用独立浏览器
+配置文件或不同主机名；服务端无法从直连配置识别此端口映射。
+
 ## Native 后台 worker
 
 ```text