input-kanban 0.0.2 → 0.0.4

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,18 @@ 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.
+- tmux mode uses one session per run and one window for planner, each batch, and judge. Batch windows contain an overview pane plus worker panes.
+- tmux role windows stay open after the Codex command exits. The runner writes `exit_code` before entering the keep-open shell so Node.js status refresh can continue to advance from filesystem state.
+- The dashboard exposes the run-level `tmux attach-session` copy action after tmux metadata is available. File viewer panels do not repeat tmux terminal details.
+- `codex exec` is non-interactive in current supported usage. tmux mode does not implement automatic approval and does not turn `codex exec` into an approval UI.
 - 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

@@ -7,7 +7,7 @@ This document explains how Input Kanban is implemented so that humans and coding
 Implementation status:
 
 ```text
-mvp / batch-scheduler / codex-exec-primary / buildkite-style-ui / manual-recovery / stop-archive / cli-bootstrap
+mvp / batch-scheduler / codex-exec-primary / tmux-batch-layout / buildkite-style-ui / manual-recovery / stop-archive / cli-bootstrap
 ```
 
 Recent validation:
@@ -37,6 +37,10 @@ The intended use case is:
 - Workers can modify the target repository. Failed workers are not automatically retried because a partial modification may already exist.
 - The planner only creates a plan and does not modify the target repo. Planner failures, invalid output, and empty plans can be safely retried before any worker or judge starts.
 - Local process state, `exit_code`, logs, and artifacts are the source of truth. Codex App Server session lookup is auxiliary.
+- tmux mode changes terminal visibility only. Node.js still owns scheduling, batch barriers, `maxParallel`, stop/archive, `judge_input.json`, and status refresh from `exit_code` plus artifacts.
+- tmux windows stay open after command completion for human inspection, but `exit_code` is written before the keep-open shell starts so state can advance without closing the window.
+- Dashboard tmux attach copy actions are shown only after tmux metadata is present. The file viewer does not repeat tmux terminal details.
+- `codex exec` is treated as non-interactive; tmux mode provides live terminal visibility, not an approval UI.
 - There is no batch-level judge. Only one final judge pass runs after all batches complete.
 
 ## CLI Entry
@@ -98,7 +102,7 @@ A task is one worker inside a batch. Batch-level parallelism is controlled by `b
 ### Roles
 
 - `planner`: read-only `codex exec` that returns a plan.
-- `worker`: normally `workspace-write` `codex exec` that performs work.
+- `worker`: `codex exec` that performs work. The run-level worker sandbox defaults to `workspace-write`, and the create form can explicitly select `read-only` or `danger-full-access`.
 - `judge`: read-only `codex exec` that performs final evaluation.
 
 ## Run State Machine
@@ -219,12 +223,13 @@ It can read planner, worker, and judge files.
 Current behavior:
 
 - Selecting a task updates the file viewer title to `runId / taskId`.
-- If a file tab is already open, switching tasks reloads the same file for the newly selected task.
+- File tabs are role-specific. Planner, worker, and judge views expose only their common or relevant files.
+- If a file tab is already open, switching tasks reloads the same file only when that role exposes the same tab; otherwise the file view is cleared.
 - Auto refresh also reloads the selected task's selected file and attempts to preserve scroll position.
 - `events.pretty` is a virtual file generated by formatting `events.jsonl` into a readable Chinese execution log.
 - The execution view shows event counts and a jump-to-bottom button.
 - `last_message.md` has a hover copy button in the top-left of the text area.
-- `judge_input.json` can be viewed through the `Judge Input` tab.
+- `judge_input.json` and `verdict.json` are shown for the judge role. `exit_code` is not a default file tab because the task table already shows exit codes.
 
 ## Files and Responsibilities
 
@@ -322,6 +327,33 @@ 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 batch gets its own window with an overview pane plus worker panes, and each role directory writes `run.sh` and `tmux.json` with the expected `sessionName`, `windowName`, `target`, and `attachCommand`.
+   - Verify `run.sh` writes `exit_code` before printing the keep-open summary, then keeps the window open for manual inspection.
+   - Verify status refresh can advance planner, workers, and judge to `completed`, `planned`, or `judged` from filesystem state while tmux windows remain open.
+   - Verify the UI does not show run attach copy before tmux metadata exists, then shows `复制tmux attach指令` in the run detail header after metadata exists. Verify the file viewer does not show a separate tmux terminal info panel.
+   - 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

@@ -50,6 +50,7 @@ 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
 ```
 
