input-kanban 0.0.1 → 0.0.3

package/ENVIRONMENT.md

@@ -11,6 +11,7 @@ CLI options take precedence over environment variables. Environment variables ta
 - `KANBAN_DEFAULT_REPO`: Default target repository path for new runs. Default: the current working directory when `input-kanban` is launched. CLI option: `--repo`.
 - `KANBAN_RUNS_DIR`: Directory for run state, logs, and artifacts. Default: `.input-kanban/runs` under the user's home directory. CLI option: `--runs-dir`.
 - `KANBAN_CODEX_BIN`: Codex CLI executable name or path. Default: `codex`. CLI option: `--codex-bin`.
+- `KANBAN_RUNNER`: Runner mode. Supported values: `headless`, `tmux`. Default: `headless`. CLI option: `--runner`.
 
 ## Environment Example
 
@@ -19,6 +20,7 @@ PORT=8787 \
 KANBAN_DEFAULT_REPO=/path/to/child-repo \
 KANBAN_RUNS_DIR=/path/to/kanban-runs \
 KANBAN_CODEX_BIN=codex \
+KANBAN_RUNNER=headless \
 input-kanban
 ```
 
@@ -29,11 +31,15 @@ input-kanban \
   --port 8787 \
   --repo /path/to/child-repo \
   --runs-dir /path/to/kanban-runs \
-  --codex-bin codex
+  --codex-bin codex \
+  --runner headless
 ```
 
 ## Notes
 
 - `KANBAN_DEFAULT_REPO` / `--repo` should point to the actual git repository where work should run.
+- `KANBAN_RUNNER` / `--runner tmux` runs Codex tasks inside tmux windows while keeping scheduling and status tracking in the Node.js orchestrator.
+- `KANBAN_RUNNER=tmux` is optional. Use it when you want live terminal visibility into planner, worker, and final judge sessions, or when you need to manually respond to Codex CLI approval prompts.
+- tmux mode does not implement automatic approval. It does not bypass Codex CLI, repository, or system permission boundaries; any approval prompt must still be explicitly approved by the user in the relevant tmux window.
 - The runtime runs directory contains task text, logs, model output, artifacts, and possible audit information. It should not be committed to git.
 - Avoid writing machine-specific absolute paths into public or shared documentation.

package/PROJECT_GUIDE.md

@@ -322,6 +322,30 @@ npm run check
 
 When editing `public/index.html`, also consider extracting the inline script and checking it with `node --check`.
 
+## Manual Smoke Checklist
+
+Use this checklist before an npm release when runner behavior or package contents
+change. Record the exact commands, run ids, and artifact paths in the release
+notes or handoff.
+
+1. Headless runner:
+   - Start the app with `input-kanban --runner headless --runs-dir <tmp-runs-dir> --repo <target-repo> --port <free-port>`.
+   - Create a small run, plan it, dispatch at least one worker, and run the final judge if the plan requires it.
+   - Verify the run state reports `runner: headless`, no task exposes `tmux` metadata, and role directories contain the expected `prompt.md`, `events.jsonl`, `stderr.log`, `last_message.md`, and `exit_code` files.
+   - Stop the run and verify no unrelated local process is affected.
+
+2. tmux runner, only when `tmux -V` succeeds:
+   - Start the app with `input-kanban --runner tmux --runs-dir <tmp-runs-dir> --repo <target-repo> --port <free-port>`.
+   - Create a small run and click Plan. Verify a session named `input-kanban-<runId>` exists and has a planner window.
+   - Dispatch workers. Verify each worker gets its own window and each role directory writes `run.sh` and `tmux.json` with the expected `sessionName`, `windowName`, `target`, `attachCommand`, and `selectWindowCommand`.
+   - Complete or stop the run. Verify stop removes only the exact `input-kanban-<runId>` tmux session and leaves any other tmux session running.
+   - Do not mark this smoke as passed when tmux is unavailable or when these tmux checks were not run.
+
+3. Package dry run:
+   - Run `npm pack --dry-run`.
+   - Verify the package includes `bin/`, `src/`, `public/`, `README.md`, `README.en.md`, `PROJECT_GUIDE.md`, `ENVIRONMENT.md`, and `package.json`.
+   - Verify no runtime run directories, local logs, or unrelated temporary artifacts are included.
+
 ## Change Guidelines
 
 - Do not add automatic worker retry unless there is a verified rollback or idempotency mechanism.

