@logicseek/hello-cc 0.1.9 → 1.0.1

package/CHANGELOG.md

@@ -16,6 +16,142 @@ 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.1
+
+### Summary
+
+hello-cc 1.0.1 is a file-lock determinism, buffer-GC safety, fresh-install, and
+release-reliability patch. It makes worker shutdown reclaim kernel lock
+endpoints deterministically when an identity probe keeps its client write half
+open, restores real PTY startup in fresh macOS npm installations, and keeps
+automatic GC fail-closed when optional buffer paths disappear or change.
+
+### Highlights
+
+- The socket-lock worker now tracks each locally accepted socket and destroys
+  those accepted handles during server shutdown, so release no longer depends
+  on the peer closing its writable half after reading the lock banner.
+- A real half-open identity-probe regression verifies that release returns
+  promptly, a nonblocking reacquisition succeeds immediately, and the probe is
+  explicitly stopped and awaited during final cleanup.
+- `node-pty` is exactly pinned to `1.2.0-beta.15`. The stable `node-pty 1.1.0`
+  npm artifact contains non-executable Darwin helpers, which makes a fresh
+  macOS install fail with `posix_spawnp failed`; the selected artifact publishes
+  both Darwin helpers with executable modes.
+- Linux, macOS, and WSL installation instructions now list Node.js 24, tmux
+  commands for the major system package managers, CLI verification, and safe
+  handling for npm global-install permission errors.
+- `hcc down` now waits for the exact Runtime process identity to exit before it
+  reports success, including safe handling for PID reuse and a bounded timeout
+  when shutdown cannot be confirmed.
+- Background Web startup keeps its immediate child-exit failure but allows a
+  bounded 60-second health window, avoiding false failures on loaded macOS CI
+  hosts where process identity and project restoration can exceed 30 seconds.
+- Manual buffer GC allows a bounded 30-second window for runtime evidence
+  planning and apply, while still deferring all eligible files if the runtime
+  remains unavailable.
+- Automatic GC now treats a missing `.hello-cc/bufs` leaf as empty without
+  recreating it. A missing state directory, a symlinked path component, an
+  inode replacement, or a retargeted project-root alias fails closed with
+  `PROJECT_PATH_FORBIDDEN` before buffer, clock, lock, or history mutation.
+- Buffer path identity is retained through evidence collection, lease
+  acquisition, planning, clock reads, and database transactions. GC uses a
+  no-create lease while existing file-lock callers retain their original
+  parent-creation behavior.
+- Per-connection Web action tokens now require their issuing terminal socket to
+  still be open, closing the handshake race before asynchronous token cleanup.
+- Runtime request deadlines now reach the underlying HTTP transport, and peer
+  start/attach preflight and mutation requests use a bounded 60-second window
+  while stop and terminal-input operations use 30 seconds, instead of all
+  inheriting the shorter read-request default.
+
+### Compatibility Notes
+
+- No CLI command or package-surface behavior changes are intended. Schema v7,
+  Runtime API v2, the authenticated browser's ability to choose any existing
+  server directory as a project root, and the 1.0.0 accepted-risk boundaries
+  are unchanged.
+- Stable project-root aliases remain supported. Only path disappearance,
+  replacement, symlink traversal, or alias retargeting during GC is rejected.
+- The existing five-second fail-closed deadline and cleanup-error behavior are
+  unchanged.
+- `node-pty@1.2.0-beta.15` is a bounded prerelease dependency risk. The exact
+  pin prevents unreviewed beta movement, and release tests verify the installed
+  version, regular-file identity, executable modes, and a real PTY. There is no
+  postinstall or CI-only `chmod` workaround.
+
+### Validation
+
+The 1.0.1 release gate includes repeated macOS Node 24 tests; a no-cache Linux
+Node 24/tmux image build followed by three complete `npm test` runs in that same
+image, each ending with `FULL_REGRESSION_OK`; and a fourth clean container that
+installs the same 1.0.1 package tarball and passes PTY, database, Web, and
+missing-buffer GC smoke checks. Fresh macOS consumer installs pass both normal
+and `--ignore-scripts` installation, proving that executable helper modes come
+from the package artifact rather than lifecycle-script mutation. GC regression
+coverage includes absent optional leaves, symlink and ancestor replacement,
+alias retargeting, no-create lock acquisition, and path guards around clock and
+history writes.
+
+## 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

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
@@ -56,10 +70,42 @@ currently supported; use WSL for a Linux-like environment.
 Linux has richer process auto-discovery through `/proc`. On macOS, use
 hello-cc shims or `hcc peer start` for reliable tmux-managed terminal sessions.
 
+Install Node.js 24 or newer from the official Node.js packages or a Node
+version manager. Then install `tmux` for your platform:
+
+```bash
+# Debian / Ubuntu
+sudo apt-get update && sudo apt-get install -y tmux
+# Fedora / RHEL
+sudo dnf install -y tmux
+# Older RHEL / CentOS
+sudo yum install -y tmux
+# Alpine
+sudo apk add tmux
+# Arch Linux
+sudo pacman -S --needed tmux
+# openSUSE
+sudo zypper install tmux
+# macOS only
+brew install tmux
+```
+
+On Linux, use the distribution package manager; Homebrew is only the macOS
+command above. Root shells can omit `sudo`. In WSL, run the matching Linux
+distribution commands inside WSL. Then install and verify hello-cc:
+
 ```bash
 npm install -g @logicseek/hello-cc
+node --version
+npm --version
+tmux -V
+hcc --version
+hcc --help
 ```
 
+If npm reports `EACCES`, use a Node version manager or a user-owned npm prefix;
+do not work around it with `sudo npm install -g`.
+
 Update an existing global install:
 
 ```bash
@@ -94,14 +140,14 @@ 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
@@ -139,6 +185,7 @@ project database.
 ```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`。
@@ -44,10 +57,41 @@ hello-cc 支持 Linux 和 macOS。需要 Node.js 24 或更新版本；可被浏
 Linux 可以通过 `/proc` 做更完整的进程自动发现。macOS 上建议通过 hello-cc
 shim 或 `hcc peer start` 启动会话，以获得可靠的 tmux 托管终端。
 
+先通过 Node.js 官方软件包或 Node 版本管理器安装 Node.js 24 或更新版本，再按
+系统安装 `tmux`：
+
+```bash
+# Debian / Ubuntu
+sudo apt-get update && sudo apt-get install -y tmux
+# Fedora / RHEL
+sudo dnf install -y tmux
+# 旧版 RHEL / CentOS
+sudo yum install -y tmux
+# Alpine
+sudo apk add tmux
+# Arch Linux
+sudo pacman -S --needed tmux
+# openSUSE
+sudo zypper install tmux
+# 仅 macOS
+brew install tmux
+```
+
+Linux 必须使用当前发行版的系统包管理器，而不是 Homebrew。root shell 可以省略
+`sudo`。WSL 用户应在 WSL 内部执行对应 Linux 发行版的命令。然后安装并验证：
+
 ```bash
 npm install -g @logicseek/hello-cc
+node --version
+npm --version
+tmux -V
+hcc --version
+hcc --help
 ```
 
+如果 npm 报 `EACCES`，请使用 Node 版本管理器或用户自有的 npm prefix，不要用
+`sudo npm install -g` 绕过权限问题。
+
 更新已有的全局安装：
 
 ```bash
@@ -82,13 +126,13 @@ 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` 可以指定请求端口。
@@ -122,6 +166,7 @@ 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"