@logicseek/hello-cc 0.1.9 → 1.0.0

package/docs/README.md

@@ -3,6 +3,14 @@
 Start with the [project README](../README.md) when you only need the project
 summary and first command. Use these docs when you need more detail.
 
+The 1.0.0 contract is breaking: schema v7 has no downgrade path, migrations
+create a verified backup, provider peer IDs changed without legacy remapping,
+and protected routes use Runtime API v2. Process evidence controls liveness and
+only unknown evidence gets 120 seconds of grace; `gc --history` is opt-in.
+Use `--tls` directly, or `--trust-proxy` with a fixed `--proxy-origin`.
+Plaintext LAN operation and
+authenticated selection of any existing server directory are accepted risks.
+
 ## User Docs
 
 - [User Guide](guide.md): install, start, Web console, coordination semantics,

package/docs/README.zh-CN.md

@@ -3,6 +3,12 @@
 只需要项目简介和第一条命令时，先看[仓库 README](../README.zh-CN.md)。
 需要更多细节时，再看下面的文档。
 
+1.0.0 是 breaking release：schema v7 不支持降级，迁移前会生成并校验备份；
+provider peer ID 已变更且不会映射旧 ID；受保护接口使用 Runtime API v2。存活由
+进程证据决定，只有 unknown 证据获得 120 秒宽限；`gc --history` 必须显式启用。
+可以直接使用 `--tls`，或让 `--trust-proxy` 固定 `--proxy-origin`。默认可信内网明文监听，以及已认证
+浏览器可选择服务器上任意已存在目录，是明确接受的风险。
+
 ## 用户文档
 
 - [用户指南](guide.zh-CN.md)：安装、启动、Web 控制台、协作语义、工作流、稳定

package/docs/architecture.md

@@ -31,19 +31,29 @@ architectural idea: split by boundary, not by convenience.
 
 ## Current Pressure Points
 
-The codebase has already extracted many focused modules under `lib/`, including
-schema, runtime state, task/message stores, peer identity, provider command
-building, tmux helpers, Web HTTP helpers, and render helpers.
+The 2026-08 monolith split is complete: `bin/hcc.mjs` is a thin entrypoint that
+imports `lib/cli/app.mjs`. All composition (constants, shared helpers, command
+factory wiring, dispatch, `main()`) lives in `lib/cli/app.mjs`; command groups
+live in `lib/cli/commands/`; GC lives in `lib/cli/commands/gc.mjs` plus
+`lib/core/coordination/gc-plan.mjs`; runtime evidence helpers live in
+`lib/core/peers/evidence-runtime.mjs`.
+
+The former 3100-line `cmdWeb()` closure is fully decomposed into `lib/web/`
+subsystem modules, each behind a `create*(deps)` factory:
+`project-contexts.mjs`, `external-sessions.mjs`, `liveness-reaper.mjs`,
+`buffer-gc-runtime.mjs`, `tmux-sessions.mjs`, `auto-attach.mjs`,
+`pty-sessions.mjs`, `http-routes.mjs`, `startup.mjs`, `cookie-auth.mjs`,
+`session-serialize.mjs`, `tmux-stream.mjs`. `runtime-main.mjs` is now the
+composition root (option parsing, factory wiring in dependency order, the
+WebSocket terminal handler, server setup, and shutdown).
 
 The remaining structural pressure is mostly:
 
-- `bin/hcc.mjs` still contains command dispatch, command handlers, Web server
-  setup, HTTP routes, WebSocket terminal handling, tmux session management, PTY
-  session management, external buffer adoption, and shutdown cleanup.
-- `cmdWeb()` is the largest mixed boundary. It should be treated as a Web
-  runtime subsystem, not as a normal CLI command body.
 - `scripts/regression.mjs` is a valuable full regression gate, but it should
   eventually become a runner over domain-specific regression modules.