package/README.en.md

@@ -0,0 +1,148 @@
+# Input Kanban
+
+[中文](README.md) | English
+
+Input Kanban is a local Codex orchestration dashboard. The recommended path is to install it from npm, run `input-kanban` inside the target repository, and use the browser UI to manage planning, worker execution, and final judging.
+
+## Recommended Usage
+
+### 1. Install
+
+```bash
+npm install -g input-kanban
+```
+
+Verify the installation:
+
+```bash
+input-kanban --help
+```
+
+### 2. Start in the Target Repository
+
+Enter the repository you want Codex to modify or inspect:
+
+```bash
+cd /path/to/your/repo
+input-kanban
+```
+
+By default, this starts a local server at:
+
+```text
+http://127.0.0.1:8787
+```
+
+Open that URL in your browser to use the dashboard.
+
+### 3. Start with an Explicit Repository
+
+If you do not want to `cd` into the target repository first, pass it explicitly:
+
+```bash
+input-kanban --repo /path/to/your/repo
+```
+
+## Common Startup Options
+
+```bash
+input-kanban --port 8787
+input-kanban --host 127.0.0.1
+input-kanban --runs-dir ~/.input-kanban/runs
+input-kanban --codex-bin codex
+input-kanban --runner headless
+input-kanban --open
+```
+
+Defaults:
+
+- target repository: the current directory where `input-kanban` is launched
+- host: `127.0.0.1`
+- port: `8787`
+- runs directory: `~/.input-kanban/runs`
+- Codex command: `codex`
+- runner: `headless`
+
+`--runner` currently supports `headless` and `tmux`. The default behavior remains `headless`; `tmux` creates one `input-kanban-<runId>` session per run and one window for the planner, each worker, and the final judge.
+
+tmux mode still leaves batch barriers, `maxParallel`, final judge sequencing, and `judge_input.json` generation in Node.js. Each role output directory gets `run.sh` and `tmux.json`; status continues to be driven by `events.jsonl`, `stderr.log`, `last_message.md`, `exit_code`, and existing artifact files.
+
+tmux mode is optional. It is intended for live terminal viewing of each Codex role and for cases where the Codex CLI asks the user for manual approval. It does not implement automatic approval and does not bypass Codex CLI, repository, or system permission boundaries; any approval prompt still has to be explicitly approved by the user in the relevant tmux window.
+
+## Using the Dashboard
+
+1. Click `New Run`.
+2. Enter a label, target repository, and task description.
+3. Click `Create Run`.
+4. Click `Plan` to let the Codex planner generate batches and workers.
+5. Click `Dispatch` to run workers by batch barrier and concurrency limits.
+6. Inspect execution logs, final messages, error logs, and artifacts.
+7. After all batches complete, click `Final Judge`.
+8. Stop or archive a run when needed, or manually mark a confirmed failed/unknown worker as completed.
+
+## What It Is For
+
+- Split a larger Codex programming task into multiple workers.
+- Control execution order with batch barriers.
+- Observe each worker's local status, logs, and final response.
+- Run a final judge after all workers complete.
+- Keep local run records for debugging and recovery.
+
+## Runtime Data Location
+
+Runtime data is stored in the configured runs directory. The CLI default is:
+
+```text
+~/.input-kanban/runs
+```
+
+Each run roughly looks like this:
+
+```text
+runs/<runId>/
+├── task.md
+├── plan.json
+├── run_state.json
+├── planner/
+├── workers/<taskId>/
+└── judge/
+    ├── judge_input.json
+    └── verdict.json
+```
+
+These files are local run records and do not need to be committed to your application repository.
+
+## Requirements
+
+- Node.js 20 or newer.
+- Codex CLI installed and configured.
+- The `codex` command works in your terminal, or `--codex-bin` points to the Codex executable.
+
+## Maintainer Development
+
+If you want to develop Input Kanban itself instead of using it as an end user:
+
+```bash
+git clone https://github.com/zhang3xing1/Input-Kanban.git
+cd Input-Kanban
+npm install
+npm start
+```
+
+For local CLI development:
+
+```bash
+npm link
+input-kanban --help
+```
+
+Run checks:
+
+```bash
+npm run check
+```
+
+## More Documentation
+
+- [Project guide](PROJECT_GUIDE.md)
+- [Environment variables](ENVIRONMENT.md)

