@logicseek/hello-cc 0.1.5 → 0.1.6

package/docs/architecture.zh-CN.md

@@ -0,0 +1,364 @@
+# hello-cc 架构设计
+
+日期：2026-06-14
+
+本文定义 hello-cc 的目标模块布局。它是后续重构的设计目标，不表示当前所有文件
+都已经符合这个结构。
+
+目标是停止按 helper 大小拆代码，改为按产品边界移动代码。薄 CLI、明确的核心
+状态模型、独立 runtime 层、terminal adapter 和 Web server 边界，能让后续修改
+更容易审查，也更不容易把无关行为混在一起。
+
+## 参考结构
+
+成熟的 agent CLI 项目通常采用类似分层：
+
+- 入口文件保持很薄，只转发到 command 或 server 模块；
+- 核心协作逻辑不依赖 HTTP、tmux 或进程启动细节；
+- runtime 文件和 runtime client 独立于命令处理器；
+- Web server routes、WebSocket transport、session lifecycle 是明确的 server
+  模块；
+- provider 特有行为与通用 session/task 逻辑隔离；
+- 测试按领域分组，而不是一直追加到一个巨大脚本里。
+
+Codex 这类结构会把 `cli`、`core`、`app-server`、`protocol` 或 transport、state
+store、hooks、config、execution adapter 分开。hello-cc 不需要 Rust crate，也
+不需要同样规模，但应该采用同一个架构原则：按边界拆，不按顺手程度拆。
+
+## 当前压力点
+
+当前代码已经抽出了很多聚焦模块，例如 schema、runtime state、task/message
+store、peer identity、provider command builder、tmux helper、Web HTTP helper
+和 render helper。
+
+剩余结构压力主要在：
+
+- `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。
+- `scripts/regression.mjs` 是有价值的全量回归入口，但后续应该变成一个调用领域
+  regression module 的 runner。
+
+## 目标目录
+
+```text
+bin/
+  hcc.mjs
+
+lib/
+  cli/
+    dispatch.mjs
+    context.mjs
+    commands/
+      ask.mjs
+      broadcast.mjs
+      down.mjs
+      event.mjs
+      gc.mjs
+      handoff.mjs
+      hooks.mjs
+      init.mjs
+      inject.mjs
+      join.mjs
+      lock.mjs
+      msg.mjs
+      peer.mjs
+      prompt.mjs
+      run.mjs
+      scan.mjs
+      setup.mjs
+      shim.mjs
+      state.mjs
+      status.mjs
+      task.mjs
+      team.mjs
+      uninstall.mjs
+      update.mjs
+      up.mjs
+      web.mjs
+
+  core/
+    coordination/
+      automation.mjs
+      handoff.mjs
+      locks.mjs
+      messages.mjs
+      tasks.mjs
+      teams.mjs
+      timeline.mjs
+    peers/
+      bindings.mjs
+      format.mjs
+      identity.mjs
+      liveness.mjs
+    sessions/
+      launch.mjs
+      model.mjs
+      providers.mjs
+      serialization.mjs
+
+  db/
+    connection.mjs
+    migrations.mjs
+    schema.mjs
+    stores/
+      locks.mjs
+      messages.mjs
+      peers.mjs
+      tasks.mjs
+
+  runtime/
+    client.mjs
+    paths.mjs
+    projects.mjs
+    state.mjs
+
+  terminal/
+    external-buffer.mjs
+    pty.mjs
+    tmux-stream.mjs
+    tmux.mjs
+
+  web/
+    projects.mjs
+    routes.mjs
+    server.mjs
+    session-manager.mjs
+    websocket.mjs
+    http.mjs
+    ui-template.mjs
+
+  integrations/
+    hooks/
+      claude.mjs
+      codex.mjs
+    providers/
+      claude.mjs
+      codex.mjs
+      shell.mjs
+    shims/
+      setup.mjs
+      script.mjs
+
+  ui/
+    format.mjs
+    help.mjs
+    state-render.mjs
+
+  release/
+    package-meta.mjs
+    release-notes.mjs
+
+  shared/
+    errors.mjs
+    json-file.mjs
+    text.mjs
+
+scripts/
+  regression.mjs
+  regression/
+    cli.mjs
+    coordination.mjs
+    db.mjs
+    release.mjs
+    runtime.mjs
+    sessions.mjs
+    web.mjs
+```
+
+## 边界规则
+
+`bin/hcc.mjs` 应该变成很薄的入口。它可以解析全局参数、创建 root context、调用
+dispatch，并把顶层错误转换为 CLI 输出。它不应该拥有 Web routing、DB schema、
+tmux streaming、provider command construction 或 task state machine。
+
+`lib/cli/` 负责命令解析和命令处理器。命令处理器可以打开数据库、调用 store 或
+core service，并打印结果。当逻辑可以放进 `core`、`runtime`、`terminal`、`web`
+或 `integrations` 时，不应该留在 command handler 里。
+
+`lib/core/` 负责产品语义。task lifecycle、takeover readiness、message thread、
+lock conflict rule、team planning、peer identity semantics 和 session identity
+rule 属于这里。core module 不应该依赖 HTTP request、WebSocket、tmux command 或
+process spawning。
+
+`lib/db/` 负责 SQLite connection、schema、migration 和 data store。store module
+应该暴露明确操作和事务边界。schema migration 必须能安全迁移每个注册项目数据库，
+而不只是当前项目。
+
+`lib/runtime/` 负责 runtime file、runtime discovery、runtime client request 和
+project registry state。它不应该知道 Web route 如何渲染 UI，也不应该知道
+terminal byte 如何传输。
+
+`lib/terminal/` 负责 terminal adapter。tmux pane inspection、tmux stream setup、
+tmux input、PTY spawn 和 external buffer adoption 属于这里。terminal adapter
+可以发出 session event，但不应该决定 task ownership 或 message 行为。
+
+`lib/web/` 负责 Web runtime。它应该组装 project context、session manager、HTTP
+route、WebSocket terminal upgrade 和 shutdown cleanup。route handler 应该很薄，
+并委托给 store、core service、runtime module 或 terminal/session manager。
+
+`lib/integrations/` 负责 provider 特有行为。Claude、Codex、shell command
+construction、hook installation details 和 shim script 不应混入通用 session 和
+coordination module。
+
+`lib/ui/` 负责 CLI 文本输出和 help。它可以格式化已经计算好的状态，但不应该读取
+或修改项目状态。
+
+`lib/release/` 负责 release metadata 和 release notes helper。release script 和
+GitHub release 工具应共享这里的 helper。
+
+`lib/shared/` 只放少量低依赖通用工具，不能变成新的杂物箱。
+
+## 包发布面策略
+
+受支持的公共接口是安装后的 CLI：`hcc` 和 `hello-cc`。`package.json` 包含
+`lib/` 是因为 CLI 运行时会 import 这些文件，不表示每个 `lib/*` 路径都是稳定
+library API。
+
+不要在用户文档里新增 `@logicseek/hello-cc/lib/*` 这类导入用法。主实现应该放在
+目标产品目录里；顶层 `lib/*.mjs` 文件只有在有明确兼容理由时，才作为
+compatibility entrypoint 保留。
+
+`@logicseek/hello-cc@0.1.5` 已经从 git head `4969100` 发布。这个已发布包因为
+没有定义 `exports` map，已经暴露了一些顶层 `lib/*.mjs` helper 路径。常规 cleanup
+提交里不要删除或重命名这些已发布路径；除非项目明确选择破坏性 package surface
+变更，否则至少保留一个 release cycle，作为 compatibility re-export。
+
+对于 `0.1.5` 之后的本地迁移提交，默认不要继续增加顶层 compatibility shim。如果
+某个尚未发布的顶层 shim 要保留到下一版，需要在 release notes 里说明它只是
+compatibility-only，并在再下一版前重新评估是否删除。不要让 compatibility shim
+变成目标架构。
+
+发行前，把顶层 `lib/*.mjs` 路径分成三类：
+
+- A 类：已发布过，或 CLI 面向用户需要稳定的 helper 路径，本次发行必须保留。
+- B 类：目录迁移产生的 compatibility path，只是 re-export 已移动实现；如确有
+  需要可保留一个版本，但 release notes 要说明它只是 compatibility-only 的
+  deep-import 路径。
+- C 类：尚未发布、内部也不用、没有兼容价值的 shim，发布前删除。
+
+因为 npm 上已经存在 `0.1.5`，任何包含 `4969100` 之后本地提交的发行都必须使用新
+package 版本。不要尝试重新发布 `0.1.5`。
+
+## 依赖方向
+
+目标依赖方向：
+
+```text
+bin -> cli -> web/runtime/db/core/terminal/integrations/ui
+web -> runtime/db/core/terminal/ui
+terminal -> shared/core sessions only when needed
+core -> shared
+db -> shared
+ui -> shared
+release -> shared
+```
+
+避免以下依赖：
+
+- `core` import `web`、`terminal`、`cli` 或 `integrations`；
+- `db` import `cli` 或 `web`；
+- `terminal` import Web route module；
+- provider integration import command handler；
+- `shared` import 产品特定模块。
+
+这样大多数行为可以在没有 Web runtime 或 tmux process 的情况下测试。
+
+## 迁移计划
+
+重构必须小步进行，每一步都保持公共行为和 npm package 内容稳定，除非任务明确要
+改行为。
+
+1. 写下目标架构。
+   本文就是后续拆分的合同。
+
+2. 把现有平铺模块移动到目标目录。
+   先做低风险迁移，例如 `runtime-*`、`web-*`、`task-store`、`messages`、`help`、
+   `state-render` 和 release helper。如果 import churn 太大，可以临时保留
+   compatibility re-export 文件。
+
+3. 按子系统拆 Web runtime。
+   分提交从 `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/`。
+
+5. 按领域拆 regression。
+   保持 `npm test` 是唯一全量回归命令，但让它调用 `scripts/regression/` 下的
+   领域模块。
+
+## Web Runtime 目标
+
+最有价值的 runtime 拆分如下：
+
+```text
+lib/web/server.mjs
+  createWebRuntime(ctx, opts, deps)
+  start/stop lifecycle
+
+lib/web/projects.mjs
+  rememberProject()
+  knownProjects()
+  projectFromRequest()
+
+lib/web/session-manager.mjs
+  sessions map
+  getSession()
+  serializeSession()
+  startSession()
+  stopSession()
+  restoreManagedSessions()
+
+lib/web/routes.mjs
+  routeHttpRequest(req, res, env)
+
+lib/web/websocket.mjs
+  handleTerminalUpgrade(req, socket, head, env)
+
+lib/terminal/tmux-stream.mjs
+  startTmuxStream()
+  stopTmuxStream()
+  refreshTmuxSnapshot()
+
+lib/terminal/external-buffer.mjs
+  adoptExternalSession()
+  scanExternalSessions()
+```
+
+这个拆分能让 Web 空白、stale session、tmux stream 和 provider binding 问题更
+容易定位。
+
+## 测试要求
+
+每个结构迁移任务至少运行：
+
+```bash
+git diff --check
+node --check bin/hcc.mjs
+node --check <changed modules>
+npm test
+```
+
+涉及发行面的变更还要运行：
+
+```bash
+npm run release:check
+npm run release:github:dry-run
+npm pack --dry-run --json
+```
+
+新增 `lib/` 模块后，要确认 `npm pack --dry-run --json` 包含它们。
+
+## 非目标
+
+不要在本次布局迁移中引入 TypeScript、Rust、bundler 或 build step。这些都是单独
+的产品决策，会影响 release 和安装成本。
+
+不要在移动文件时重写已工作的行为。目录迁移提交应该很朴素：import 改了、模块
+路径改了、regression guard 改了，但行为不变。
+
+在没有单独 Web UI build 方案前，不要把 UI template asset 移到前端框架里。当前
+npm 包安装后应继续可以直接运行。

package/docs/layout-split-stack-audit.md

@@ -0,0 +1,298 @@
+# Layout Split Stack Audit
+
+Date: 2026-06-14
+
+Audit branch: `audit/layout-split-stack-20260614`
+
+Reviewed range: `origin/master..HEAD`
+
+- Base: `4969100` (`origin/master`, published as `@logicseek/hello-cc@0.1.5`)
+- Audited head: `4283234`
+- Commit count: 40
+
+This document audits the local architecture split stack before any push or npm
+publish. It is intentionally on a dedicated audit branch/worktree so the active
+`master` implementation stack is not rewritten during review.
+
+## Review Standard
+
+Each commit is classified against `docs/architecture.md`:
+
+- `keep`: the commit directly moves code toward a documented product boundary.
+- `keep-with-cleanup`: the direction is right, but package surface, shim policy,
+  or module placement still needs a cleanup decision before release.
+- `squash/rebuild`: the code is useful, but the commit exists mostly as an
+  intermediate flat extraction and should be folded into a product-boundary
+  commit if a clean release branch is rebuilt.
+- `decision-needed`: the final location or public surface is not settled.
+- `docs-only`: documentation or process record.
+
+The important distinction is code shape versus history shape. A commit can be
+useful for reaching the current code state while still being a poor standalone
+release-history commit.
+
+## Team Review Split
+
+Parent task: `#232`
+
+- `#234 lead-audit`: maintain this matrix and merge review feedback.
+- `#236 review-core-db`: core, coordination, db, peers, session semantics.
+- `#235 review-runtime-web`: runtime, web, terminal, integrations, release,
+  shared helper placement.
+- `#237 review-package-surface`: top-level `lib/*.mjs` compatibility shims,
+  npm package surface, and release-note risk.
+
+## Summary
+
+The current `HEAD` is not a random bad refactor. The final code shape has mostly
+been corrected toward the target architecture:
+
+- coordination logic under `lib/core/coordination`
+- peer/session semantics under `lib/core/peers` and `lib/core/sessions`
+- schema and stores under `lib/db`
+- runtime state/client/project helpers under `lib/runtime`
+- tmux under `lib/terminal`
+- Web runtime helpers under `lib/web`
+- provider/hooks/shims under `lib/integrations`
+- small utilities under `lib/shared`
+- text rendering/help under `lib/ui`
+- release helpers under `lib/release`
+
+The problem is the history shape. The first 25 local commits were mostly
+"extract a helper from `bin/hcc.mjs` into a top-level `lib/*.mjs` file". That
+was useful as a safety step, but it does not match the architecture design by
+itself. Later commits then moved many of those flat files into real product
+boundaries.
+
+Therefore:
+
+1. If the project keeps the current `master` history, do not keep making broad
+   split commits. Finish only package-surface cleanup, run full validation, bump
+   the version, and publish/sync with a clear changelog.
+2. If the project wants clean history for this major refactor, create a rebuild
+   branch from `origin/master` and replay the final shape as fewer architectural
+   commits. Do not rewrite the active `master` while peers use it.
+
+## Phase Classification
+
+### Phase 1: Early Flat Extractions
+
+These commits reduced `bin/hcc.mjs`, but mostly created top-level helper modules
+before the design document existed. They should be treated as
+`squash/rebuild` if a clean branch is made.
+
+| Commit | Area | Classification | Reason |
+| --- | --- | --- | --- |
+| `1bb1967` | providers + tmux | `squash/rebuild` | Mixed two product boundaries in one top-level extraction; should become integrations/provider and terminal/tmux commits. |
+| `e155d5a` | locks | `squash/rebuild` | Useful code, but final home is `lib/core/coordination/locks.mjs`, not top-level `lib/locks.mjs`. |
+| `9ab464d` | team planning | `squash/rebuild` | Same pattern; final home is `lib/core/coordination/teams.mjs`. |
+| `807fa96` | peer identity | `squash/rebuild` | Useful extraction, but identity is split between integration discovery and core peer semantics later. |
+| `494d38f` | peer format | `squash/rebuild` | Good low-level helper, but should land with peer-boundary cleanup rather than a standalone flat helper commit. |
+| `e2b745d` | project registry | `squash/rebuild` | Final boundary is runtime/project registry. |
+| `e4c4497` | project context | `squash/rebuild` | Final boundary is runtime/project context. |
+| `dec3e2e` | handoff | `decision-needed` | `lib/handoff.mjs` remains top-level; decide core coordination semantics versus CLI command helper. |
+| `61b02a2` | timeline | `squash/rebuild` | Final boundary is core coordination timeline. |
+| `62ede11` | runtime state | `squash/rebuild` | Final boundary is `lib/runtime/state.mjs`. |
+| `7d885f1` | task liveness | `squash/rebuild` | Final boundary is core peer liveness. |
+| `3f0cc7e` | session launch | `decision-needed` | Current compatibility file bridges core session launch and terminal/tmux helpers; keep an eye on dependency direction. |
+| `b07e9b5` | automation | `squash/rebuild` | Final boundary is core coordination automation. |
+| `428bbf3` | state render | `squash/rebuild` | Final boundary is UI state rendering. |
+| `8a6120f` | tmux pane | `squash/rebuild` | Should be folded into terminal/tmux movement. |
+| `3ec062b` | help text | `squash/rebuild` | Final boundary is UI help. |
+| `7e8068c` | uninstall help | `squash/rebuild` | Should be folded into UI help extraction. |
+| `9ed79b6` | message store | `squash/rebuild` | Final boundary is core coordination messages. |
+| `07ddcc9` | runtime client | `squash/rebuild` | Final boundary is `lib/runtime/client.mjs`. |
+| `c06e55d` | web runtime server helpers | `squash/rebuild` | Useful step, but final boundary is `lib/web/runtime.mjs`; route/session/server split still pending. |
+| `fe36930` | task store | `squash/rebuild` | Final boundary is core coordination tasks. |
+| `3bd0782` | task CLI parsing | `keep-with-cleanup` | This is a CLI-specific helper and can remain near CLI until `lib/cli/*` exists. |
+| `61538fc` | peer bindings | `squash/rebuild` | Final split crosses core peer bindings and db peer store. |
+| `787857f` | CLI runtime | `keep-with-cleanup` | Still not the final `lib/cli/context.mjs` layout, but it is a valid CLI/runtime entrypoint reduction. |
+| `00ac7ba` | coordination state | `squash/rebuild` | Useful factory boundary, but should be evaluated with core coordination dependencies. |
+
+### Phase 2: Architecture Documentation And First Boundary Correction
+
+| Commit | Area | Classification | Reason |
+| --- | --- | --- | --- |
+| `94d63c0` | architecture docs | `docs-only` | Correctly establishes the target layout. |
+| `76d5181` | web peer actions | `squash/rebuild` | Good product boundary direction, but final import path is corrected later under `lib/web/peer-actions.mjs`. |
+| `265284a` | broad architecture alignment | `keep-with-cleanup` | Correct direction, but too broad for ideal history; should become several product-boundary commits on a rebuild branch. Also review whether SQL/transaction-heavy task code belongs in `lib/core/coordination/tasks.mjs` or should split pure task policy from a db store. |
+
+### Phase 3: Product-Boundary Cleanup Commits
+
+These commits are much closer to the target design. They are the model for the
+rebuild branch if one is created.
+
+| Commit | Area | Classification | Reason |
+| --- | --- | --- | --- |
+| `294eb2e` | peer layout boundaries | `keep` | Moves peer semantics toward `core/peers`, `db/stores`, and integrations boundaries. |
+| `a3eabd8` | tmux adapter | `keep` | Clear terminal adapter boundary. |
+| `fb9c35a` | shared JSON file helpers | `keep-with-cleanup` | Shared utility is appropriate; keep `lib/json-file.mjs` compat because it was already published in `0.1.5`. |
+| `77c098d` | provider commands | `keep` | Correct integrations boundary. |
+| `6bbe4a0` | project context | `keep` | Correct runtime boundary. |
+| `be7c882` | session launch helpers | `decision-needed` | Direction is mostly correct, but compat surface exports both core session and terminal/tmux helpers. Review dependency direction before release. |
+| `ffc42a7` | setup hook installers | `keep` | Correct integrations/hooks boundary. |
+| `1bd110f` | setup shims | `keep` | Correct integrations/shims boundary. |
+| `c191c72` | shim script generator | `keep` | Correct integrations/shims/script boundary. |
+| `11fd4f6` | CLI errors | `keep` | Correct small shared utility boundary with compatibility re-export. |
+
+### Phase 4: Review And Policy Docs
+
+| Commit | Area | Classification | Reason |
+| --- | --- | --- | --- |
+| `19c0856` | split review | `docs-only` | Captures the historical concern and branch strategy. |
+| `4283234` | package surface policy | `docs-only` | Captures npm `0.1.5` fact, version-bump requirement, and A/B/C shim policy. |
+
+## Initial Recommendations
+
+### Use A New Branch
+
+Yes. This is a major refactor stack and should not be pushed or published
+directly just because `master` is currently green. Use this audit branch for
+review. If the team chooses clean history, create a separate rebuild branch from
+`origin/master`, not from current `master`.
+
+Suggested rebuild branch:
+
+```bash
+git worktree add ../hello-cc-layout-rebuild -b rebuild/layout-split-20260614 origin/master
+```
+
+Suggested rebuilt commit order:
+
+1. Architecture docs.
+2. Core coordination modules: locks, teams, messages, tasks, timeline,
+   automation, liveness-related coordination state.
+3. Core peer/session modules and db peer store.
+4. Runtime modules: paths, state, client, project registry, project context.
+5. Terminal adapter: tmux.
+6. Web modules: runtime, HTTP, peer actions, UI template.
+7. Integrations: providers, hooks, shims, shim script, peer identity.
+8. Shared/release/ui helpers.
+9. Compatibility shim policy and package-surface release notes.
+
+### Do Not Revert The Final Shape Blindly
+
+The final code shape is mostly aligned with the architecture document. The
+problem is the noisy path taken to get there. A rebuild should preserve the
+validated final behavior while changing the history granularity.
+
+### Core/DB Review Findings
+
+The core/db review from `#236` and the parallel read-only subagent agree on the
+main shape:
+
+- Keep the final direction of `lib/core/coordination/*`, `lib/core/peers/*`,
+  `lib/core/sessions/launch.mjs`, `lib/db/schema.mjs`,
+  `lib/db/stores/peers.mjs`, and `lib/shared/errors.mjs`.
+- Rebuild the early top-level coordination/peer/session helper commits into
+  product-boundary commits if clean history is chosen.
+- Do not treat `lib/handoff.mjs`, `lib/session-launch.mjs`, or
+  `lib/coordination-state.mjs` as settled final architecture.
+
+Concrete cleanup items from that review:
+
+- `lib/core/coordination/tasks.mjs` is currently SQL/transaction-heavy. Split
+  pure task lifecycle/takeover/team policy from DB store operations, or move the
+  store-style SQL operations under `lib/db/stores/tasks.mjs`.
+- `lib/core/coordination/automation.mjs` and
+  `lib/core/coordination/timeline.mjs` depend on top-level `lib/format.mjs` for
+  `shellQuoteArg` / `compactText`. Move dependency-light text helpers to
+  `lib/shared/text.mjs` or keep rendering concerns in the UI/CLI layer.
+- `lib/handoff.mjs` mixes CLI input normalization with runtime Git changed-file
+  discovery. Split handoff product semantics from CLI/runtime file inspection.
+- `lib/session-launch.mjs` re-exports both core session helpers and
+  terminal/tmux helpers. That is acceptable only as a compatibility entrypoint;
+  do not let it become the conceptual module boundary.
+- `lib/coordination-state.mjs` is useful as an interim assembler, but it mixes
+  DB queries, timeline, automation, hook context, status summary, and message
+  ack batching. Later split it into core state services plus CLI/Web adapters.
+
+### Runtime/Web/Integrations Review Findings
+
+The runtime/web/terminal/integrations review from `#235` and the parallel
+read-only subagent agree on the main shape:
+
+- Keep the final direction of `lib/terminal/tmux.mjs`.
+- Keep the final direction of `lib/integrations/providers.mjs`,
+  `lib/integrations/hooks.mjs`, `lib/integrations/shims.mjs`, and
+  `lib/integrations/shims/script.mjs`.
+- Keep the final direction of `lib/release/*`, `lib/shared/errors.mjs`, and
+  `lib/shared/json-file.mjs`.
+- Keep the runtime and Web movement as directionally correct:
+  `lib/runtime/{paths,state,client,projects,project-context}.mjs` and
+  `lib/web/{http,runtime,ui-template,peer-actions}.mjs`.
+
+Concrete cleanup items from that review:
+
+- `lib/runtime/client.mjs` and `lib/runtime/state.mjs` import `runtimeApiUrl`
+  from `lib/web/runtime.mjs`. That creates a runtime -> web reverse dependency.
+  Move the URL helper into `lib/runtime`, `lib/shared`, or inject it from the
+  caller before claiming strict dependency direction.
+- `lib/web/runtime.mjs` and `lib/web/peer-actions.mjs` import CLI parsing
+  helpers from `lib/cli-args.mjs`. Move shared option parsing such as
+  `intOpt`/`required` to a dependency-light shared helper, or inject parsing at
+  the route boundary.
+- `lib/web/peer-actions.mjs` imports `normalizeStateResources` from
+  `lib/ui/state-render.mjs`. Move non-render normalization out of the UI layer,
+  or keep the dependency at a CLI/Web adapter edge.
+- `cmdWeb()` in `bin/hcc.mjs` still owns server lifecycle, session manager,
+  WebSocket terminal transport, tmux/PTY orchestration, external-buffer
+  adoption, and shutdown cleanup. Future work should split this by subsystem;
+  do not continue random helper extraction from it.
+
+No immediate runtime blocker was found. `#235` also reran `npm test` and got
+`FULL_REGRESSION_OK`.
+
+### Decide Shim Policy Before Release
+
+Because `@logicseek/hello-cc@0.1.5` is already published from `4969100`, the
+next package version must be new. Before that publish:
+
+- Group A: already-published or CLI-facing top-level `lib/*.mjs` paths stay.
+- Group B: migration compatibility paths stay one release if needed and are
+  documented as compatibility-only deep-import paths.
+- Group C: unpublished top-level shims with no internal use or compatibility
+  value should be removed before release.
+
+Initial package-surface inventory:
+
+| Group | Paths | Current decision |
+| --- | --- | --- |
+| A: published in `0.1.5` | `lib/cli-args.mjs`, `lib/db-schema.mjs`, `lib/discover.mjs`, `lib/errors.mjs`, `lib/format.mjs`, `lib/guidance.mjs`, `lib/json-file.mjs`, `lib/package-meta.mjs`, `lib/release-notes.mjs`, `lib/runtime-paths.mjs`, `lib/setup.mjs`, `lib/shell-path.mjs`, `lib/shim-script.mjs`, `lib/web-http.mjs`, `lib/web-runtime.mjs`, `lib/web-ui-template.mjs` | Keep for the next release, even if some are now compatibility re-exports. Removing them would be a package-surface break. |
+| A: current internal top-level runtime refs | `lib/cli-runtime.mjs`, `lib/coordination-state.mjs`, `lib/handoff.mjs`, `lib/project-context.mjs`, `lib/task-cli.mjs`, `lib/tmux.mjs` | Keep until a focused cleanup moves current internal imports to the target directories. Do not delete these as pure compatibility shims today. |
+| B/C candidates: new re-export-only paths with no current runtime ref | `lib/automation.mjs`, `lib/help.mjs`, `lib/locks.mjs`, `lib/messages.mjs`, `lib/peer-bindings.mjs`, `lib/peer-format.mjs`, `lib/peer-identity.mjs`, `lib/project-registry.mjs`, `lib/provider-commands.mjs`, `lib/runtime-client.mjs`, `lib/runtime-state.mjs`, `lib/session-launch.mjs`, `lib/state-render.mjs`, `lib/task-liveness.mjs`, `lib/task-store.mjs`, `lib/team-planning.mjs`, `lib/timeline.mjs`, `lib/web-peer-actions.mjs` | Treat as C only if the project decides they have no migration compatibility value. Otherwise keep for one release as B and document them as compatibility-only deep imports. |
+| C: remove before publish | None confirmed yet | Do not delete by guess. A candidate becomes C only after checking it was not in `0.1.5`, is not imported internally, and has no release compatibility value. |
+
+### Watch Items
+
+- `lib/handoff.mjs`: decide core coordination versus CLI command helper.
+- `lib/session-launch.mjs`: review mixed core session and terminal/tmux
+  compatibility exports.
+- `lib/core/coordination/tasks.mjs`: split pure task policy from DB store style
+  SQL/transactions.
+- `lib/core/coordination/{automation,timeline}.mjs`: remove dependency on
+  top-level `lib/format.mjs`.
+- `lib/coordination-state.mjs`: keep as interim assembler, but split before
+  claiming final architecture.
+- `lib/runtime/{client,state}.mjs`: remove reverse dependency on
+  `lib/web/runtime.mjs`.
+- `lib/web/{runtime,peer-actions}.mjs`: remove direct dependency on CLI parsing
+  helpers.
+- `lib/web/peer-actions.mjs`: remove direct dependency on UI state-render
+  helpers for non-render normalization.
+- `scripts/regression.mjs`: current test coverage is valuable, but its size
+  should be split after the architecture stack is stable.
+- `bin/hcc.mjs`: still contains large command and Web orchestration areas; do
+  not continue extracting from it until this audit decides branch strategy.
+
+## Current Status
+
+Peer feedback from `#235`, `#236`, and `#237` has been merged into this audit.
+The audit conclusion is:
+
+- The final code shape is mostly reasonable.
+- The early commit history is not clean architecture history.
+- Use a new rebuild branch from `origin/master` if clean history matters.
+- Keep the current `master` stack only if the project accepts noisy local
+  history and completes the release cleanup items above before publish.
+- Do not resume release task `#233` until this audit decision is accepted.

package/lib/automation.mjs

@@ -0,0 +1,8 @@
+export {
+  actionCommand,
+  deriveAutomation,
+  looksLikeMultiTask,
+  makeAction,
+  renderAutomationContext,
+  selectCurrentTask
+} from './core/coordination/automation.mjs';

package/lib/cli-args.mjs

@@ -1,5 +1,5 @@
 import process from 'node:process';
-import { CliError } from './errors.mjs';
+import { CliError } from './shared/errors.mjs';
 
 export function splitGlobalArgs(argv) {
   const global = { json: false, root: null, db: null };