+- `lib/web/tmux-sessions.mjs` is the largest subsystem module (~1300 lines);
+  its kill/rebind planning could split further once tmux GC command handling
+  and session lifecycle settle.
 
 ## Target Layout
 
@@ -174,10 +184,11 @@ scripts/
 
 ## Boundary Rules
 
-`bin/hcc.mjs` should become a thin entrypoint. It may parse global arguments,
-create the root context, invoke dispatch, and convert top-level errors to CLI
-output. It should not own Web routing, DB schema, tmux streaming, provider
-command construction, or task state machines.
+`bin/hcc.mjs` is a thin entrypoint: it imports `runCli()` from
+`lib/cli/app.mjs` and nothing else. Argument parsing, context creation,
+dispatch, and top-level error conversion live in `lib/cli/app.mjs`. Neither
+file should own Web routing, DB schema, tmux streaming, provider command
+construction, or task state machines.
 
 `lib/cli/` owns command parsing and command handlers. A command handler can
 open a database, call stores or core services, and print results. It should not
@@ -295,13 +306,13 @@ npm package contents stable unless the task explicitly says otherwise.
    `messages`, `help`, `state-render`, and release helpers. Keep compatibility
    re-export files temporarily if the import churn becomes too large.
 
-3. Split the Web runtime by subsystem.
-   Extract project selection, session manager, Web routes, WebSocket terminal
-   handling, tmux stream, PTY session, and external buffer adoption from
-   `cmdWeb()` in separate commits.
+3. Split the Web runtime by subsystem. (Done in 2026-08: twelve subsystem
+   modules under `lib/web/`, each behind a `create*(deps)` factory;
+   `runtime-main.mjs` is the composition root with the WebSocket terminal
+   handler and shutdown.)
 
-4. Make `bin/hcc.mjs` a thin entrypoint.
-   Move dispatch and command groups under `lib/cli/commands/`.
+4. Make `bin/hcc.mjs` a thin entrypoint. (Done in 2026-08: 6 lines, delegating
+   to `lib/cli/app.mjs`; command groups live under `lib/cli/commands/`.)
 
 5. Split regression tests by domain.
    Keep `npm test` as the single full regression command, but make it call

package/docs/architecture.zh-CN.md

@@ -31,13 +31,22 @@ store、hooks、config、execution adapter 分开。hello-cc 不需要 Rust crat
 store、peer identity、provider command builder、tmux helper、Web HTTP helper
 和 render helper。
 
+2026-08 的单体拆分已完成：`bin/hcc.mjs` 是薄入口（6 行），只导入
+`lib/cli/app.mjs`。全部装配（常量、共享助手、命令工厂接线、dispatch、
+`main()`）在 `lib/cli/app.mjs`；命令组在 `lib/cli/commands/`；Web runtime 在
+`lib/web/`（startup、runtime-main、cookie-auth、session-serialize、
+tmux-stream）；GC 在 `lib/cli/commands/gc.mjs` 与
+`lib/core/coordination/gc-plan.mjs`；运行时证据助手在
+`lib/core/peers/evidence-runtime.mjs`。
+
 剩余结构压力主要在：
 
-- `bin/hcc.mjs` 仍包含 command dispatch、command handler、Web server setup、
-  HTTP routes、WebSocket terminal、tmux session 管理、PTY session 管理、
-  external buffer adoption 和 shutdown cleanup。
-- `cmdWeb()` 是最大的混合边界。它应该被视为 Web runtime 子系统，而不是普通
-  CLI command body。
+- （已于 2026-08 完成）原 3100 行 `cmdWeb()` 闭包已全部分解为 `lib/web/` 下的
+  子系统模块，各自通过 `create*(deps)` 工厂注入依赖：project-contexts、
+  external-sessions、liveness-reaper、buffer-gc-runtime、tmux-sessions、
+  auto-attach、pty-sessions、http-routes、startup、cookie-auth、
+  session-serialize、tmux-stream。`runtime-main.mjs` 现在是组合根（参数解析、
+  按依赖序装配工厂、WebSocket 终端处理、server 搭建与 shutdown）。
 - `scripts/regression.mjs` 是有价值的全量回归入口，但后续应该变成一个调用领域
   regression module 的 runner。
 
