open-tui-orchestrator 0.9.6

package/CHANGELOG.md

@@ -0,0 +1,205 @@
+# Changelog
+
+Notable changes, newest first. Every entry pairs a package version with a core version —
+`open-tui-orchestrator --version` prints both (`open-tui-orchestrator <version> (core <core>)`).
+
+## 0.9.6 — core 1.14.6
+
+### Fixed
+
+- **A dead model account no longer hides behind a parser-sounding message.** When the classify
+  call returned nothing because the account was out of quota (or not logged in, or the network
+  failed), the failure line read `no JSON in classify output: (no valid JSON) -> fallback to
+  single serial block` — which looks like a parsing bug. `runThreadPrompt`'s `errored`/`warnings`
+  (where the real reason lives) were being dropped. The line now carries the underlying reason,
+  bounded to one line:
+
+  ```
+  before:  decompose LLM failed after 2 attempt(s): no JSON in classify output:  (no valid JSON) -> fallback …
+  after:   decompose LLM failed after 2 attempt(s): classify model call failed: You've hit your usage limit. Visit
+           https://chatgpt.com/codex/settings/usage to purchase more credits or try again at Sep 19th, 2026 4:10 PM. -> fallback …
+  ```
+
+  Verified by before/after on this machine with the same command and the same account state (the
+  released 0.9.5 copy versus the fixed tree); the reason text comes from the account, so the run
+  also tells you when it recovers. Recorded in `test/acceptance-2026-09-15-windows-guard-live-run.json`.
+
+- Recorded, not fixed (honest boundary): when units themselves fail on quota exhaustion, the run
+  correctly reports `success: false` with `failed` tasks and no fake success, but the per-task
+  reason is the generic `No durable task checkpoint` / `Safe recovery attempt budget exhausted`;
+  the underlying CLI text stays in `runs/<id>/attempts/`. Surfacing the unit-level reason is a
+  follow-up, not claimed here.
+
+## 0.9.5 — core 1.14.5
+
+### Fixed
+
+- **The Windows-only promise is now enforced, not just documented.** Measured: with no guard, a
+  simulated non-Windows platform reported a *healthy* `--doctor` (exit 0, `"terminal": "wt"`) and
+  `--run-windows` proceeded to a real classify call — the front page claimed "other platforms get
+  a diagnostic instead of a half-working install", and that claim was false. The refusal now
+  happens in `scripts/platform-guard.mjs`, called by `cli.mjs`, `orch.mjs` and the SDK wrapper
+  before host resolution, before any model call and before any state: one
+  `[orchestrator] FATAL: Windows-only: …` line, exit 1, no stack. `--version`, `--help` and
+  `--install-deps` stay available because they are platform-neutral and are what you need when
+  debugging a platform issue (they are what the criterion pins as still working).
+
+### Added
+
+- `test/windows-only.test.mjs` — two criteria, red-capable in both directions (remove the guard →
+  case 1 fails; widen it to every entry → case 2 fails). The red case was demonstrated for real:
+  guard removed from a copy, copy resealed, fake platform → healthy `--doctor`.
+
+### Verified
+
+- A live two-block run against the **released** copy (0.9.4) through the caller-driven channel
+  (`--plan-file` + `--unit-cmd-file` + `--acceptance-file`, zero model calls): board reached
+  `2/2 verified … finalized success=true`, products `alpha.txt=ALPHA_OK` / `beta.txt=BETA_OK`
+  written and hash-recorded, both tasks `verified` with `completed` checkpoints, ~60 s.
+- Environment note recorded in the evidence file: the codex account on this machine is out of
+  quota until 2026-09-19, so a model-driven run could not be executed today; the orchestrator
+  degraded correctly (inline fallback, no fake success) instead of pretending to run.
+
+## 0.9.4 — core 1.14.4
+
+### Added
+
+- **`scripts/gate.mjs` — the machine gate now lives in the repository** and anyone can run it:
+  `node scripts/gate.mjs --all` runs L1 the offline regression suite, L2a host resolution,
+  L2b a deliberately failing test (proof that the criteria can still go red), L3 the unknown-run
+  diagnostic and L4 the version / seal / documentation / suite-total cross-check plus a stale
+  mutex-ticket sweep. Every criterion prints command, expectation and actual; a value that cannot
+  be read counts as a failure.
+- **`.github/workflows/ci.yml`** — the same gate on a clean `windows-latest` runner, including the
+  codex install and the `--install-deps` bootstrap self-test. It ships **disarmed** (manual
+  trigger only) so that pushing to a private repository never spends Windows runner minutes;
+  the header comment names the two lines that arm it.
+- **`docs/trust-and-safety.md`** — a plain statement of what this tool does on your machine:
+  hidden agents running with your credentials, the Codex approval bypass, what `--unit-cmd` means,
+  every file it writes, and the fact that there is no telemetry, daemon or auto-update.
+- **`SECURITY.md`** — private vulnerability reporting, scope, disclosure timeline.
+- **`CONTRIBUTING.md`** — the house rules (criteria must be able to go red, seal discipline,
+  single-source numbers).
+
+### Changed
+
+- README / README-zh lead with the **Windows-only** statement and link the trust statement,
+  security policy and contributing guide.
+- `INSTALL.md` documents `node scripts/gate.mjs --all`, `node scripts/release-integrity.mjs`
+  and `ORCH_NPM_BIN`.
+
+## 0.9.3 — core 1.14.3
+
+### Fixed
+
+- **`--install-deps` is now reachable exactly when you need it.** If your environment sets
+  `ORCH_AGENT=codex`, the wrapper used to run the SDK dependency check (and the engine to
+  `import` `@openai/codex-sdk` at load) *before* the bootstrap entry could run — a deadlock for
+  anyone with missing dependencies. The bootstrap now runs before the engine, and its
+  implementation lives in `scripts/install-deps.mjs`, which imports nothing but Node builtins.
+- **A successful install is no longer reported as a failure.** The dependency probe was computed
+  once before the install, so `npm ci` succeeding (exit 0) still produced
+  `FATAL: dependency install failed`. It is re-checked after the install, and the success path now
+  has a regression test (offline, with an npm stub).
+- `ORCH_NPM_BIN` (new) points at a custom or corporate npm; a missing toolchain is reported with
+  the manual fallback command instead of a Node stack.
+
+### Changed
+
+- **Publishing metadata**: `private` removed, `description` / `keywords` / `author` / `license` /
+  `repository` / `homepage` / `bugs` added, and an explicit `files` list now excludes `test/` and
+  `scripts/node_modules` (without that exclusion the tarball picked up 385 MB of dev
+  dependencies — 143 MB packed; with it, 89 files / 292 kB). `npm publish --dry-run` is green.
+- **Machine identity stripped from the repository**: 18 tracked files / 77 occurrences of the
+  authoring machine's user name are normalized to `<user>`, and the root causes are fixed so
+  future artifacts stay clean (evidence collector, profile adapter provenance, the shipped hermes
+  profile).
+- npm is invoked through `node_modules/npm/bin/npm-cli.js` when available (no `shell: true`,
+  no `DEP0190` warning, no shell-quoting of paths).
+
+## 0.9.2 — core 1.14.2
+
+### Added
+
+- **`--install-deps`** — a first-class entry that installs this package's own locked SDK
+  dependencies (`@lydell/node-pty` for the invisible ConPTY carrier, `@openai/codex-sdk` for
+  Codex-hosted runs). Idempotent (a second run prints `already-present` without touching the
+  network), stdout stays pure data, and a failure names the manual fallback command. A public
+  install is now three commands.
+- **`INSTALL.md` / `INSTALL-zh.md`** and a README install section, plus
+  `docs/public-readiness.md` — an explicit list of what is done and what is still missing before
+  this can be released publicly.
+
+## 0.9.1 — core 1.14.1
+
+### Fixed
+
+- Coordinator mutex tickets are reclaimed on **every coordinator-directory resolution** (an idle
+  machine no longer keeps residue until the next transaction), and the helper polls its release
+  file every 100 ms instead of ~1 s — tickets vanish within ~300 ms. 576 leaked tickets were
+  observed on a long-lived machine and removed.
+
+## 0.9.0 — core 1.14.0
+
+### Fixed
+
+- **Coordinator mutex hardening.** The wait was hard-coded at 20 s inside the helper and 30 s on
+  the JS side, so nine contending parents under load produced false
+  `Coordinator mutex acquisition failed` results (2/9 in a full-suite run). Now: tunable wait
+  (`ORCH_MUTEX_WAIT_MS`, default 60 s), retries with exponential + jittered backoff
+  (`ORCH_MUTEX_RETRIES`, default 2), a JS-side bound derived from the same value, and age-based
+  ticket reclamation (`ORCH_MUTEX_TICKET_TTL_MS`, default 10 min).
+- `queue-backoff`'s end-to-end failure output now carries the per-block reason.
+
+## 0.8.0 — core 1.13.0
+
+### Added
+
+- **Machine-caller failure contract.** Every public entry fails closed with exactly one
+  `[orchestrator] FATAL: <reason>` line (Node stacks only with `ORCH_DEBUG=1`); exit codes are
+  0 success / 1 refused / 2 usage.
+
+### Fixed
+
+- `--verify-run` / `--resume-run` on an unknown run id now answer `Run not found: <id>` instead of
+  a raw `ENOENT` plus a four-frame stack.
+- `--watch <unknown run>` used to poll **forever** with no output; it now honours a bounded grace
+  (`ORCH_WATCH_GRACE_MS`, default 60 s — the run directory may legitimately not exist yet while
+  `--run-windows` is still planning) and reports a summary that disappears mid-watch.
+
+## 0.7.0 — core 1.12.0
+
+### Added
+
+- Queue wait backoff: capacity/conflict waiters back off exponentially with jitter
+  (`ORCH_WAIT_BACKOFF_MS`, `ORCH_WAIT_BACKOFF_MAX_MS`); waiting state rewrites the board only when
+  the reason changes.
+- OpenClaw version-gate diagnostics: the runtime `tui` interface probe runs first; unverified
+  versions fail closed carrying the probe result, node-pty presence and the last-verified version.
+- `orch-adapt` shim for the adaptation entry.
+
+## 0.6.0 — core 1.11.0
+
+### Added
+
+- Initiating-agent alignment: an adapter-less initiator with a landed profile (Hermes) is a
+  first-class auto host — its own CLI becomes the executor, with `--no-restore-cwd` guarding
+  against stale-session CWD writes.
+- Model/effort inheritance for caller-driven runs, and model/effort traceability in
+  `summary.json` (value plus source: explicit / host session / host-default).
+
+## 0.5.0 — core 1.10.0
+
+### Added
+
+- Unit carrier tiering: TUI-class agents run on an invisible ConPTY pseudo-terminal carrier by
+  default (a real console, no window, no focus steal); print-class CLIs keep the no-console
+  carrier. Identity, lease and recovery contracts are unchanged.
+
+## 0.4.0 — core 1.9.0
+
+### Added
+
+- Caller-driven channel: `--plan-file` (caller-supplied ledger/blocks, zero model calls in the
+  run), `--unit-cmd` / `--unit-cmd-file` (bring any CLI without an adapter), read-only `--tasks`
+  to align ids first, and resume identity rules for unit commands.