@@ -60,11 +61,20 @@ Defaults:
 - 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 batch, and the final judge. A batch window contains an overview pane plus the worker panes for that batch.
+
+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. After a tmux role command finishes, it writes `exit_code` first and then keeps the window open for inspection; the user closes the window manually from tmux.
+
+tmux mode is optional and intended for live terminal viewing of each Codex role. `codex exec` is currently non-interactive and does not normally show manual approval prompts; if you select `danger-full-access` when creating a run, you explicitly relax the worker sandbox and should only do so in a controlled test repository.
+
+After run-level tmux metadata is available, the dashboard shows `Copy tmux attach command`. The file viewer no longer repeats tmux terminal details; use the run detail header to copy the attach command and inspect the tmux session.
 
 ## Using the Dashboard
 
 1. Click `New Run`.
-2. Enter a label, target repository, and task description.
+2. Enter a label, target repository, worker sandbox, 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.
@@ -77,6 +87,7 @@ Defaults:
 - 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.
+- In tmux runner mode, inspect an overview pane and worker panes inside each batch window.
 - Run a final judge after all workers complete.
 - Keep local run records for debugging and recovery.
 
@@ -108,6 +119,7 @@ These files are local run records and do not need to be committed to your applic
 
 - Node.js 20 or newer.
 - Codex CLI installed and configured.
+- `tmux` installed when using `--runner tmux`.
 - The `codex` command works in your terminal, or `--codex-bin` points to the Codex executable.
 
 ## Maintainer Development

package/README.md