package/README.md

@@ -1,140 +1,102 @@
 # Input Kanban
 
-Input Kanban is a lightweight local dashboard for splitting a Codex task into batches and workers, running them with `codex exec`, observing status, stopping or archiving runs, and performing a final judge pass.
+中文 | [English](README.en.md)
 
-For implementation details and agent-facing project context, see:
+Input Kanban 是一个本地 Codex 编排看板。推荐通过 npm 安装，然后在目标代码仓库里运行 `input-kanban`，用浏览器管理任务拆分、并发执行和最终验收。
 
-```text
-PROJECT_GUIDE.md
-```
+## 推荐使用方式
 
-For runtime environment variables, see:
+### 1. 安装
 
-```text
-ENVIRONMENT.md
+```bash
+npm install -g input-kanban
 ```
 
-## Features
+验证安装：
 
-- Static HTML dashboard with no frontend build step.
-- Node.js backend that can:
-  - create multiple runs;
-  - start a `codex exec` planner and materialize `plan.json`;
-  - safely retry planner runs before any worker or judge starts;
-  - detect `plan_empty` when the planner returns zero tasks;
-  - schedule workers by strict batch barriers and `batch.maxParallel`;
-  - generate `judge_input.json` before the final judge pass;
-  - start an independent `codex exec` final judge;
-  - aggregate PID, exit code, events, stderr, last message, artifacts, and Codex session IDs;
-  - stop runs, soft-archive runs, and manually mark failed or unknown workers as completed.
+```bash
+input-kanban --help
+```
 
-## CLI Usage
+### 2. 在目标仓库启动
 
-Run from the target repository directory:
+进入你希望 Codex 修改或检查的代码仓库：
 
 ```bash
+cd /path/to/your/repo
 input-kanban
 ```
 
-Or provide the target repository explicitly:
+默认会启动本地服务：
 
-```bash
-input-kanban --repo /path/to/repo
+```text
+http://127.0.0.1:8787
 ```
 
-Then open:
+打开浏览器访问这个地址即可使用看板。
 
-```text
-http://127.0.0.1:8787
+### 3. 指定目标仓库启动
+
+如果不想先 `cd` 到目标仓库，也可以显式指定：
+
+```bash
+input-kanban --repo /path/to/your/repo
 ```
 
-Common options:
+## 常用启动参数
 
 ```bash
 input-kanban --port 8787
 input-kanban --host 127.0.0.1
 input-kanban --runs-dir ~/.input-kanban/runs
 input-kanban --codex-bin codex