@@ -170,9 +179,10 @@ scripts/
 
 ## 边界规则
 
-`bin/hcc.mjs` 应该变成很薄的入口。它可以解析全局参数、创建 root context、调用
-dispatch，并把顶层错误转换为 CLI 输出。它不应该拥有 Web routing、DB schema、
-tmux streaming、provider command construction 或 task state machine。
+`bin/hcc.mjs` 是薄入口：只从 `lib/cli/app.mjs` 导入 `runCli()`。参数解析、
+context 创建、dispatch 和顶层错误转换都在 `lib/cli/app.mjs`。两个文件都
+不应该拥有 Web routing、DB schema、tmux streaming、provider command
+construction 或 task state machine。
 
 `lib/cli/` 负责命令解析和命令处理器。命令处理器可以打开数据库、调用 store 或
 core service，并打印结果。当逻辑可以放进 `core`、`runtime`、`terminal`、`web`
@@ -283,8 +293,8 @@ release -> shared
    分提交从 `cmdWeb()` 抽出 project selection、session manager、Web routes、
    WebSocket terminal、tmux stream、PTY session 和 external buffer adoption。
 
-4. 让 `bin/hcc.mjs` 变成薄入口。
-   把 dispatch 和 command groups 移到 `lib/cli/commands/`。
+4. 让 `bin/hcc.mjs` 变成薄入口。（2026-08 已完成：6 行，委托给
+   `lib/cli/app.mjs`；命令组在 `lib/cli/commands/`。）
 
 5. 按领域拆 regression。
    保持 `npm test` 是唯一全量回归命令，但让它调用 `scripts/regression/` 下的

package/docs/commands.md

@@ -4,6 +4,12 @@ Use `hcc --help` for the current top-level command list. Most subcommands also
 accept `--help`, for example `hcc update --help`, `hcc peer --help`, and
 `hcc task --help`.
 
+Version 1.0.0 uses schema v7 (no downgrade), verified pre-migration backups,
+new full-session provider peer IDs without old-ID remapping, and Runtime API v2.
+Process evidence controls liveness with 120 seconds only for unknown evidence;
+history cleanup requires `gc --history`. The default plaintext LAN listener and
+authenticated access to any existing server directory are accepted risks.
+
 ## Install Maintenance
 
 ```text
@@ -18,16 +24,16 @@ current project's `.hello-cc` data and guidance blocks.
 ## Start And Stop
 
 ```text
-hcc web [--host HOST] [--port N] [--token TEXT] [--local] [--no-token] [--no-discover] [--no-guidance]
+hcc web [--host HOST] [--port N] [--token TEXT] [--local] [--tls] [--trust-proxy --proxy-origin ORIGIN] [--no-token] [--no-discover] [--no-guidance]
 hcc down
 hcc up [--no-discover] [--no-guidance]
 ```
 
 `hcc web` is the default entry. It initializes coordination, installs hooks and
 shims, starts or reuses the Web console, and returns the terminal to you. Bare
-`hcc web` listens on `0.0.0.0` and uses a saved URL token, generating one on
-first use. Use `--local` to bind only `127.0.0.1`, `--token` or `HCC_WEB_TOKEN`
-to replace the saved token, and
+`hcc web` listens on `0.0.0.0` and generates a URL token for that runtime.
+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 local `.hello-cc/runtime.json` from `hcc web`; they do not use a
@@ -103,6 +109,7 @@ hcc task takeover [--peer ID] --id N --reason TEXT [--policy any|blocked|stale|b
 hcc task next [--peer ID] [--force] [--count N]
 hcc task create --title TEXT --parent N [--team-role ROLE]
 hcc task update [--peer ID] --id N --status running|review|blocked|done|abandoned [--summary TEXT] [--body TEXT] [--to ID]
+hcc task running|review|blocked|abandoned [--peer ID] --id N [--summary TEXT] [--body TEXT] [--to ID]
 hcc task done [--peer ID] --id N --summary TEXT
 ```
 