@@ -50,6 +50,7 @@ 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
 ```
 
@@ -60,11 +61,20 @@ input-kanban --open
 - port：`8787`
 - runs 目录：`~/.input-kanban/runs`
 - Codex 命令：`codex`
+- runner：`headless`
+
+`--runner` 当前支持 `headless` 和 `tmux`。默认行为保持 `headless`；`tmux` 会为每个 run 创建一个 `input-kanban-<runId>` session，并为 planner、每个 batch、final judge 创建独立 window。batch window 内包含 overview pane 和对应 worker panes。
+
+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 文件驱动。tmux 角色命令完成后会先写入 `exit_code`，再保留 window，方便查看现场；需要关闭时由用户在 tmux 里手动退出。
+
+tmux 模式是可选能力，主要用于在终端里实时查看每个 Codex 角色的执行过程。`codex exec` 当前属于非交互模式，默认不会弹出人工 approval；如果创建任务时选择 `danger-full-access`，表示显式放开 worker sandbox 限制，应只在受控测试仓库中使用。
+
+看板会在 run 生成 tmux 元数据后显示 `复制tmux attach指令`。文件查看区域不再重复展示 tmux 终端信息；如需查看现场，请从批次详情顶部复制 attach 指令进入 tmux session。
 
 ## 在看板里如何使用
 
 1. 点击 `新建任务批次`。
-2. 输入批次名称、目标仓库和任务说明。
+2. 输入批次名称、目标仓库、Worker 沙箱和任务说明。
 3. 点击 `创建批次`。
 4. 点击 `拆分任务`，让 Codex planner 生成 batches 和 workers。
 5. 点击 `派发执行`，按 batch barrier 和并发限制运行 workers。
@@ -77,6 +87,7 @@ input-kanban --open
 - 把一个较大的 Codex 编程任务拆成多个 worker。
 - 按批次阻塞关系控制执行顺序。
 - 在本地观察每个 worker 的状态、日志和最终回复。
+- 使用 tmux runner 时，在每个 batch window 中查看 overview pane 和 worker panes。
 - 在所有 worker 完成后，让 final judge 汇总验收。
 - 保留本地运行记录，便于排查和恢复。
 
@@ -108,6 +119,7 @@ runs/<runId>/
 
 - 已安装 Node.js 20 或更高版本。
 - 已安装并配置可用的 Codex CLI。
+- 如需使用 `--runner tmux`，本机需要安装可用的 `tmux`。
 - `codex` 命令能在终端中正常运行，或通过 `--codex-bin` 指定 Codex 可执行文件路径。
 
 ## 维护者开发

package/bin/input-kanban-format-events.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import readline from 'node:readline';
+import { formatCodexEventLine } from '../src/eventFormatter.js';
+
+const rl = readline.createInterface({ input: process.stdin, crlfDelay: Infinity });
+let index = 0;
+
+rl.on('line', line => {
+  if (!line.trim()) return;
+  console.log(formatCodexEventLine(line, index++));
+  console.log('');
+});

package/bin/input-kanban-tmux-overview.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+
+const statePath = process.argv[2];
+
+function readState() {
+  if (!statePath) return null;
+  try { return JSON.parse(fs.readFileSync(statePath, 'utf8')); }
+  catch { return null; }
+}
+
+function countTasks(tasks = []) {
+  return {
+    total: tasks.length,
+    pending: tasks.filter(task => task.status === 'pending').length,
+    running: tasks.filter(task => task.status === 'running').length,
+    completed: tasks.filter(task => task.status === 'completed').length,
+    failed: tasks.filter(task => ['failed', 'unknown'].includes(task.status)).length,
+    stopped: tasks.filter(task => task.status === 'stopped').length
+  };
+}
+
+function line(label, value) {
+  console.log(`${label.padEnd(12)} ${value}`);
+}
+
+const state = readState();
+const now = new Date().toLocaleString();
+console.log('Input Kanban tmux Overview');
+console.log('='.repeat(32));
+console.log(`Updated     ${now}`);
+
+if (!state) {
+  console.log('Waiting for run_state.json...');
+  process.exit(0);
+}
+
+line('Run', state.runId || '-');
+line('Label', state.label || '-');
+line('Status', state.status || '-');
+line('Repo', state.repo || '-');
+console.log('');
+
+const batches = Array.isArray(state.batches) ? state.batches : [];
+const plannerStatus = state.planner?.status || 'pending';
+const judgeStatus = state.judge?.status || 'pending';
+console.log(`Special    planner=${plannerStatus} judge=${judgeStatus}`);
+console.log(`Batches    ${batches.length}`);
+console.log('');
+
+if (!batches.length) {
+  console.log('No worker batches materialized yet.');
+  process.exit(0);
+}
+
+for (const [index, batch] of batches.entries()) {
+  const tasks = Array.isArray(batch.tasks) ? batch.tasks : [];
+  const counts = countTasks(tasks);
+  console.log(`${index + 1}. ${batch.id || `batch-${index + 1}`}  ${batch.status || 'pending'}  maxParallel=${batch.maxParallel || '-'}  workers=${counts.total}`);
+  console.log(`   completed=${counts.completed} running=${counts.running} pending=${counts.pending} failed=${counts.failed} stopped=${counts.stopped}`);
+  for (const task of tasks) {
+    const tmux = task.tmux?.ready ? ` window=${task.tmux.windowName || '-'} pane=${task.tmux.paneId || '-'}` : '';
+    console.log(`   - ${task.id || '-'}  ${task.status || 'pending'}${tmux}`);
+  }
+  console.log('');
+}

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.2",
+  "version": "0.0.4",
   "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 bin/input-kanban-format-events.js && node --check bin/input-kanban-tmux-overview.js && node --check src/server.js && node --check src/orchestrator.js && node --check src/appServerClient.js && node --check src/utils.js && node --check src/eventFormatter.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",