+input-kanban --runner headless
 input-kanban --open
 ```
 
-## Development
+默认值：
 
-```bash
-npm start
-```
+- 目标仓库：启动 `input-kanban` 时的当前目录
+- host：`127.0.0.1`
+- port：`8787`
+- runs 目录：`~/.input-kanban/runs`
+- Codex 命令：`codex`
+- runner：`headless`
 
-For local CLI development:
+`--runner` 当前支持 `headless` 和 `tmux`。默认行为保持 `headless`；`tmux` 会为每个 run 创建一个 `input-kanban-<runId>` session，并为 planner、每个 worker、final judge 创建独立 window。
 
-```bash
-npm link
-input-kanban
-```
+tmux 模式仍由 Node.js 负责 batch barrier、`maxParallel`、final judge 顺序和 `judge_input.json` 生成。每个角色输出目录会写入 `run.sh` 和 `tmux.json`，状态继续由 `events.jsonl`、`stderr.log`、`last_message.md`、`exit_code` 和既有 artifact 文件驱动。
 
-## Workflow
-
-1. Click `New Run`, then enter a label, target repo, max parallel value, and task text.
-2. Click `Create Run`.
-3. Click `Plan` to start the planner:
-   - planner uses `codex exec --json --sandbox read-only`;
-   - output is stored under `runs/<runId>/planner/`.
-4. When planning succeeds, `plan.json` is created and the worker list is shown.
-5. Click `Dispatch` to start workers according to batch barriers and `batch.maxParallel`.
-6. The page polls status every 3 seconds.
-7. After all batches complete, click `Final Judge` to run the final judge pass.
-
-The current UI labels are localized, but the project documentation is written in English for easier agent consumption.
-
-## Planner Output Format
-
-The preferred planner response is a JSON object with `batches`. The older `tasks` shape is also supported.
-
-```json
-{
-  "batches": [
-    {
-      "id": "batch-1",
-      "name": "first batch name",
-      "maxParallel": 3,
-      "tasks": [
-        {
-          "id": "T-01",
-          "name": "short name",
-          "prompt": "complete worker prompt",
-          "sandbox": "workspace-write",
-          "expectedArtifacts": ["tmp/example-result.json"]
-        }
-      ]
-    }
-  ],
-  "finalJudgeRequired": true
-}
-```
+tmux 模式是可选能力，主要用于在终端里实时查看每个 Codex 角色的执行过程，并在 Codex CLI 需要人工确认时让用户手动处理。它不会实现自动审批，也不会绕过 Codex CLI、仓库权限或系统权限的安全边界；所有需要确认的操作仍必须由用户在对应 tmux window 中明确批准。
 
-The backend extracts the first JSON object from `last_message.md`. If the planner succeeds but returns zero tasks, the run is marked `plan_empty` and can be planned again before any worker or judge starts.
+## 在看板里如何使用
 
-## Status Sources
+1. 点击 `新建任务批次`。
+2. 输入批次名称、目标仓库和任务说明。
+3. 点击 `创建批次`。
+4. 点击 `拆分任务`，让 Codex planner 生成 batches 和 workers。
+5. 点击 `派发执行`，按 batch barrier 和并发限制运行 workers。
+6. 查看执行日志、最终回复、错误日志和产物。
+7. 所有 batch 完成后，点击 `汇总验收`。
+8. 必要时可以停止或归档 run，也可以手动标记已确认完成的失败/未知 worker。
 
-Worker status is primarily determined from local state:
+## 它适合做什么
 
-- Node child process tracking
-- `exit_code`
-- `events.jsonl`
-- `stderr.log`
-- `last_message.md`
-- expected artifacts
+- 把一个较大的 Codex 编程任务拆成多个 worker。
+- 按批次阻塞关系控制执行顺序。
+- 在本地观察每个 worker 的状态、日志和最终回复。
+- 在所有 worker 完成后，让 final judge 汇总验收。
+- 保留本地运行记录，便于排查和恢复。
 
-Codex App Server is an auxiliary source only:
+## 运行数据保存位置
 
-- the backend starts `codex app-server --stdio`;
-- it calls `thread/list`;
-- it matches sessions using prompt markers:
-  - `ORCHESTRATOR_RUN_ID`
-  - `ORCHESTRATOR_TASK_ID`
+运行数据会保存到 runs 目录。CLI 默认位置是：
 
-A Codex App Server `notLoaded` state does not mean a worker failed. The local process, exit code, logs, and artifacts remain the source of truth.
+```text
+~/.input-kanban/runs
+```
 
-## Runtime Directory
+每个 run 大致结构如下：
 
 ```text
 runs/<runId>/