@@ -121,6 +128,8 @@ another owner; it records the previous owner, requires a reason, and notifies
 them. Add `--policy blocked`, `stale`, or `blocked-or-stale` when takeover
 should only proceed under that auditable precondition. The default policy is
 `any` for compatibility.
+Use `task running`, `task review`, `task blocked`, or `task abandoned` as
+shortcuts for `task update --status STATUS`.
 
 ## Teams
 

package/docs/commands.zh-CN.md

@@ -3,6 +3,11 @@
 使用 `hcc --help` 查看当前顶层命令列表。大多数子命令也支持 `--help`，
 例如 `hcc update --help`、`hcc peer --help` 和 `hcc task --help`。
 
+1.0.0 使用 schema v7（不支持降级）、经校验的迁移前备份、不会映射旧 ID 的
+完整 session provider peer ID，以及 Runtime API v2。进程证据决定存活，只有
+unknown 证据获得 120 秒宽限；历史清理必须显式使用 `gc --history`。默认可信
+内网明文监听和已认证浏览器访问任意已存在服务器目录，是明确接受的风险。
+
 ## 安装维护
 
 ```text
@@ -17,15 +22,16 @@ hcc uninstall [--purge --yes]
 ## 启动和停止
 
 ```text
-hcc web [--host HOST] [--port N] [--token TEXT] [--local] [--no-token] [--no-discover] [--no-guidance]
+hcc web [--host HOST] [--port N] [--token TEXT] [--local] [--tls] [--trust-proxy --proxy-origin ORIGIN] [--no-token] [--no-discover] [--no-guidance]
 hcc down
 hcc up [--no-discover] [--no-guidance]
 ```
 
 `hcc web` 是默认入口。它会初始化协作状态，安装 hooks 和 shims，启动或复用
-Web 控制台，然后把终端还给你。裸 `hcc web` 会监听 `0.0.0.0` 并使用固定
-URL token；首次使用时自动生成并保存。用 `--local` 可只绑定 `127.0.0.1`，
-用 `--token` 或 `HCC_WEB_TOKEN` 可替换保存的 token，只有在可信本地/测试环境才使用 `--no-token`。
+Web 控制台，然后把终端还给你。裸 `hcc web` 会监听 `0.0.0.0`，并为本次
+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` 生成本地 `.hello-cc/runtime.json` 的项目，不会使用全局 runtime
 去管理任意目录。
@@ -96,6 +102,7 @@ hcc task takeover [--peer ID] --id N --reason TEXT [--policy any|blocked|stale|b
 hcc task next [--peer ID] [--force] [--count N]
 hcc task create --title TEXT --parent N [--team-role ROLE]
 hcc task update [--peer ID] --id N --status running|review|blocked|done|abandoned [--summary TEXT] [--body TEXT] [--to ID]
+hcc task running|review|blocked|abandoned [--peer ID] --id N [--summary TEXT] [--body TEXT] [--to ID]
 hcc task done [--peer ID] --id N --summary TEXT
 ```
 
@@ -110,6 +117,8 @@ dispatch` 是显式的一步分发：创建或指定已有任务并分配给目
 填写 reason，会记录原 owner 并通知对方。需要更保守时，可加 `--policy blocked`、
 `stale` 或 `blocked-or-stale`，要求任务符合可审计的阻塞/陈旧条件后才允许接管。
 默认 policy 仍是 `any`，以保持兼容。
+`task running`、`task review`、`task blocked` 和 `task abandoned` 是
+`task update --status STATUS` 的便捷写法。
 
 ## 团队