@logicseek/hello-cc 0.1.8 → 1.0.0

package/CHANGELOG.md

@@ -16,6 +16,123 @@ the release description from the current changelog section. Use
 `npm run release:github` with `GH_TOKEN` or `GITHUB_TOKEN` only for local
 backfills.
 
+## 1.0.0
+
+### Summary
+
+hello-cc 1.0.0 is a breaking data, identity, and Runtime API release. It makes
+process identity the authority for session liveness, bounds unknown evidence,
+and hardens browser terminal control and technical-state cleanup.
+
+### Highlights
+
+- Process identity now controls live/dead decisions across tmux and ordinary
+  child processes, including sleep, detach, PID reuse, and stale status rows.
+- Browser credentials, trusted proxy headers, Runtime API TLS, and buffer GC
+  all have narrower, tested authority boundaries.
+
+### Breaking Changes
+
+- Databases upgrade to schema v7. Downgrading a migrated database is not
+  supported. Before migration, hello-cc creates a verified
+  `<db>.pre-v<from>-to-v7.<timestamp>.<suffix>.bak` snapshot; stop all hello-cc
+  processes and validate the backup with SQLite `quick_check` before any manual
+  recovery. At most five strictly named backups are retained per database; the
+  recovery procedure is documented in the user guide.
+- Provider peer IDs now hash the complete provider session value. Existing
+  pre-v1 provider IDs and bindings are left unchanged: there is no automatic
+  alias, graph rewrite, or migration to the new ID.
+- Protected HTTP and WebSocket operations require Runtime API v2. Browser
+  terminal write tokens are issued per WebSocket connection and revoked when
+  that connection closes.
+
+### Security And Reliability
+
+- Live tmux and non-tmux sessions are decided from immutable process evidence;
+  sleep and tmux detachment do not mark a live process dead. Unknown evidence
+  receives at most 120 seconds of grace, while confirmed dead owners expire.
+- Generated Web access tokens are scoped to one runtime and are not persisted.
+  HTTPS runtime overrides use normal certificate verification; set
+  `HCC_RUNTIME_CA` to a CA file for a private or self-signed endpoint.
+- `--trust-proxy` now requires `--proxy-origin https://host[:port]`; forwarded
+  scheme and host must match that fixed origin and arrive from loopback.
+- Garbage collection keeps task/message/event/handoff history unless
+  `hcc gc --history --yes` is explicitly requested. Buffer deletion rechecks
+  producer evidence and leases immediately before each bounded batch.
+
+### Accepted Risks
+
+- The default Web listener remains `0.0.0.0` over plaintext HTTP for trusted
+  LAN use. The token controls access but does not provide transport encryption;
+  use `--tls` or a pinned TLS reverse proxy when the network is not trusted.
+- An authenticated browser may select any existing server directory as a
+  project root. This is intentional for the operator console and is not a
+  project-root sandbox or tenant boundary.
+
+### Validation
+
+The release gate requires Node 24 unit and full regression tests, package import
+closure checks, a fresh Docker build, and three consecutive container runs that
+end with `FULL_REGRESSION_OK`.
+
+## 0.1.9
+
+### Summary
+
+hello-cc 0.1.9 publishes the post-0.1.8 Web runtime and provider shim
+hardening work. It tightens Web peer action identity, makes runtime cleanup
+safer, and keeps Claude/Codex shims from attaching unrelated projects to a
+global Web runtime.
+
+### Highlights
+
+- Hardened Web runtime cleanup so starting `hcc web` from a wrapper shell does
+  not terminate the current parent process chain while still removing stale
+  orphan runtimes for the same project.
+- Returned structured `BAD_REQUEST` JSON for malformed Web API request bodies
+  instead of surfacing raw JSON parse failures.
+- Replaced Web-runtime-token reuse for mutating peer actions with independent
+  per-session action tokens.
+- Changed provider shims to fall back to the real Claude/Codex CLI when no
+  current-project Web runtime is available.
+- Made provider shims use only the current project's `.hello-cc/runtime.json`
+  during managed launches, avoiding accidental attachment through a global Web
+  runtime from another project.
+- Kept shim-only environment variables out of restarted provider sessions.
+
+### Compatibility Notes
+
+- No breaking CLI command changes are intended in this release.
+- `hcc web --local` is still Web mode; use `hcc up` when you only want local
+  coordination commands without the Web console or shims.
+- Starting `claude` or `codex` in a directory without a local
+  `.hello-cc/runtime.json` now runs the real provider CLI instead of implicitly
+  using a global hello-cc Web runtime.
+
+### Validation
+
+The 0.1.9 release should be validated with:
+
+```bash
+git diff --check
+node --check bin/hcc.mjs
+find lib -name '*.mjs' -print0 | xargs -0 -n1 node --check
+node --check scripts/github-release.mjs
+node --check scripts/regression.mjs
+node --check scripts/release-notes.mjs
+npm run release:check
+npm run release:github:dry-run -- --version 0.1.9
+npm pack --dry-run --json
+npm publish --dry-run --registry=https://registry.npmjs.org/ --access public
+npm test
+```
+
+The expected full regression marker is:
+
+```text
+FULL_REGRESSION_OK
+```
+
 ## 0.1.8
 
 ### Summary