@@ -148,10 +110,39 @@ runs/<runId>/
     └── verdict.json
 ```
 
-The development `runs/` directory is gitignored. For CLI usage, the default runtime directory is `~/.input-kanban/runs`.
+这些文件是本地运行记录，不需要提交到你的业务仓库。
+
+## 使用前提
 
-## Checks
+- 已安装 Node.js 20 或更高版本。
+- 已安装并配置可用的 Codex CLI。
+- `codex` 命令能在终端中正常运行，或通过 `--codex-bin` 指定 Codex 可执行文件路径。
+
+## 维护者开发
+
+如果你要开发 Input Kanban 本身，而不是作为用户使用：
+
+```bash
+git clone https://github.com/zhang3xing1/Input-Kanban.git
+cd Input-Kanban
+npm install
+npm start
+```
+
+本地 CLI 开发：
+
+```bash
+npm link
+input-kanban --help
+```
+
+检查：
 
 ```bash
 npm run check
 ```
+
+## 更多文档
+
+- [项目实现说明](PROJECT_GUIDE.md)
+- [环境变量](ENVIRONMENT.md)

package/bin/input-kanban.js

@@ -2,8 +2,15 @@
 import path from 'node:path';
 import { spawn } from 'node:child_process';
 
+const VALID_RUNNERS = ['headless', 'tmux'];
+
+function validateRunner(value, source) {
+  if (VALID_RUNNERS.includes(value)) return value;
+  throw new Error(`invalid ${source}: ${value}; expected one of: ${VALID_RUNNERS.join(', ')}`);
+}
+
 function parseArgs(argv) {
-  const args = { host: '127.0.0.1', port: undefined, repo: undefined, runsDir: undefined, codexBin: undefined, open: false, help: false };
+  const args = { host: '127.0.0.1', port: undefined, repo: undefined, runsDir: undefined, codexBin: undefined, runner: undefined, open: false, help: false };
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     const next = () => argv[++i];
@@ -15,6 +22,7 @@ function parseArgs(argv) {
     else if (arg === '--repo' || arg === '-r') args.repo = next();
     else if (arg === '--runs-dir') args.runsDir = next();
     else if (arg === '--codex-bin') args.codexBin = next();
+    else if (arg === '--runner') args.runner = validateRunner(next(), '--runner');
     else throw new Error(`unknown argument: ${arg}`);
   }
   return args;
@@ -32,6 +40,7 @@ Options:
   -r, --repo <path>      Default target repository, default current directory
   --runs-dir <path>      Runtime runs directory, default ~/.input-kanban/runs
   --codex-bin <path>     Codex CLI executable, default codex
+  --runner <mode>        Runner mode: headless or tmux, default headless
   --open                 Open browser after starting
   --no-open              Do not open browser, default
   -h, --help             Show help
@@ -54,6 +63,7 @@ try {
   else if (!process.env.KANBAN_DEFAULT_REPO) process.env.KANBAN_DEFAULT_REPO = process.cwd();
   if (args.runsDir) process.env.KANBAN_RUNS_DIR = path.resolve(args.runsDir);
   if (args.codexBin) process.env.KANBAN_CODEX_BIN = args.codexBin;
+  if (args.runner) process.env.KANBAN_RUNNER = args.runner;
 
   const { startServer } = await import('../src/server.js');
   const instance = await startServer({ host: process.env.HOST, port: Number(process.env.PORT || 8787), log: false });
@@ -61,6 +71,7 @@ try {
   console.log(`URL:  ${instance.url}`);
   console.log(`Repo: ${instance.defaultRepo}`);
   console.log(`Runs: ${instance.runsDir}`);
+  console.log(`Runner: ${instance.runner}`);
   if (args.open) openBrowser(instance.url);
   const shutdown = () => { instance.stop().finally(() => process.exit(0)); };
   process.on('SIGINT', shutdown);

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "input-kanban",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "type": "module",
   "bin": {
     "input-kanban": "bin/input-kanban.js"
   },
   "scripts": {
     "start": "node bin/input-kanban.js",
-    "check": "node --check bin/input-kanban.js && node --check src/server.js && node --check src/orchestrator.js && node --check src/appServerClient.js && node --check src/utils.js"
+    "check": "node --check bin/input-kanban.js && node --check src/server.js && node --check src/orchestrator.js && node --check src/appServerClient.js && node --check src/utils.js && node --check src/runners/index.js && node --check src/runners/headlessRunner.js && node --check src/runners/tmuxRunner.js && node --check src/runners/tmuxUtils.js && node --check src/tmux.js && node --test"
   },
   "dependencies": {},
   "description": "A local Codex orchestration kanban dashboard",
@@ -16,6 +16,7 @@
     "src",
     "public",
     "README.md",
+    "README.en.md",
     "PROJECT_GUIDE.md",
     "ENVIRONMENT.md"
   ],