package/INSTALL-zh.md

@@ -0,0 +1,96 @@
+# 安装（中文）
+
+## 环境要求
+
+- **Windows 10/11（x64）**——当前仅支持 Windows：除 `--version`、`--help`、`--install-deps` 外，其它入口在别的平台上都会以一行诊断直接拒绝（不留「半能用」、不静默降级）。
+- **Node.js 22 或更高**（`node --version`）。
+- **Windows Terminal**（推荐；`--doctor` 会报 `terminal: "wt"`，缺失时回退 `conhost`）。
+- **一个已安装并已登录的宿主 agent CLI**：Codex、pi、opencode、Kimi Code、Claude Code，或版本锁定的 OpenClaw。编排器只驱动你已有的 CLI，**不会**安装、升级或替换任何 agent CLI。
+
+## 从 npm 安装
+
+```powershell
+npm install -g open-tui-orchestrator
+open-tui-orchestrator --install-deps          # 拉取本包锁定的 SDK 依赖
+open-tui-orchestrator --agent codex --doctor  # 验证
+```
+
+`--install-deps` 只安装**本包自己的**锁定依赖——`@lydell/node-pty`（无窗 ConPTY 载体）与 `@openai/codex-sdk`（Codex 宿主运行）——装进已安装的包目录内。只需联网一次；幂等：再跑一次会输出 `{"ok":true,"action":"already-present"}` 且不联网。
+
+## 从 tarball 安装（未上 npm 也能用）
+
+```powershell
+npm pack                                       # 在仓库内执行 -> open-tui-orchestrator-<版本>.tgz
+npm install -g .\open-tui-orchestrator-<版本>.tgz
+open-tui-orchestrator --install-deps
+```
+
+## 从源码安装（贡献者）
+
+```powershell
+git clone <本仓库>
+cd open-tui-orchestrator
+npm run setup                                  # = npm ci --prefix scripts
+npm test                                       # 离线回归（测试环境约定见 README-zh.md）
+node scripts/gate.mjs --all                    # 机判门禁：套件 + doctor + 反例能红 + 未知 run + 版本·封印·文档口径对账
+node scripts/release-integrity.mjs             # 封印校验（跑之前先确认这份检出没被动过）
+node cli.mjs --agent codex --doctor
+```
+
+## 验证
+
+`--doctor` 输出一段 JSON。健康安装长这样：
+
+```json
+{ "agent": "codex", "hostError": null, "carrier": "pty", "carrierAvailable": true, "spawnMode": "headless" }
+```
+
+- `hostError: null`——宿主 CLI 解析成功；
+- `carrierAvailable: true`——隐藏执行载体就绪（这就是 `--install-deps` 的作用）；
+- `spawnMode: "headless"`——单元默认无窗运行，`--mode window` 切可见 TUI 窗。
+
+## 第一次运行
+
+```powershell
+orch "刷新登录页文案；给令牌刷新路径补一条回归测试"
+```
+
+`orch` 是强制编排入口；常规入口是 `open-tui-orchestrator --run-windows "<请求>"`。真正可并行的请求会按块拉起执行单元——默认 headless、不弹窗。从另一个 shell 只读观察：
+
+```powershell
+open-tui-orchestrator --status --readonly
+open-tui-orchestrator --watch <runId> [--jsonl]
+```
+
+运行状态只落在 `<工作区>\temp\orchestrator\runs\<runId>\`（`manifest.json`、`summary.json`、`acceptance.json`、`attempts/`）。`summary.json` 是逐任务的权威结果账本。
+
+## 升级 / 回滚
+
+安装即「目录级发行副本」：升级或回滚就是替换该目录，然后重跑一次 `--install-deps`。当前版本用 `open-tui-orchestrator --version` 查看（只读，不解析 agent CLI）。
+
+## 卸载
+
+```powershell
+npm uninstall -g open-tui-orchestrator
+```
+
+各工作区的状态仍在 `<工作区>\temp\orchestrator` 下，需要彻底清干净就手动删。没有后台服务；除包目录外唯一的系统级痕迹是跨工作区共享窗口预算用的协调器定位（`HKCU\Software\TuiOrchestrator`）。
+
+## 排错
+
+| 症状 | 处理 |
+| --- | --- |
+| `RELEASE_DEPENDENCY_MISSING` | 跑 `open-tui-orchestrator --install-deps` |
+| `HOST_UNKNOWN` / `CLI_MISSING` | 安装并登录 `--agent` 指定的 CLI，或用 `ORCH_CLI` 指向其绝对路径 |
+| `--watch` 报 `Run not found: <id>` | run id 写错，或该 run 属于另一个 `--workspace` |
+| 什么都没弹出来 | 这是默认行为（headless）；`--mode window` 才有可见窗 |
+| `--install-deps` 失败 | 它会打印手工兜底命令 `npm ci --prefix "<包>\scripts"`；确认 Node 22+（含 npm）在 PATH 上 |
+
+## 它在你的机器上做什么（简版）
+
+完整声明（包括**没有**沙箱化的部分）见 [docs/trust-and-safety.md](docs/trust-and-safety.md)。简版：
+
+- 只驱动你已有的 agent CLI，并沿用你现有的授权——Codex 在「never 审批 + full access」策略下会带 `--dangerously-bypass-approvals-and-sandbox`，以免已授权的窗口卡在项目信任提示上；
+- 运行状态**只写** `<工作区>\temp\orchestrator`；
+- 不安装/升级/替换 agent CLI，也不把你的凭据发往任何地方；
+- `--unit-cmd` 执行的是**你自己**给的命令：那是调用方自授权，不是提权。

package/INSTALL.md

@@ -0,0 +1,96 @@
+# Install
+
+## Requirements
+
+- **Windows 10/11 (x64)** — Windows-only today: every entry except `--version`, `--help` and `--install-deps` refuses on another platform with one diagnostic line (no half-working install, no silent degradation).
+- **Node.js 22 or newer** (`node --version`).
+- **Windows Terminal** — recommended; `--doctor` reports `terminal: "wt"` or falls back to `conhost`.
+- **One supported agent CLI, already installed and logged in**: Codex, pi, opencode, Kimi Code, Claude Code, or the version-pinned OpenClaw. The orchestrator drives the CLI you already use; it never installs, upgrades or substitutes one.
+
+## Install (npm registry)
+
+```powershell
+npm install -g open-tui-orchestrator
+open-tui-orchestrator --install-deps          # fetch this package's locked SDK dependencies
+open-tui-orchestrator --agent codex --doctor  # verify
+```
+
+`--install-deps` installs only this package's own locked dependencies — `@lydell/node-pty` (the invisible ConPTY carrier) and `@openai/codex-sdk` (Codex-hosted runs) — into the installed package directory. It needs network access once and is idempotent: a second run prints `{"ok":true,"action":"already-present"}` and does not touch the network. It never installs an agent CLI.
+
+## Install from a tarball (no registry entry needed)
+
+```powershell
+npm pack                                       # inside the repository -> open-tui-orchestrator-<version>.tgz
+npm install -g .\open-tui-orchestrator-<version>.tgz
+open-tui-orchestrator --install-deps
+```
+
+## Install from source (contributors)
+
+```powershell
+git clone <this repository>
+cd open-tui-orchestrator
+npm run setup                                  # = npm ci --prefix scripts
+npm test                                       # offline regression (see the test-env note in README.md)
+node scripts/gate.mjs --all                    # the machine gate: suite + doctor + red canary + unknown run + version/seal/docs cross-check
+node scripts/release-integrity.mjs             # seal verify for the checkout you are about to run
+node cli.mjs --agent codex --doctor
+```
+
+## Verify
+
+`--doctor` prints one JSON block. A healthy install shows:
+
+```json
+{ "agent": "codex", "hostError": null, "carrier": "pty", "carrierAvailable": true, "spawnMode": "headless" }
+```
+
+- `hostError: null` — the host CLI resolved.
+- `carrierAvailable: true` — the hidden execution carrier is ready (this is what `--install-deps` provides).
+- `spawnMode: "headless"` — units run invisibly by default; `--mode window` switches to visible TUI windows.
+
+## First run
+
+```powershell
+orch "refresh the login page copy; add a regression test for the token refresh path"
+```
+
+`orch` is the force-execute entry; `open-tui-orchestrator --run-windows "<request>"` is the regular one. A genuinely parallel request opens one execution unit per block — headless by default, nothing pops up. Watch it read-only from another shell:
+
+```powershell
+open-tui-orchestrator --status --readonly
+open-tui-orchestrator --watch <runId> [--jsonl]
+```
+
+Run state lives under `<workspace>\temp\orchestrator\runs\<runId>\` (`manifest.json`, `summary.json`, `acceptance.json`, `attempts/`). `summary.json` is the authoritative per-task result ledger.
+
+## Upgrade / rollback
+
+Installations are directory-level release copies; an upgrade or rollback replaces that directory and re-runs `--install-deps`. Check what you are running with `open-tui-orchestrator --version` (it prints `open-tui-orchestrator <version> (core <core version>)` read-only, without resolving an agent CLI).
+
+## Uninstall
+
+```powershell
+npm uninstall -g open-tui-orchestrator
+```
+
+Per-workspace state stays under `<workspace>\temp\orchestrator`; delete it if you want a clean slate. There is no background service and no system-wide state beyond the package directory (a machine-wide coordinator locator is kept in `HKCU\Software\TuiOrchestrator` while runs from several workspaces share one window budget).
+
+## Troubleshooting
+
+| Symptom | What to do |
+| --- | --- |
+| `RELEASE_DEPENDENCY_MISSING` | run `open-tui-orchestrator --install-deps` |
+| `HOST_UNKNOWN` / `CLI_MISSING` | install and log in the CLI you pass to `--agent`, or point `ORCH_CLI` at its absolute path |
+| `--watch` prints `Run not found: <id>` | wrong run id, or the run belongs to a different `--workspace` |
+| Nothing pops up | that is the default (headless); pass `--mode window` |
+| `--install-deps` fails | it prints the manual fallback `npm ci --prefix "<pkg>\scripts"`; make sure Node 22+ (with npm) is on PATH, or point `ORCH_NPM_BIN` at your own npm (corporate mirror, alternate install) |
+
+## What it does on your machine (short version)
+
+The full statement, including what is *not* sandboxed, is [docs/trust-and-safety.md](docs/trust-and-safety.md). In short:
+
+- drives the agent CLI you already have and carries your existing permissions — for Codex under the never-approval + full-access policy the launcher passes `--dangerously-bypass-approvals-and-sandbox` so an already-authorized window cannot stall on a project-trust prompt;
+- writes run state **only** under `<workspace>\temp\orchestrator`;
+- never installs, upgrades or substitutes an agent CLI, and never transmits your credentials anywhere; the only network access it initiates is fetching its own locked dependencies (`--install-deps`);
+- `--unit-cmd` runs commands **you** supply: that is your own authorization, not an escalation.

package/LICENSE

@@ -0,0 +1,48 @@
+MIT License
+
+Copyright (c) 2026 Yang Wenchàng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+# 许可说明（中文参考）
+
+本软件以 【MIT 许可证】（MIT License）发布，属于宽松型开源许可证。法律效力以英文原文为准，以下中文说明仅作解释方便。
+
+## 你被允许做什么
+
+- **自由使用**：无论商用还是非商用，都可以自由使用、复制本软件。
+- **自由修改**：可以修改、合并、二次开发本软件。
+- **自由分发**：可以把修改后的版本再发布出去，也可以闭源商用、并入自己的项目，无需公开你自己的源代码。
+
+## 你需要满足的条件
+
+- 仅在再分发时【保留原始版权声明与许可文本】这一条实质义务。
+- 无需为你的衍生作品使用相同许可证。
+
+## 不提供担保
+
+- 本软件按“现状”（AS IS）提供，【不附带任何明示或默示担保】，包括但不限于适销性、特定用途适用性与非侵权保证。
+- 使用本软件所产生的一切风险由使用者自行承担。
+
+## 免责声明
+
+- 本技能用于【自动拆解并编排执行真实任务】，涉及文件写入、构建、安装、测试、重启、进程管理等真实操作，可能导致项目文件变更、服务中断、数据丢失等风险。
+- 使用前请自行审阅、备份并按需配置；版权持有人不对因使用本软件产生的任何直接或间接损害承担责任。

package/README-zh.md

@@ -0,0 +1,181 @@
+# open-tui-orchestrator
+
+面向带 CLI（命令行接口）的 Agent（能够接收任务并调用工具完成工作的智能体）的本地 Node.js 编排器。
+
+**当前仅支持 Windows。** 启动器、不可见 ConPTY 载具与机器级协调器都是 Windows 专有实现；其它平台会直接给出诊断而不是「半能用」的安装。运行前请读 [docs/trust-and-safety.md](docs/trust-and-safety.md)——它直说这个工具在你的机器上做什么（隐藏窗口里以你的凭据运行的 agent、Codex 宿主运行的审批旁路、它到底写哪些文件）。安全报告：[SECURITY.md](SECURITY.md)；参与开发：[CONTRIBUTING.md](CONTRIBUTING.md)。
+
+## 大体介绍
+
+open-tui-orchestrator 面向复杂、较长、包含多个可独立推进部分的执行请求。它先建立完整的 TODO LIST（待办清单）、原始任务账本和依赖关系，再把语义判断与确定性调度分开：模型只负责补充任务归属、资源和依赖信息，代码负责检查任务是否完整、处理冲突、划分执行块和安排依赖波次。
+
+规划结果确实存在可并行的任务时，编排器会在发起对话所在的工作区打开多个可见 TUI（终端用户界面）窗口，并让它们同时执行。每个窗口只负责自己的任务块；窗口之间通过资源冲突键、依赖关系和容量租约（限制同一时刻窗口数量的共享记录）协调。任务开始、完成、结果验收和关窗都要留下持久化证据，整批任务全部验收后才算完成。
+
+编排器服务于复杂长任务，不会把每个小指令都套上一层窗口。单任务、单块计划或只能按依赖串行推进的请求不触发开窗；CLI 返回完整的原始任务清单和规划原因，由发起 Agent 在当前对话中直接执行。只有同一依赖波次至少有两个可执行块时，才进入并行执行——默认无窗 headless（同一 launcher 换隐藏载具，不弹窗、不抢焦点），`--mode window` 可切换为可见 TUI 窗口；因此不开窗不会意味着任务被丢弃。
+
+窗口容量先从本机内存计算：先用内存 GiB 换算出厂商标称的内存 GB，再取其 3/4，得到本地允许的最大窗口数。
+
+~~~text
+标称内存 GB = round(内存 GiB × 1024 ÷ 1000)
+最大窗口数 = round(标称内存 GB × 3 ÷ 4)
+~~~
+
+`round` 表示取整。例如标称 16 GB 内存得到 12 个窗口，标称 8 GB 内存得到 6 个窗口，标称 4 GB 内存得到 3 个窗口。实际同时活动的窗口数还要经过跨运行、跨工作区的全局协调器确认；活动窗口和正在启动的预留窗口都会占用容量。任务数超过容量时，多出的任务会并入已有块，在块内按依赖串行执行，不会被推迟到下一批，也不会从原始账本中删除。
+
+例如，16 GiB 标称内存得到 12 个窗口容量；9 个互不冲突的任务会形成 9 个单任务块，最多同时打开 9 个窗口，9 项任务仍全部进入账本并完成验收。
+
+Windows Terminal 是默认承载。窗口沿用发起对话的工作目录，并以失焦、脱离父进程的方式启动，尽量不抢占正在使用的窗口。启动脚本、结果、锁、拆解缓存和恢复账本统一放在发起工作区的 `temp/orchestrator`；宿主 Agent 自己的配置、会话和凭据仍由宿主管理。PowerShell 只承担 Windows 生命周期、编码和进程树管理辅助，窗口承载和 Agent 适配优先走 Node.js 与 Windows Terminal。
+
+Codex、pi、opencode、Kimi Code、Claude Code 和固定版本 OpenClaw 适配器（把不同宿主 CLI 的参数、输出和关闭方式转换成统一协议）已经接通。宿主由 `--agent`/`ORCH_AGENT`、宿主环境标记或 Windows 祖先进程链自动识别——哪个 agent 发起，窗口就用哪个 agent 的 CLI，且窗口继承发起窗当前使用的 model 与 thinking effort（显式 `ORCH_MODEL`/`ORCH_EFFORT` 优先；否则按宿主检测——Codex rollout、Kimi Code 会话 wire 日志、pi settings、opencode 与 Claude 配置，画像 agent 按其 `modelDetection` 规格——最后回退到 CLI 自身配置）。未知 Agent、未验证的 CLI 或缺失的可执行文件会直接给出诊断，不会自动安装，也不会回退到另一个 Agent。已经授权的执行上下文在 TUI 窗启动后直接执行，不插入额外人工确认；编排器只继承调用方已有权限，不扩大权限范围。
+
+## 安装
+
+```powershell
+npm install -g open-tui-orchestrator
+open-tui-orchestrator --install-deps          # 拉取本包锁定的 SDK 依赖（联网一次）
+open-tui-orchestrator --agent codex --doctor  # 验证：hostError null、carrierAvailable true
+```
+
+环境要求：Windows 10/11（x64）、Node.js 22+、Windows Terminal（推荐），以及一个你**已经安装并登录**的 agent CLI——Codex、pi、opencode、Kimi Code、Claude Code 或版本锁定的 OpenClaw。工具不会安装或替换任何 agent CLI。tarball 安装、源码安装、升级/回滚、卸载与排错见 **[INSTALL-zh.md](INSTALL-zh.md)**（English: [INSTALL.md](INSTALL.md)）；公开可用性的现状与缺口见 [docs/public-readiness.md](docs/public-readiness.md)。
+
+## 什么时候适合使用
+
+它适合一次请求同时涉及多个项目、多个目录、多个相互独立的修复，或者需要先完成前置工作再进行收尾验证的长流程。编排器会先保留完整任务清单，再做项目归属、资源冲突和依赖分析；只读分析、方案讨论以及编排器自身的修改留在发起对话。
+
+简单小任务、单个动作、纯串行链条和只读请求直接在当前 Agent 中完成更合适。`--spawn` 是“明确要求单独打开一个可见窗口”的手动入口，不代表普通编排请求会为单任务开窗。
+
+## 快速开始
+
+命令从发起对话的工作区执行，不需要先切换到安装目录。下面假设 `cli.mjs` 已在当前目录或调用路径中；也可以替换成安装目录的绝对路径：
+
+~~~powershell
+node cli.mjs --agent codex --doctor
+node cli.mjs --agent pi --doctor
+node cli.mjs --agent claude --doctor
+node cli.mjs --agent openclaw --doctor
+node cli.mjs --agent codex --workspace 'D:\your-project' --plan '修复项目81登录页并优化项目82购物车'
+node cli.mjs --agent codex --workspace 'D:\your-project' --run-windows '修复项目81登录页并优化项目82购物车'
+node cli.mjs --tasks '修复项目81登录页；优化项目82购物车'
+node cli.mjs --plan-file plan.json --unit-cmd-file unit.json --run-windows '修复项目81登录页；优化项目82购物车'
+~~~
+
+`--plan` 只规划不执行；新鲜的 `--run-windows` 只有检测到并行波次才开窗；`--resume-run <id>` 接管中断后的已保存运行；`--verify-run <id>` 只重新验收，不重跑任务；`--status --readonly` 查看窗口、租约与活动 run 看板行；`--watch <id> [--jsonl]` 只读流式查看执行看板；`orch` 命令是强制编排入口——等价于 `--run-windows` 但跳过全部 inline 回退（单块、纯串行、只读定性、自改请求都会照常派发单元），除维护锁外 100% 被调用。发起窗把看板流镜像进 Kimi Code 原生 TodoList / 后台任务的固化套路与字段映射见 `docs/kimi-integration.md`；未适配的 print-class agent CLI 用 `node scripts/adapt.mjs`（或 `ORCH_AUTO_ADAPT=1` 自动模式）完成探测→画像→活验→重封→自动提交，见 `docs/adapt.md`。任何 agent 还可以完全不带适配器地调用：`--plan-file` 接收调用方自己的账本/分块（全程零模型调用），`--unit-cmd`/`--unit-cmd-file` 自带单元命令，直接绕过宿主识别、探测与适配器名单；`--tasks "<请求>"` 打印权威 `T001…` 账本，便于先对齐 id——详见 `docs/caller-driven.md`。安装依赖可运行 `npm run setup`，离线回归运行 `npm test`。
+
+## 起因：为什么要做这个工具
+
+起因有两个。
+
+第一个起因，是为了让 Kimi K3 发挥更大的能力，我专门安装了 KimiCode 来使用 Kimi K3。在一次代码量极大的 review（代码审查）任务中，Kimi K3 让 KimiCode 启动了 swarm（并行代理群），同时派出 10 个 coder subagents（编码子代理）执行不同部分。我看到后认为，这种并行执行在大任务上确实能显著缩短等待时间、提高整体吞吐。
+
+![KimiCode 启动 10 个 coder subagents 的现场截图](docs/assets/kimicode-agent-swarm-10-subagents.png)
+
+*图：KimiCode 在 Kimi K3 驱动下同时派出 10 个 coder subagents。这是本项目并行窗口设计的动机参考图，不是 open-tui-orchestrator 的运行截图。*
+
+第二个起因，是我观察到KimiCode 在 Kimi K3 驱动下，在处理事情时通常会先列出 TODO LIST，再开始执行。对于复杂、持续时间长、容易漏步骤的任务，先把目标、依赖、动作、验证和收尾写清楚，再逐项推进，能明显提高过程稳定性。
+
+于是，我想在我用的其它 Agent 中也能多并发+TODO LIST，然而并不是所有 Agent 都可以自由启动大量 subagents，也不是所有 Agent 都会用TODO LIST干活。因此，一个通用的替代办法就是调用它已经安装好的 CLI，打开多个 TUI 窗口并行执行。多个窗口各自运行一个独立任务块，效果与同时启动多个 subagents 接近，但不要求宿主 Agent 本身具备子代理编排能力。TODO LIST 则由技能约束和执行协议固定下来：主控先保留完整原始任务，窗口内再按块列清单、写检查点、逐项更新状态。
+
+诚实地说，这两个能力对简单小活属于杀鸡用牛刀，所以这个编排器从来不是为了让所有请求都弹窗。它的目标是让 Agent 在复杂长任务中稳定使用 TODO LIST；能安全并行的部分，以至少两个 TUI 窗口同时执行；可打开的窗口数由“标称内存 GB × 3 ÷ 4 后取整数”计算最大并发限制数，其中标称内存 GB = round(内存 GiB × 1024 ÷ 1000)。若请求只有一个任务、只有一个块，或依赖关系决定它只能串行，编排器就不触发开窗机制，由发起 Agent 在当前对话中直接处理。若任务多于窗口上限，多出的任务会并入某个已有块串行完成，最终账本必须覆盖每一项原始任务。
+
+## 具体实现思路
+
+### 1. 先确认工作区和资源容量
+
+编排器从调用进程的当前目录或 `--workspace` 确定工作区，先创建并使用该工作区下的 `temp/orchestrator` 作为状态之家。随后读取本机内存，先按 `round(内存 GiB × 1024 ÷ 1000)` 换算出标称内存 GB，再按 `round(标称 GB × 3 ÷ 4)` 计算窗口容量。容量是整个用户会话的共享上限，活动窗口和正在启动的预留窗口都会计入。
+
+### 2. 建立不可丢失的原始任务账本
+
+主控先按请求边界建立 `T001`、`T002` 等稳定任务 ID，保留每一项原文，并把它们作为 TODO LIST 的权威来源。规划模型只能补充项目归属、资源提示、依赖和可行性判断，不能凭“已完成”或“不可行”标记删除任务，也不能用摘要替换原文。模型输出缺项、重复、格式错误或无法确认归属时，系统保留完整原始清单并采用串行安全计划。
+
+### 3. 把语义判断和确定性分块分开
+
+规划阶段只让模型做扁平任务定性：任务是什么、属于哪个项目、会碰哪些资源、依赖哪些任务。真正的分块由代码完成：
+
+- 同一项目或同一资源目录的任务归到同一块，避免互相覆盖。
+- 同项目任务再做精细化拆分：分类器为每个任务给出精确资源关键词（conflict_hints）时，按资源键重叠聚类——互不重叠的任务各自成块并行开窗（只带精确资源键，不再共用项目目录键）；任一任务说不清资源或全部纠缠时才退回单块串行（项目目录键兜底）。
+- 明确没有冲突且没有依赖的任务保留为独立块。
+- 未知归属的任务进入保守的串行块，不把孤儿任务误放进并发波次。
+- 依赖关系先校验未知、自指和循环，再映射到块级依赖。
+- 同一波次只启动依赖已验收的块；无关块不互相排队。
+
+### 4. 应用容量上限，而不是制造额外队列
+
+确定性计划完成后，按容量压缩块数。压缩只会把任务合入已有块，并把合并块标记为 `linked`（块内严格串行）；它不会产生第 9 个窗口，也不会把剩余任务悄悄推迟到下一轮。压缩前后都检查原始任务 ID 集合，确保数量、唯一性和顺序可追溯。
+
+### 5. 用并行波次决定是否开窗
+
+代码会把计划转换为依赖波次，并应用明确的开窗策略：
+
+- 只有一个块：返回 `mode: inline`，不创建运行窗口。
+- 多个块但每个波次只有一个块：返回 `mode: inline`，不为串行链打开窗口。
+- 某个波次至少有两个块：返回 `mode: windows`，按该波次并行启动至少两个 TUI 窗口；同一波次的实际数量仍不能超过内存容量。
+
+`inline` 返回中包含原始请求、完整任务账本、块标题、依赖和下一步提示，因此“不开窗”不会变成“任务没执行”或“任务被吞掉”。
+
+### 6. 在 Windows Terminal 中启动失焦窗口
+
+每个块获得唯一运行 ID、尝试编号和 token（本次窗口的唯一结束标识）。Windows Terminal 负责承载可见界面，启动时继承发起工作区和已授权的宿主参数；分离式启动器不会主动把新窗口置前。若 Windows Terminal 不可用，才退回传统控制台承载，不会退回另一个 Agent。关闭时只根据已核对的 launcher（启动器）进程身份处理自己的进程树，不结束共享的 Windows Terminal 主进程。
+
+### 7. 在每个窗口内固定 TODO 和执行纪律
+
+窗口启动后先检查环境并列出本块 TODO LIST，保留原始任务 ID、目标、依赖、动作、验证和收尾。每项开始前写入 `started` 检查点，完成并自验后写入 `completed` 检查点；失败就保留现场证据，不把口头汇报当成成功。窗口不得再次调用编排器、不得递归开窗，也不得把其它任务混入本块。
+
+### 8. 通过多重证据判定完成
+
+窗口最后输出带自身 token 的 `__ORCH_DONE__` 标记，watchdog（完成监视器，在窗口异常退出前持续观察收尾证据）据此自动收尾。但结束标记只表示窗口完成了自己的收尾动作，不表示业务结果一定正确。主控还要：
+
+- 读取每个块的检查点和结果文件。
+- 按父级提供的只读验收条件核对真实落盘文件、JSON 或命令结果。
+- 确认所有原始任务都有最终状态。
+- 确认窗口进程已经关闭且租约已释放。
+- 只有全部任务 `verified` 才把整批标记为成功。
+
+### 9. 中断恢复和幂等保护
+
+每次尝试都把剩余任务 ID、工作区、token、PID（进程标识）和启动文件写入运行账本。恢复时先按进程身份、创建时间、可执行文件和命令行接管仍存活的窗口，不重复启动替代窗口。已经验收的任务不会重做；已开始但副作用无法证明的任务进入 `needs-reconciliation`（需要主控核对实际状态），不会盲目重跑。依赖失败的后续任务保留在账本中并明确阻塞原因。
+
+### 10. 以适配器隔离不同 Agent
+
+通用入口通过 `--agent` 或 `ORCH_AGENT` 选择宿主；两者都缺省时，先按宿主环境标记（`CODEX_THREAD_ID`/`CODEX_SESSION_ID`），再按 Windows 祖先进程链（kimi.exe / codex.exe / claude.exe / pi-coding-agent / opencode / openclaw，就近命中）自动识别发起方。Codex、pi、opencode、Kimi Code、Claude Code 和固定版本 OpenClaw 各自实现参数拼接、会话/结果读取、完成判定和关闭流程；通用调度器只依赖统一协议。新 Agent 必须同时通过 CLI 发现、规划、交互启动、输出解析、完成和清理验证，不能只添加一个命令名。
+
+### 11. 弱网和无二次确认执行
+
+Codex 规划和窗口沿用现有 HTTPS Responses 配置，避免先等待 WebSocket 再回退；网络暂时中断时由宿主 CLI 的重试和截止时间处理，状态写入工作区账本。已授权窗口直接开始工作，不重复要求人工确认；编排器只传递调用方已经拥有的权限，不把自身变成权限提升工具。
+
+### 12. 清理、发布和验证
+
+运行结束后只清理本批已结束且由本批拥有的启动器、日志、结果和临时文件，保留运行账本和必要验收证据；活动窗口及其它工作区状态不会被误删。核心文件用 `release.json` 的 SHA-256 发布封印（固定发行清单的完整性校验）保护，核心或运行时变更后必须重新封印并验证。
+
+### 13. 维护锁：自身维护期间暂停编排
+
+对编排器自身做升级/优化/维护/更新等改动前，先上维护锁：`node scripts/maintenance-lock.mjs lock --reason "原因" [--ttl-minutes N]`。上锁期间任何 agent 调用编排器的动作入口（`orch`、`--run-windows`/`--spawn`/`--resume-run`/`--run`/`--exec`/`--plan`、`open-tui-orchestrator-preflight.mjs`、`open-tui-orchestrator-force.mjs --assert/--verify`）都只返回一句话：`open-tui-orchestrator正在维护更新，本轮跳过orchestrator直接开始执行`，并以退出码 0 放行，由发起对话本轮直接执行。只读入口（`--status`/`--doctor`/`--verify-run`/`--clear-cache`/`--tasks`）不受影响，`--status` 会额外显示锁状态。锁全局按用户生效（默认 `~/.open-tui-orchestrator/maintenance-lock.json`，可用 `ORCH_MAINTENANCE_LOCK` 覆盖），默认 180 分钟自动过期（上限 24 小时），过期或文件损坏一律 fail-open 视为未锁，绝不会把编排器卡死；`repair.mjs --clean`/`--target` 在未持锁时会自行上锁、结束即解。维护结束用 `node scripts/maintenance-lock.mjs unlock` 解锁。
+
+## 相关文档
+
+- [执行与验收协议](docs/execution-contract.md)
+- [发行策略](docs/release-policy.md)
+- [Pi 适配说明](docs/pi-adapter.md)
+- [OpenClaw 执行与隔离说明](docs/openclaw-adapter.md)
+- [Kimi Code 适配器](docs/kimi-adapter.md)
+- [opencode 适配器](docs/opencode-adapter.md)
+- [Claude Code 适配器](docs/claude-adapter.md)
+- [新 agent CLI 自动适配（print-class 画像）](docs/adapt.md)
+- [调用方自助通道：计划文件 + 单元命令（任何 agent）](docs/caller-driven.md)
+- [Kimi Code 接入：看板流 → 原生 TodoList](docs/kimi-integration.md)
+- [失焦窗口验证](docs/inactive-windows.md)
+- [异常中断后自动恢复](docs/auto-recovery.md)
+- [维护锁](docs/maintenance-lock.md)
+
+## 当前支持与验证边界
+
+Codex CLI、pi CLI、opencode CLI、Kimi Code CLI、Claude Code CLI 和 OpenClaw 2026.9.2 CLI 已完成适配。运行诊断：
+
+~~~powershell
+node cli.mjs --agent codex --doctor
+node cli.mjs --agent pi --doctor
+node cli.mjs --agent claude --doctor
+node cli.mjs --agent openclaw --doctor
+~~~
+
+当前通用核心为 1.14.6，离线回归为 292/292 通过；覆盖无窗 headless 派发默认（`--mode window` 保留可见弹窗；launcher/身份/租约/恢复契约同构，隐藏载具不抢焦点）、单元载体分级（TUI 类 agent 走 ConPTY 伪终端载体——真实控制台、无窗口、不抢焦点，身份/租约/恢复契约与窗口模式同构；print 类维持无控制台载体）、执行看板（块与任务状态实时 `[board]` 行、run `events.jsonl`、只读 `--watch <runId>` 流式视图含 `--jsonl`、`--status` 活动 run 摘要）、任务不丢失、多块并行容量调度、依赖波次、同项目任务按资源键精细化拆分、全局容量租约（排队块等待指数退避+抖动；`ORCH_WAIT_BACKOFF_MS`/`ORCH_WAIT_BACKOFF_MAX_MS` 可调；协调器互斥等待亦可调可重试：`ORCH_MUTEX_WAIT_MS`/`ORCH_MUTEX_RETRIES`，锁票按龄回收 `ORCH_MUTEX_TICKET_TTL_MS`）、Windows Terminal 启动（同步拉起，弹窗可靠且不抢发起窗焦点）、失焦启动回归、进程身份、断点恢复、恢复账本加固（launcherFiles 工作区包容、验收契约哈希绑定、注册表锁老化回收）、守护进程驱动的控制器丢失自动恢复（test/guardian-live-result.json）与手动 --resume-run 收编存活窗口恢复（test/recovery-live-result.json）、发起方自动识别（环境标记优先、进程链兜底：kimi/codex/claude/pi/opencode/openclaw/hermes）、`orch` 强制编排入口、print-class 数据驱动画像适配管线（表面探测→画像→解析自检→活验守门→重封→自动提交，失败一律回滚；画像 agent 按 `modelDetection` 跟随发起窗 model/effort；hermes 画像已落地——hermes 发起即自动挡：识别其身份并以自身 CLI 执行（`--no-restore-cwd` 防旧会话 CWD 写偏））、调用方自助通道（调用方自带计划文件在覆盖/依赖/回退保证不变的前提下跑通且全程零模型调用、调用方自带单元命令让任意 CLI 走同一启动器/租约/恢复/验收契约、只读 `--tasks` 账本助手、单元命令的 resume 身份一致性、未知 agent 的两条出路诊断）、档位去向留痕（summary 记录 model/effort 与三态来源：explicit/宿主会话/host-default；机器可读入口 stdout 保持纯数据）、机器可调用失败契约（公开入口失败一律只回一行 `[orchestrator] FATAL: <原因>`、无 Node 栈帧（`ORCH_DEBUG=1` 才打）；未知 run 不甩 `ENOENT`、不挂起——`--verify-run`/`--resume-run` 立刻回 `Run not found: <id>`，`--watch` 先给有界宽限 `ORCH_WATCH_GRACE_MS`（默认 60s，覆盖 `--run-windows` 仍在规划、run 目录尚未建立的竞态）再拒，看板中途丢 `summary.json` 也立刻报错而不静默停摆）、维护锁、当前核心安全审计及修复（docs/security-audit-2026-09-09.md）、弱网配置、SDK 诊断、宿主 CLI 探测超时重试与逐候选拒绝诊断、OpenClaw 版本门诊断（tui 接口探针先行：未验证版本以探针实测结果 + 最后验证版本 fail-closed——版本常量只记「最后验证于」，不是准入门槛）、恢复账本校验覆盖盘符根工作区和干净发行副本。测试环境要求：离线套件假定发起 agent 的 CLI（默认 `codex`）可在 PATH 解析（Windows 下前置 codex vendor bin，即回归环境约定）；缺失时依赖 agent 解析的测试文件按设计快速失败（fail-closed），其中两个运行期依赖 CLI 的用例已标注 `{skip}`。真实模型额度、不同 Windows 用户安装、长时间断网恢复和每个未来 Agent 的现场兼容性也仍需单独验收。
+
+未知宿主、无可执行 CLI 或显式路径无效时，命令会直接失败并给出原因；不会自动安装、猜测替代路径或换用其它 Agent。