package/README.md

@@ -30,6 +30,20 @@ It is built for developers who run multiple AI coding agents in the same repo
 and need them to coordinate instead of guessing what the other sessions are
 doing.
 
+## v1 Compatibility And Trust Model
+
+Version 1.0.0 upgrades project databases to schema v7 after creating a verified
+pre-migration backup; downgrading that database is unsupported. Provider peer
+IDs now hash the full provider session value and old IDs are not remapped.
+Runtime API v2 and per-connection terminal action tokens are required.
+
+Liveness follows tmux/non-tmux process evidence: sleep or detachment does not
+kill a live session, and only unknown evidence receives the bounded 120-second
+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.
+
 ## Highlights
 
 - **Shared project memory**: peers, tasks, messages, locks, handoffs, and
@@ -94,19 +108,22 @@ hcc web
 ```
 
 Then open the printed URL. By default, `hcc web` listens on LAN interfaces and
-requests `0.0.0.0:8787`, using a saved URL token generated on first use. If
+requests `0.0.0.0:8787`, using a token generated for that runtime. If
 port 8787 is already busy and you did not pass `--port`, it automatically tries
 the next available port. The command prints both the LAN login URL and the local
 loopback URL:
 
 ```text
-open: http://<machine-ip>:8787/?token=<saved-token>&project=/path/to/project
-local: http://127.0.0.1:8787/?token=<saved-token>&project=/path/to/project
+open: http://<machine-ip>:8787/?token=<runtime-token>&project=/path/to/project
+local: http://127.0.0.1:8787/?token=<runtime-token>&project=/path/to/project
 ```
 
 Use `--local` to bind only to `127.0.0.1`, or `--port N` to request a specific
 port. `hcc web` initializes the project bus, installs Claude/Codex hooks and
 shims, starts or reuses the Web console, and returns the terminal to you.
+`hcc web --local` is still Web mode; it only limits the listener to loopback.
+Use `hcc up` when you want local coordination commands without the Web console
+or shims.
 
 After the first shim install, open a new terminal or reload the rc file for
 your shell:
@@ -125,13 +142,18 @@ codex resume <session-id>
 ```
 
 Those sessions become tmux-backed peers that can be seen and controlled from
-Web while remaining usable from the local terminal.
+Web while remaining usable from the local terminal. The shims only use the
+current project's runtime file. If you start `claude` or `codex` in a directory
+where `hcc web` has not created `.hello-cc/runtime.json`, the shim falls back to
+the real provider CLI instead of using the global Web runtime or creating a new
+project database.
 
 ## Basic Workflow
 
 ```bash
 hcc task create --title "Review router changes" --priority 20
 hcc task next
+hcc task running --id 1 --summary "Started"
 hcc lock acquire --resource src/router --ttl 900 --reason "edit router"
 hcc status
 hcc handoff create --summary "Router change ready for review" --tests "npm test"

package/README.zh-CN.md

@@ -25,6 +25,19 @@
 
 它适合在同一个仓库里同时运行多个 AI 编程 agent 的场景：让它们知道彼此在做什么，而不是各自猜测。
 
+## v1 兼容性与信任边界
+
+1.0.0 会在生成并校验升级前备份后，把项目数据库升级到 schema v7；升级后的
+数据库不支持降级。provider peer ID 改为对完整 provider session 值做哈希，旧 ID
+不会自动映射或迁移。受保护的接口使用 Runtime API v2，终端 action token 按
+WebSocket 连接签发和撤销。
+
+存活判断以 tmux/非 tmux 进程证据为准：休眠或 detach 不会把活进程判死，只有
+unknown 证据获得最长 120 秒宽限。`hcc gc` 默认保留历史，必须显式使用
+`--history`。`--tls` 提供传输加密；`--trust-proxy` 必须固定
+`--proxy-origin`。两项风险是有意保留的：默认在可信内网以明文 HTTP 监听
+`0.0.0.0`，且已认证浏览器可以选择服务器上任意已存在目录。
+
 ## 特色
 
 - **项目本地共享状态**：peers、tasks、messages、locks、handoffs 和 events 写入 `<project>/.hello-cc/mesh.db`。
@@ -82,18 +95,20 @@ hcc web
 ```
 
 然后打开命令输出里的 URL。默认情况下，`hcc web` 会监听内网地址，请求
-`0.0.0.0:8787`，并在 URL 里附带首次自动生成并保存的稳定 token。如果 8787
+`0.0.0.0:8787`，并在 URL 里附带为本次 runtime 自动生成的 token。如果 8787
 端口已被占用，且你没有显式传 `--port`，它会自动尝试后续可用端口。启动时会同时
 打印内网登录地址和本机 loopback 地址：
 
 ```text
-open: http://<machine-ip>:8787/?token=<saved-token>&project=/path/to/project
-local: http://127.0.0.1:8787/?token=<saved-token>&project=/path/to/project
+open: http://<machine-ip>:8787/?token=<runtime-token>&project=/path/to/project
+local: http://127.0.0.1:8787/?token=<runtime-token>&project=/path/to/project
 ```
 
 使用 `--local` 可以只绑定 `127.0.0.1`，使用 `--port N` 可以指定请求端口。
 `hcc web` 会初始化项目总线，安装 Claude/Codex hooks 和 shims，启动或复用 Web
 控制台，然后把终端还给你。
+`hcc web --local` 仍然是 Web 模式，只是限制监听在本机 loopback。只想使用本地
+协作命令、不启动 Web 控制台、不安装 shims 时，使用 `hcc up`。
 
 第一次安装 shim 后，打开新终端，或根据当前 shell 重新加载配置：
 
@@ -111,12 +126,16 @@ codex resume <session-id>
 ```
 
 这些会话会成为 tmux-backed peer，可以继续在本地终端里使用，也可以被 Web 控制台观察和操作。
+shim 只使用当前项目自己的 runtime 文件。如果你在没有通过 `hcc web` 创建
+`.hello-cc/runtime.json` 的目录里启动 `claude` 或 `codex`，shim 会回退到真实
+provider CLI，不会使用全局 Web runtime，也不会为这个目录新建项目数据库。
 
 ## 基本流程
 
 ```bash
 hcc task create --title "Review router changes" --priority 20
 hcc task next
+hcc task running --id 1 --summary "Started"
 hcc lock acquire --resource src/router --ttl 900 --reason "edit router"
 hcc status
 hcc handoff create --summary "Router change ready for review" --tests "npm test"