input-kanban 0.0.2 → 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

@@ -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,6 +61,13 @@ 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 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
 

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,6 +61,13 @@ input-kanban --open
 - port：`8787`
 - runs 目录：`~/.input-kanban/runs`
 - Codex 命令：`codex`
+- runner：`headless`
+
+`--runner` 当前支持 `headless` 和 `tmux`。默认行为保持 `headless`；`tmux` 会为每个 run 创建一个 `input-kanban-<runId>` session，并为 planner、每个 worker、final judge 创建独立 window。
+
+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 模式是可选能力，主要用于在终端里实时查看每个 Codex 角色的执行过程，并在 Codex CLI 需要人工确认时让用户手动处理。它不会实现自动审批，也不会绕过 Codex CLI、仓库权限或系统权限的安全边界；所有需要确认的操作仍必须由用户在对应 tmux window 中明确批准。
 
 ## 在看板里如何使用
 

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.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",

package/public/index.html

@@ -32,11 +32,14 @@
     th:nth-child(4), td:nth-child(4) { width: 64px; white-space: nowrap; }
     th:nth-child(5), td:nth-child(5) { width: 70px; }
     th:nth-child(6), td:nth-child(6) { width: 58px; }
-    th:nth-child(8), td:nth-child(8) { width: 66px; }
-    th:nth-child(9), td:nth-child(9) { width: 94px; }
+    th:nth-child(8), td:nth-child(8) { width: 118px; }
+    th:nth-child(9), td:nth-child(9) { width: 66px; }
+    th:nth-child(10), td:nth-child(10) { width: 94px; }
     th { color: #cbd5e1; font-size: 12px; text-transform: uppercase; letter-spacing: .06em; }
     tr:hover { background: #162033; cursor: pointer; }
     .pill { display: inline-block; padding: 3px 8px; border-radius: 999px; font-size: 12px; font-weight: 800; background: var(--gray); line-height: 1.3; }
+    .attention-hint { display: block; margin-top: 6px; color: #fbbf24; font-size: 12px; font-weight: 700; white-space: normal; line-height: 1.35; }
+    .attention-hint code { color: #fde68a; font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 11px; word-break: break-all; }
     .completed, .judged, .workers_completed, .planned, .batches_completed { background: var(--green); }
     .running, .planning, .judging { background: var(--blue); }
     .failed, .workers_failed, .plan_failed, .judge_failed, .unknown, .batch_blocked { background: var(--red); }
@@ -75,6 +78,12 @@
     .execution-summary + pre { border-top-left-radius: 0; border-top-right-radius: 0; }
     .notice { margin-top: 10px; padding: 10px 12px; border: 1px solid var(--line); border-radius: 10px; background: #1f2937; color: #cbd5e1; }
     .notice.warning { border-color: #92400e; background: rgba(180,83,9,.18); }
+    .tmux-box { margin: 8px 0 10px; padding: 10px 12px; border: 1px solid var(--line); border-radius: 10px; background: #020617; color: #cbd5e1; font-size: 12px; }
+    .tmux-box.hidden { display: none; }
+    .tmux-box-title { font-weight: 800; color: var(--text); margin-bottom: 5px; }
+    .tmux-actions { margin-top: 7px; display: flex; flex-wrap: wrap; gap: 4px; }
+    .tmux-actions button { margin: 0; }
+    .tmux-inline { display: block; margin-top: 3px; word-break: break-all; }
     .file-content-wrap { position: relative; }
     .floating-copy-btn { position: absolute; top: 8px; left: 8px; z-index: 2; opacity: 0; pointer-events: none; transition: opacity .15s; padding: 5px 8px; background: rgba(71,85,105,.92); }
     .file-content-wrap:hover .floating-copy-btn:not(.hidden), .floating-copy-btn:focus { opacity: 1; pointer-events: auto; }
@@ -144,6 +153,7 @@
         <button class="secondary" onclick="loadFile('verdict.json')">验收结论</button>
       </div>
       <div id="executionSummary" class="execution-summary hidden"></div>
+      <div id="tmuxPanel" class="tmux-box hidden"></div>
       <div class="file-content-wrap">
         <button id="copyLastMessageBtn" class="secondary copy-btn floating-copy-btn hidden" title="复制最终回复内容" onclick="copyFileContent(event)">⧉</button>
         <pre id="fileContent"></pre>
@@ -192,6 +202,13 @@ function durationSeconds(start, end) {
   return Math.max(0, Math.round((endMs - new Date(start).getTime()) / 1000));
 }
 function runTimingText(s) { return `开始时刻 ${formatDateTime(s.createdAt)}｜用时 ${durationSeconds(s.createdAt, s.updatedAt)} 秒`; }
+function isTmuxMode() { return currentState?.runner === 'tmux'; }
+function taskById(id) {
+  if (!currentState) return null;
+  if (id === 'planner') return currentState.planner;
+  if (id === 'judge') return currentState.judge;
+  return (currentState.tasks || []).find(t => t.id === id) || null;
+}
 
 async function loadHealth() {
   const h = await api('/api/health');
@@ -292,7 +309,14 @@ function taskStatusCell(t) {
     const original = t.originalStatus || t.manualCompletion.originalStatus || t.manualCompletion.previousStatus || 'unknown';
     return `${pill(original)} <span class="pill completed">手动标记成功已完成</span>`;
   }
-  return pill(t?.status);
+  const hint = attentionHintCell(t);
+  return `${pill(t?.status)}${hint}`;
+}
+function attentionHintCell(t) {
+  if (!t?.attentionHint) return '';
+  const command = t.attentionHint.attachCommand ? ` <code>${esc(t.attentionHint.attachCommand)}</code>` : '';
+  const reasons = Array.isArray(t.attentionHint.reasons) && t.attentionHint.reasons.length ? `｜${esc(t.attentionHint.reasons.join(' / '))}` : '';
+  return `<span class="attention-hint" title="${esc(t.attentionHint.message || '')}">可能需要人工介入；请 attach tmux 检查。${command}${reasons}</span>`;
 }
 function taskActionCell(id, t) {
   if (!t || id === 'planner' || id === 'judge') return '-';
@@ -304,6 +328,13 @@ function sessionCell(thread) {
   if (!thread) return '-';
   return `<span class="session-cell">${esc(thread)}</span><button class="copy-btn" title="复制 Codex 会话ID" onclick="copySessionId(event, '${esc(thread)}')">⧉</button>`;
 }
+function tmuxCell(t) {
+  if (!isTmuxMode()) return '-';
+  const tmux = t?.tmux;
+  if (!tmux) return '<span class="muted">未启动终端</span>';
+  const label = tmux.windowName || tmux.target || 'tmux';
+  return `<span class="session-cell" title="${esc(tmux.target || '')}">${esc(label)}</span>`;
+}
 function taskStartedCell(t) {
   return t?.startedAt ? formatDateTime(t.startedAt) : '-';
 }
@@ -314,7 +345,7 @@ function taskDurationCell(t) {
 }
 function taskRow(id, role, t) {
   const thread = t?.codexThread?.id || '';
-  return `<tr class="job-row ${selectedTask === id ? 'selected' : ''}" onclick="selectTask('${id}')"><td><b class="task-name" title="${esc(id)}">${esc(id)}</b><span class="muted task-role">${esc(displayRole(role))}</span></td><td>${taskStatusCell(t)}</td><td>${esc(taskStartedCell(t))}</td><td>${esc(taskDurationCell(t))}</td><td>${esc(t?.pid || '-')}</td><td>${esc(t?.exitCode ?? '-')}</td><td>${sessionCell(thread)}</td><td>${esc(t?.files?.lastMessage?.exists ? '有' : '-')}</td><td>${taskActionCell(id, t)}</td></tr>`;
+  return `<tr class="job-row ${selectedTask === id ? 'selected' : ''}" onclick="selectTask('${id}')"><td><b class="task-name" title="${esc(id)}">${esc(id)}</b><span class="muted task-role">${esc(displayRole(role))}</span></td><td>${taskStatusCell(t)}</td><td>${esc(taskStartedCell(t))}</td><td>${esc(taskDurationCell(t))}</td><td>${esc(t?.pid || '-')}</td><td>${esc(t?.exitCode ?? '-')}</td><td>${sessionCell(thread)}</td><td>${tmuxCell(t)}</td><td>${esc(t?.files?.lastMessage?.exists ? '有' : '-')}</td><td>${taskActionCell(id, t)}</td></tr>`;
 }
 function renderTasks() {
   const s = currentState;
@@ -322,12 +353,12 @@ function renderTasks() {
   if (Array.isArray(s.batches) && s.batches.length) {
     for (const b of s.batches) {
       const done = (b.tasks || []).filter(t => t.status === 'completed').length;
-      rows.push(`<tr class="batch-row"><td colspan="9">${esc(b.name || b.id)} ${pill(b.status)} <span class="muted">${esc(b.id)}｜最大并发 ${esc(b.maxParallel || '-')}｜${done}/${(b.tasks || []).length}</span></td></tr>`);
+      rows.push(`<tr class="batch-row"><td colspan="10">${esc(b.name || b.id)} ${pill(b.status)} <span class="muted">${esc(b.id)}｜最大并发 ${esc(b.maxParallel || '-')}｜${done}/${(b.tasks || []).length}</span></td></tr>`);
       for (const t of b.tasks || []) rows.push(taskRow(t.id, t.name, t));
     }
   } else rows.push(...(s.tasks||[]).map(t => taskRow(t.id, t.name, t)));
   rows.push(taskRow('judge','最终验收',s.judge));
-  document.getElementById('tasks').innerHTML = `<table><tr><th>任务</th><th>状态</th><th>发起时间</th><th>用时</th><th>进程号</th><th>退出码</th><th>Codex 会话ID</th><th>最终回复</th><th>操作</th></tr>${rows.join('')}</table>`;
+  document.getElementById('tasks').innerHTML = `<table><tr><th>任务</th><th>状态</th><th>发起时间</th><th>用时</th><th>进程号</th><th>退出码</th><th>Codex 会话ID</th><th>终端</th><th>最终回复</th><th>操作</th></tr>${rows.join('')}</table>`;
 }
 async function selectTask(id) {
   selectedTask = id;
@@ -347,12 +378,14 @@ async function loadFile(name, { preserveScroll = false } = {}) {
   else pre.scrollTop = 0;
   if (name === 'events.pretty') await renderExecutionSummary();
   else hideExecutionSummary();
+  renderTmuxPanel();
   updateCopyLastMessageButton();
 }
 function clearFileView() {
   document.getElementById('fileTitle').textContent = '点击任务后选择文件';
   document.getElementById('fileContent').textContent = '';
   hideExecutionSummary();
+  hideTmuxPanel();
   updateCopyLastMessageButton();
 }
 function updateCopyLastMessageButton() {
@@ -378,6 +411,50 @@ function hideExecutionSummary() {
   el.classList.add('hidden');
   el.innerHTML = '';
 }
+function hideTmuxPanel() {
+  const el = document.getElementById('tmuxPanel');
+  el.classList.add('hidden');
+  el.innerHTML = '';
+}
+function renderTmuxPanel() {
+  const el = document.getElementById('tmuxPanel');
+  if (!el) return;
+  if (!selectedTask || !currentState) { hideTmuxPanel(); return; }
+  if (!isTmuxMode()) {
+    el.classList.remove('hidden');
+    el.innerHTML = '<div class="tmux-box-title">终端模式</div><span class="muted">当前 runner 为 headless，无需终端附加操作。</span>';
+    return;
+  }
+  const tmux = taskById(selectedTask)?.tmux;
+  if (!tmux) {
+    el.classList.remove('hidden');
+    el.innerHTML = '<div class="tmux-box-title">tmux 终端</div><span class="muted">该任务尚未生成 tmux window。</span>';
+    return;
+  }
+  el.classList.remove('hidden');
+  el.innerHTML = `
+    <div class="tmux-box-title">tmux 终端</div>
+    <span class="tmux-inline">session：${esc(tmux.sessionName || '-')}</span>
+    <span class="tmux-inline">window：${esc(tmux.windowName || '-')}</span>
+    <span class="tmux-inline">target：${esc(tmux.target || '-')}</span>
+    <div class="tmux-actions">
+      ${tmux.attachCommand ? `<button class="secondary" onclick="copyTmuxCommand(event, 'attach')">复制 attach</button>` : ''}
+      ${tmux.selectWindowCommand ? `<button class="secondary" onclick="copyTmuxCommand(event, 'select')">复制 select-window</button>` : ''}
+    </div>`;
+}
+async function copyTmuxCommand(event, kind) {
+  event.stopPropagation();
+  const tmux = taskById(selectedTask)?.tmux;
+  const command = kind === 'attach' ? tmux?.attachCommand : tmux?.selectWindowCommand;
+  if (!command) return;
+  try {
+    await navigator.clipboard.writeText(command);
+    event.currentTarget.textContent = '已复制';
+    setTimeout(() => { event.currentTarget.textContent = kind === 'attach' ? '复制 attach' : '复制 select-window'; }, 900);
+  } catch {
+    prompt(kind === 'attach' ? '复制 attachCommand' : '复制 selectWindowCommand', command);
+  }
+}
 async function renderExecutionSummary() {
   const el = document.getElementById('executionSummary');
   let raw = '';

package/src/orchestrator.js

@@ -1,15 +1,27 @@
-import { spawn } from 'node:child_process';
 import fs from 'node:fs';
 import fsp from 'node:fs/promises';
 import path from 'node:path';
 import {
-  CODEX_BIN, DEFAULT_REPO, RUNS_DIR, ensureDir, nowIso, makeRunId, readJson,
+  DEFAULT_REPO, RUNS_DIR, ensureDir, nowIso, makeRunId, readJson,
   writeJsonAtomic, fileInfo, readTextMaybe, extractFirstJsonObject, listRunDirs,
-  pathForRun, roleDir, safeIdPart
+  pathForRun, roleDir, safeIdPart, RUNNER
 } from './utils.js';
 import { matchThreadToMarkers } from './appServerClient.js';
-
-const runningChildren = new Map(); // key: `${runId}:${taskId}` -> child
+import { defaultRunner } from './runners/index.js';
+
+const runner = defaultRunner;
+const ATTENTION_IDLE_MS = 5 * 60 * 1000;
+const ATTENTION_MIN_RUNTIME_MS = 10 * 60 * 1000;
+const ATTENTION_KEYWORDS = [
+  'permission',
+  'approval',
+  'approve',
+  'confirm',
+  'continue',
+  'password',
+  'authentication',
+  'authenticate'
+];
 
 function statePath(runDir) { return path.join(runDir, 'run_state.json'); }
 function planPath(runDir) { return path.join(runDir, 'plan.json'); }
@@ -21,6 +33,7 @@ export async function createRun({ label = 'task', taskText = '', repo = DEFAULT_
   await fsp.writeFile(path.join(runDir, 'task.md'), taskText || '');
   const state = {
     runId, label, repo: path.resolve(repo), maxParallel: Number(maxParallel) || 3,
+    runner: RUNNER,
     status: 'created', createdAt: nowIso(), updatedAt: nowIso(),
     planner: { status: 'pending' }, batches: [], tasks: [], judge: { status: 'pending' }
   };
@@ -132,24 +145,6 @@ Plan: ${path.join(pathForRun(state.runId), 'plan.json')}
 `;
 }
 
-function spawnCodex({ state, taskId, prompt, sandbox, cwd, outDir }) {
-  const events = path.join(outDir, 'events.jsonl');
-  const stderr = path.join(outDir, 'stderr.log');
-  const last = path.join(outDir, 'last_message.md');
-  fs.writeFileSync(path.join(outDir, 'prompt.md'), prompt);
-  const args = ['exec', '--json', '--sandbox', sandbox, '-C', cwd, '-o', last, prompt];
-  const child = spawn(CODEX_BIN, args, { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
-  child.stdout.pipe(fs.createWriteStream(events, { flags: 'a' }));
-  child.stderr.pipe(fs.createWriteStream(stderr, { flags: 'a' }));
-  const key = `${state.runId}:${taskId}`;
-  runningChildren.set(key, child);
-  child.on('exit', code => {
-    try { fs.writeFileSync(path.join(outDir, 'exit_code'), String(code)); } catch {}
-    runningChildren.delete(key);
-  });
-  return child;
-}
-
 export async function startPlanner(runId) {
   const state = await loadRun(runId);
   if (!state) throw new Error(`run not found: ${runId}`);
@@ -168,11 +163,11 @@ export async function startPlanner(runId) {
   await fsp.rm(planPath(runDir), { force: true });
   const taskText = await fsp.readFile(path.join(runDir, 'task.md'), 'utf8');
   const prompt = defaultPlannerPrompt(state, taskText);
-  const child = spawnCodex({ state, taskId: 'planner', prompt, sandbox: 'read-only', cwd: state.repo, outDir });
+  const child = await runner.startCodexTask({ runId: state.runId, taskId: 'planner', prompt, sandbox: 'read-only', cwd: state.repo, outDir });
   state.status = 'planning';
   state.planner = { status: 'running', pid: child.pid, startedAt: nowIso(), dir: outDir, attempt: (state.plannerAttempts?.length || 0) + 1 };
   await saveRun(state);
-  child.on('exit', async code => {
+  child.onExit(async code => {
     const s = await loadRun(runId); if (!s || s.status === 'stopped') return;
     s.planner.exitCode = code; s.planner.endedAt = nowIso(); s.planner.status = code === 0 ? 'completed' : 'failed';
     const planResult = await materializePlan(s);
@@ -304,7 +299,7 @@ ORCHESTRATOR_BATCH_ID: ${task.batchId || 'batch-1'}
 
 ${task.prompt}
 `;
-  const child = spawnCodex({ state, taskId: task.id, prompt: fullPrompt, sandbox: task.sandbox || 'workspace-write', cwd: state.repo, outDir });
+  const child = await runner.startCodexTask({ runId: state.runId, taskId: task.id, prompt: fullPrompt, sandbox: task.sandbox || 'workspace-write', cwd: state.repo, outDir });
   Object.assign(task, { status: 'running', pid: child.pid, startedAt: nowIso(), dir: outDir });
 }
 
@@ -312,12 +307,7 @@ export async function stopRun(runId, { reason = 'stopped by user' } = {}) {
   const state = await loadRun(runId);
   if (!state) throw new Error(`run not found: ${runId}`);
   const stoppedAt = nowIso();
-  for (const [key, child] of runningChildren.entries()) {
-    if (key.startsWith(`${runId}:`)) {
-      try { child.kill('TERM'); } catch {}
-      runningChildren.delete(key);
-    }
-  }
+  await runner.stopRun(runId);
   for (const roleState of [state.planner, state.judge]) {
     if (roleState?.status === 'running') Object.assign(roleState, { status: 'stopped', stoppedAt, endedAt: stoppedAt });
   }
@@ -400,11 +390,11 @@ export async function startJudge(runId) {
   const judgeInput = await buildJudgeInput(state);
   await writeJsonAtomic(judgeInputPath, judgeInput);
   const prompt = defaultJudgePrompt(state, judgeInputPath);
-  const child = spawnCodex({ state, taskId: 'judge', prompt, sandbox: 'read-only', cwd: state.repo, outDir });
+  const child = await runner.startCodexTask({ runId: state.runId, taskId: 'judge', prompt, sandbox: 'read-only', cwd: state.repo, outDir });
   state.judge = { status: 'running', pid: child.pid, startedAt: nowIso(), dir: outDir };
   state.status = 'judging';
   await saveRun(state);
-  child.on('exit', async code => {
+  child.onExit(async code => {
     const s = await loadRun(runId); if (!s || s.status === 'stopped') return;
     s.judge.exitCode = code; s.judge.endedAt = nowIso(); s.judge.status = code === 0 ? 'completed' : 'failed';
     const text = await readTextMaybe(path.join(outDir, 'last_message.md'), 1000000);
@@ -423,9 +413,12 @@ export async function refreshRun(runId, appClient = null) {
 async function loadAndRefreshRun(runId, appClient = null, { light = false } = {}) {
   const state = await loadRun(runId);
   if (!state) return null;
+  state.runner = state.runner || RUNNER;
   await refreshRole(state, state.planner, roleDir(pathForRun(runId), 'planner'));
+  await recoverCompletedPlanner(state);
   for (const task of state.tasks || []) await refreshTask(state, task);
   await refreshRole(state, state.judge, roleDir(pathForRun(runId), 'judge'));
+  await recoverCompletedJudge(state);
   recomputeRunStatus(state);
   await scheduleMoreWorkers(state);
   recomputeRunStatus(state);
@@ -434,19 +427,43 @@ async function loadAndRefreshRun(runId, appClient = null, { light = false } = {}
   return state;
 }
 
+async function recoverCompletedPlanner(state) {
+  if (state.planner?.status !== 'completed' || state.tasks?.length || state.batches?.length) return;
+  const planResult = await materializePlan(state);
+  if (planResult.ok) state.status = 'planned';
+  else if (planResult.empty) state.status = 'plan_empty';
+  else state.status = 'plan_failed';
+}
+
+async function recoverCompletedJudge(state) {
+  if (!['completed', 'failed'].includes(state.judge?.status)) return;
+  if (state.judge.status === 'completed' && !state.judge.verdict) {
+    const outDir = roleDir(pathForRun(state.runId), 'judge');
+    const text = await readTextMaybe(path.join(outDir, 'last_message.md'), 1000000);
+    const verdict = extractFirstJsonObject(text);
+    if (verdict) {
+      state.judge.verdict = verdict;
+      await writeJsonAtomic(path.join(outDir, 'verdict.json'), verdict);
+    }
+  }
+  state.status = state.judge.status === 'completed' ? 'judged' : 'judge_failed';
+}
+
 async function refreshRole(state, roleState, dir) {
   if (!roleState) return;
   const exitPath = path.join(dir, 'exit_code');
   const exit = await readTextMaybe(exitPath, 1000);
   const exitInfo = await fileInfo(exitPath);
-  const key = `${state.runId}:${roleState === state.judge ? 'judge' : 'planner'}`;
+  const key = roleState === state.judge ? 'judge' : 'planner';
   if (exit !== '') {
     roleState.exitCode = Number(exit.trim());
     if (!roleState.endedAt && exitInfo.exists) roleState.endedAt = exitInfo.mtime;
     if (roleState.status === 'running') roleState.status = roleState.exitCode === 0 ? 'completed' : 'failed';
   }
-  else if (roleState.status === 'running' && !runningChildren.has(key)) roleState.status = 'unknown';
+  else if (roleState.status === 'running' && !runner.hasRunning(state.runId, key)) roleState.status = 'unknown';
   roleState.files = await standardFiles(dir);
+  await attachTmuxMetadata(roleState, dir);
+  roleState.attentionHint = await buildAttentionHint({ state, target: roleState, dir });
 }
 
 async function refreshTask(state, task) {
@@ -454,13 +471,14 @@ async function refreshTask(state, task) {
   const exitPath = path.join(dir, 'exit_code');
   const exit = await readTextMaybe(exitPath, 1000);
   const exitInfo = await fileInfo(exitPath);
-  const key = `${state.runId}:${task.id}`;
   if (exit !== '') {
     task.exitCode = Number(exit.trim());
     if (!task.endedAt && exitInfo.exists) task.endedAt = exitInfo.mtime;
     if (task.status === 'running') task.status = task.exitCode === 0 ? 'completed' : 'failed';
-  } else if (task.status === 'running' && !runningChildren.has(key)) task.status = 'unknown';
+  } else if (task.status === 'running' && !runner.hasRunning(state.runId, task.id)) task.status = 'unknown';
   task.files = await standardFiles(dir);
+  await attachTmuxMetadata(task, dir);
+  task.attentionHint = await buildAttentionHint({ state, target: task, dir });
   task.artifacts = [];
   for (const rel of task.expectedArtifacts || []) task.artifacts.push({ path: rel, ...(await fileInfo(path.isAbsolute(rel) ? rel : path.join(state.repo, rel))) });
   const batch = (state.batches || []).find(b => b.id === task.batchId);
@@ -470,13 +488,77 @@ async function refreshTask(state, task) {
   }
 }
 
+async function attachTmuxMetadata(target, dir) {
+  const raw = await readJson(path.join(dir, 'tmux.json'), null);
+  if (!raw || raw.runner !== 'tmux') {
+    delete target.tmux;
+    return;
+  }
+  const selectWindowCommand = raw.selectWindowCommand || raw.selectCommand || '';
+  target.tmux = {
+    runner: 'tmux',
+    sessionName: raw.sessionName || '',
+    windowName: raw.windowName || '',
+    target: raw.target || '',
+    attachCommand: raw.attachCommand || '',
+    selectWindowCommand,
+    runScript: raw.runScript || '',
+    startedAt: raw.startedAt || ''
+  };
+}
+
+async function buildAttentionHint({ state, target, dir }) {
+  if (!['running', 'unknown'].includes(target?.status) || state?.status === 'stopped') return null;
+  if ((state?.runner || RUNNER) !== 'tmux' && !target.tmux) return null;
+  const reasons = [];
+  const textTail = [
+    await readTextMaybe(path.join(dir, 'stderr.log'), 20000),
+    await readTextMaybe(path.join(dir, 'events.jsonl'), 20000)
+  ].join('\n');
+  const keyword = findAttentionKeyword(textTail);
+  if (keyword) reasons.push(`log tail contains "${keyword}"`);
+  const idle = taskIdleSnapshot(target);
+  if (idle.isLongIdle || (target.status === 'unknown' && idle.isIdle)) reasons.push(`no recent log updates for ${Math.round(idle.idleMs / 1000)}s`);
+  if (!reasons.length) return null;
+  return {
+    message: 'This task may need manual intervention; attach to tmux to inspect.',
+    reasons,
+    attachCommand: target.tmux?.attachCommand || '',
+    detectedAt: nowIso()
+  };
+}
+
+function findAttentionKeyword(text) {
+  const lower = String(text || '').toLowerCase();
+  return ATTENTION_KEYWORDS.find(keyword => lower.includes(keyword)) || null;
+}
+
+function taskIdleSnapshot(target) {
+  const now = Date.now();
+  const startedMs = Date.parse(target?.startedAt || '');
+  const runtimeMs = Number.isFinite(startedMs) ? now - startedMs : 0;
+  const recentMs = [target?.files?.events, target?.files?.stderr, target?.files?.lastMessage]
+    .filter(info => info?.exists && Number.isFinite(info.mtimeMs))
+    .map(info => info.mtimeMs)
+    .sort((a, b) => b - a)[0];
+  const idleMs = Number.isFinite(recentMs) ? now - recentMs : runtimeMs;
+  return {
+    idleMs,
+    runtimeMs,
+    isIdle: idleMs >= ATTENTION_IDLE_MS,
+    isLongIdle: runtimeMs >= ATTENTION_MIN_RUNTIME_MS && idleMs >= ATTENTION_IDLE_MS
+  };
+}
+
 async function standardFiles(dir) {
   return {
     prompt: await fileInfo(path.join(dir, 'prompt.md')),
     events: await fileInfo(path.join(dir, 'events.jsonl')),
     stderr: await fileInfo(path.join(dir, 'stderr.log')),
     lastMessage: await fileInfo(path.join(dir, 'last_message.md')),
-    exitCode: await fileInfo(path.join(dir, 'exit_code'))
+    exitCode: await fileInfo(path.join(dir, 'exit_code')),
+    runScript: await fileInfo(path.join(dir, 'run.sh')),
+    tmux: await fileInfo(path.join(dir, 'tmux.json'))
   };
 }
 
@@ -567,6 +649,7 @@ async function buildJudgeInput(state) {
       resultJson: await readJson(path.join(dir, 'result.json'), null),
       evidenceJson: await readJson(path.join(dir, 'evidence.json'), null),
       manualCompletion: task.manualCompletion || await readJson(path.join(dir, 'manual_completion.json'), null),
+      tmux: task.tmux || null,
       stderrTail: await readTextMaybe(path.join(dir, 'stderr.log'), 20000)
     });
   }
@@ -579,6 +662,7 @@ async function buildJudgeInput(state) {
       label: state.label,
       repo: state.repo,
       status: state.status,
+      runner: state.runner || RUNNER,
       createdAt: state.createdAt,
       updatedAt: state.updatedAt,
       maxParallel: state.maxParallel
@@ -597,6 +681,7 @@ async function buildJudgeInput(state) {
       exitCode: state.planner?.exitCode ?? null,
       planParseError: state.planner?.planParseError,
       planEmpty: !!state.planner?.planEmpty,
+      tmux: state.planner?.tmux || null,
       lastMessage: await readTextMaybe(path.join(roleDir(runDir, 'planner'), 'last_message.md'), 200000)
     },
     tasks
@@ -629,7 +714,7 @@ async function enrichFromAppServer(state, appClient) {
 
 function summaryOfRun(s) {
   const tasks = s.tasks || [];
-  return { runId: s.runId, label: s.label, repo: s.repo, status: s.status, archived: !!s.archived, createdAt: s.createdAt, updatedAt: s.updatedAt, total: tasks.length, completed: tasks.filter(t => t.status === 'completed').length, failed: tasks.filter(t => ['failed','unknown'].includes(t.status)).length, running: tasks.filter(t => t.status === 'running').length, batches: (s.batches || []).map(b => ({ id: b.id, name: b.name, status: b.status, total: b.tasks?.length || 0, completed: (b.tasks || []).filter(t => t.status === 'completed').length })) };
+  return { runId: s.runId, label: s.label, repo: s.repo, status: s.status, runner: s.runner || RUNNER, archived: !!s.archived, createdAt: s.createdAt, updatedAt: s.updatedAt, total: tasks.length, completed: tasks.filter(t => t.status === 'completed').length, failed: tasks.filter(t => ['failed','unknown'].includes(t.status)).length, running: tasks.filter(t => t.status === 'running').length, batches: (s.batches || []).map(b => ({ id: b.id, name: b.name, status: b.status, total: b.tasks?.length || 0, completed: (b.tasks || []).filter(t => t.status === 'completed').length })) };
 }
 
 function formatCodexEventsJsonl(text) {
@@ -718,7 +803,7 @@ export async function readRunTaskText(runId) {
 
 export async function readRunFile(runId, taskId, name) {
   const runDir = pathForRun(runId);
-  const allowed = new Set(['prompt.md','events.jsonl','events.pretty','stderr.log','last_message.md','exit_code','result.json','evidence.json','verdict.json','judge_input.json','manual_completion.json']);
+  const allowed = new Set(['prompt.md','events.jsonl','events.pretty','stderr.log','last_message.md','exit_code','result.json','evidence.json','verdict.json','judge_input.json','manual_completion.json','run.sh','tmux.json']);
   if (!allowed.has(name)) throw new Error('file not allowed');
   let dir;
   if (taskId === 'planner') dir = roleDir(runDir, 'planner');

package/src/runners/headlessRunner.js

@@ -0,0 +1,51 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { CODEX_BIN } from '../utils.js';
+
+function processKey(runId, taskId) {
+  return `${runId}:${taskId}`;
+}
+
+export function createHeadlessRunner({ codexBin = CODEX_BIN } = {}) {
+  const runningProcesses = new Map();
+
+  function startCodexTask({ runId, taskId, prompt, sandbox, cwd, outDir }) {
+    const events = path.join(outDir, 'events.jsonl');
+    const stderr = path.join(outDir, 'stderr.log');
+    const last = path.join(outDir, 'last_message.md');
+    fs.writeFileSync(path.join(outDir, 'prompt.md'), prompt);
+    const args = ['exec', '--json', '--sandbox', sandbox, '-C', cwd, '-o', last, prompt];
+    const child = spawn(codexBin, args, { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+    child.stdout.pipe(fs.createWriteStream(events, { flags: 'a' }));
+    child.stderr.pipe(fs.createWriteStream(stderr, { flags: 'a' }));
+    const key = processKey(runId, taskId);
+    runningProcesses.set(key, child);
+    child.on('exit', code => {
+      try { fs.writeFileSync(path.join(outDir, 'exit_code'), String(code)); } catch {}
+      runningProcesses.delete(key);
+    });
+    return {
+      pid: child.pid,
+      onExit(listener) { child.on('exit', listener); },
+      stop(signal = 'TERM') { child.kill(signal); }
+    };
+  }
+
+  function stopRun(runId, signal = 'TERM') {
+    for (const [key, child] of runningProcesses.entries()) {
+      if (key.startsWith(`${runId}:`)) {
+        try { child.kill(signal); } catch {}
+        runningProcesses.delete(key);
+      }
+    }
+  }
+
+  function hasRunning(runId, taskId) {
+    return runningProcesses.has(processKey(runId, taskId));
+  }
+
+  return { kind: 'headless', startCodexTask, stopRun, hasRunning };
+}
+
+export const headlessRunner = createHeadlessRunner();

package/src/runners/index.js

@@ -0,0 +1,13 @@
+import { headlessRunner } from './headlessRunner.js';
+import { createTmuxRunner } from './tmuxRunner.js';
+import { RUNNER } from '../utils.js';
+
+export { createHeadlessRunner, headlessRunner } from './headlessRunner.js';
+export { createTmuxRunner } from './tmuxRunner.js';
+
+export function createDefaultRunner(runnerMode = RUNNER) {
+  if (runnerMode === 'tmux') return createTmuxRunner();
+  return headlessRunner;
+}
+
+export const defaultRunner = createDefaultRunner();

package/src/runners/tmuxRunner.js

@@ -0,0 +1,170 @@
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import {
+  CODEX_BIN,
+  ensureDir,
+  nowIso,
+  readTextMaybe,
+  writeJsonAtomic
+} from '../utils.js';
+import {
+  DEFAULT_TMUX_BIN,
+  sanitizeTmuxSessionName,
+  sanitizeTmuxWindowName,
+  tmuxHasSession,
+  tmuxKillSession,
+  tmuxNewSession,
+  tmuxNewWindow
+} from '../tmux.js';
+
+function processKey(runId, taskId) {
+  return `${runId}:${taskId}`;
+}
+
+function roleForTask(taskId) {
+  if (taskId === 'planner') return 'planner';
+  if (taskId === 'judge') return 'judge';
+  return 'worker';
+}
+
+function windowNameForTask(taskId) {
+  const role = roleForTask(taskId);
+  return sanitizeTmuxWindowName(role === 'worker' ? `worker-${taskId}` : role);
+}
+
+function sessionNameForRun(runId) {
+  return sanitizeTmuxSessionName(`input-kanban-${runId}`);
+}
+
+function shellQuote(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+
+function buildRunScript({ codexBin, sandbox, cwd, outDir }) {
+  return `#!/usr/bin/env bash
+set -u
+
+CODEX_BIN=${shellQuote(codexBin)}
+SANDBOX=${shellQuote(sandbox)}
+CWD=${shellQuote(cwd)}
+OUT_DIR=${shellQuote(outDir)}
+PROMPT_FILE="$OUT_DIR/prompt.md"
+EVENTS="$OUT_DIR/events.jsonl"
+STDERR_LOG="$OUT_DIR/stderr.log"
+LAST_MESSAGE="$OUT_DIR/last_message.md"
+EXIT_CODE="$OUT_DIR/exit_code"
+
+cd "$CWD"
+rm -f "$EXIT_CODE"
+"$CODEX_BIN" exec --json --sandbox "$SANDBOX" -C "$CWD" -o "$LAST_MESSAGE" "$(<"$PROMPT_FILE")" >>"$EVENTS" 2>>"$STDERR_LOG"
+code=$?
+printf '%s' "$code" > "$EXIT_CODE"
+exit "$code"
+`;
+}
+
+export function createTmuxRunner({
+  codexBin = CODEX_BIN,
+  tmuxBin = DEFAULT_TMUX_BIN,
+  tmuxOptions = {},
+  pollMs = 1000
+} = {}) {
+  const runningWindows = new Map();
+
+  async function startCodexTask({ runId, taskId, prompt, sandbox, cwd, outDir }) {
+    await ensureDir(outDir);
+    const sessionName = sessionNameForRun(runId);
+    const windowName = windowNameForTask(taskId);
+    const role = roleForTask(taskId);
+    const key = processKey(runId, taskId);
+    const promptFile = path.join(outDir, 'prompt.md');
+    const runScript = path.join(outDir, 'run.sh');
+    const exitFile = path.join(outDir, 'exit_code');
+    const metadataFile = path.join(outDir, 'tmux.json');
+    const startedAt = nowIso();
+
+    await fsp.writeFile(promptFile, prompt);
+    await fsp.writeFile(runScript, buildRunScript({ codexBin, sandbox, cwd, outDir }));
+    await fsp.chmod(runScript, 0o755);
+
+    const metadata = {
+      type: 'input_kanban_tmux_task',
+      version: 1,
+      runner: 'tmux',
+      runId,
+      taskId,
+      role,
+      sessionName,
+      windowName,
+      target: `${sessionName}:${windowName}`,
+      attachCommand: `${tmuxBin} attach-session -t ${sessionName}`,
+      selectWindowCommand: `${tmuxBin} select-window -t ${sessionName}:${windowName}`,
+      selectCommand: `${tmuxBin} select-window -t ${sessionName}:${windowName}`,
+      runScript,
+      promptFile,
+      cwd,
+      sandbox,
+      startedAt
+    };
+    await writeJsonAtomic(metadataFile, metadata);
+
+    const tmuxCommandOptions = {
+      ...tmuxOptions,
+      tmuxBin,
+      cwd,
+      command: runScript
+    };
+    if (await tmuxHasSession(sessionName, tmuxCommandOptions)) {
+      await tmuxNewWindow(sessionName, windowName, tmuxCommandOptions);
+    } else {
+      await tmuxNewSession(sessionName, { ...tmuxCommandOptions, windowName });
+    }
+
+    const listeners = [];
+    let exited = false;
+    let exitCode = null;
+    const timer = setInterval(async () => {
+      const text = await readTextMaybe(exitFile, 1000);
+      if (text === '') return;
+      clearInterval(timer);
+      runningWindows.delete(key);
+      const code = Number(text.trim());
+      exited = true;
+      exitCode = Number.isNaN(code) ? null : code;
+      for (const listener of listeners) listener(exitCode);
+    }, Math.max(100, Number(pollMs) || 1000));
+
+    const handle = {
+      pid: null,
+      onExit(listener) {
+        if (exited) listener(exitCode);
+        else listeners.push(listener);
+      },
+      stop() {}
+    };
+    runningWindows.set(key, { sessionName, windowName, timer });
+    return handle;
+  }
+
+  async function stopRun(runId) {
+    for (const [key, value] of runningWindows.entries()) {
+      if (!key.startsWith(`${runId}:`)) continue;
+      clearInterval(value.timer);
+      runningWindows.delete(key);
+    }
+    const sessionName = sessionNameForRun(runId);
+    try {
+      if (await tmuxHasSession(sessionName, { ...tmuxOptions, tmuxBin })) {
+        await tmuxKillSession(sessionName, { ...tmuxOptions, tmuxBin });
+      }
+    } catch (error) {
+      if (!/no such session/i.test(error?.message || '')) throw error;
+    }
+  }
+
+  function hasRunning(runId, taskId) {
+    return runningWindows.has(processKey(runId, taskId));
+  }
+
+  return { kind: 'tmux', sessionNameForRun, startCodexTask, stopRun, hasRunning };
+}

package/src/runners/tmuxUtils.js

@@ -0,0 +1,15 @@
+export {
+  DEFAULT_TMUX_BIN,
+  TmuxUnavailableError,
+  checkTmuxAvailable,
+  ensureTmuxAvailable,
+  runTmux,
+  sanitizeTmuxName,
+  sanitizeTmuxSessionName,
+  sanitizeTmuxWindowName,
+  tmuxHasSession,
+  tmuxKillSession,
+  tmuxKillWindow,
+  tmuxNewSession,
+  tmuxNewWindow
+} from '../tmux.js';

package/src/server.js

@@ -3,7 +3,7 @@ import fsp from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { CodexAppServerClient } from './appServerClient.js';
-import { APP_ROOT, DEFAULT_REPO, RUNS_DIR } from './utils.js';
+import { APP_ROOT, DEFAULT_REPO, RUNNER, RUNS_DIR } from './utils.js';
 import { createRun, listRuns, startPlanner, dispatchRun, startJudge, refreshRun, readRunFile, readRunTaskText, markTaskCompleted, stopRun, archiveRun } from './orchestrator.js';
 
 const PUBLIC_DIR = path.join(APP_ROOT, 'public');
@@ -42,7 +42,7 @@ async function handleApi(req, res, url, appClient) {
   const parts = url.pathname.split('/').filter(Boolean);
   try {
     if (req.method === 'GET' && url.pathname === '/api/health') {
-      return send(res, 200, { ok: true, appRoot: APP_ROOT, runsDir: RUNS_DIR, defaultRepo: DEFAULT_REPO });
+      return send(res, 200, { ok: true, appRoot: APP_ROOT, runsDir: RUNS_DIR, defaultRepo: DEFAULT_REPO, runner: RUNNER });
     }
     if (parts[1] === 'runs' && parts.length === 2) {
       if (req.method === 'GET') return send(res, 200, { runs: await listRuns({ includeArchived: url.searchParams.get('includeArchived') === '1' }) });
@@ -100,7 +100,7 @@ export async function startServer({ host = process.env.HOST || '127.0.0.1', port
     appClient.stop();
     await new Promise(resolve => server.close(resolve));
   };
-  return { server, appClient, host, port, url, defaultRepo: DEFAULT_REPO, runsDir: RUNS_DIR, stop };
+  return { server, appClient, host, port, url, defaultRepo: DEFAULT_REPO, runsDir: RUNS_DIR, runner: RUNNER, stop };
 }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) {

package/src/tmux.js

@@ -0,0 +1,139 @@
+import { execFile } from 'node:child_process';
+import crypto from 'node:crypto';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+export const DEFAULT_TMUX_BIN = process.env.KANBAN_TMUX_BIN || 'tmux';
+
+export class TmuxUnavailableError extends Error {
+  constructor(tmuxBin, result) {
+    const detail = result?.stderr || result?.stdout || result?.error?.message || 'command failed';
+    super(`tmux is unavailable: failed to run "${tmuxBin} -V" (${detail.trim()})`);
+    this.name = 'TmuxUnavailableError';
+    this.tmuxBin = tmuxBin;
+    this.result = result;
+  }
+}
+
+function normalizeResult(result) {
+  return {
+    code: Number.isInteger(result?.code) ? result.code : 0,
+    stdout: result?.stdout || '',
+    stderr: result?.stderr || '',
+    error: result?.error
+  };
+}
+
+async function defaultRunner(command, args, { timeoutMs = 3000 } = {}) {
+  try {
+    const { stdout, stderr } = await execFileAsync(command, args, { timeout: timeoutMs, windowsHide: true });
+    return { code: 0, stdout, stderr };
+  } catch (error) {
+    const code = Number.isInteger(error?.code) ? error.code : error?.code === 'ENOENT' ? 127 : 1;
+    return { code, stdout: error?.stdout || '', stderr: error?.stderr || error?.message || '', error };
+  }
+}
+
+async function runCommand(command, args, options = {}) {
+  const runner = options.runner || defaultRunner;
+  return normalizeResult(await runner(command, args, { timeoutMs: options.timeoutMs || 3000 }));
+}
+
+function safeFallback(fallback) {
+  const value = String(fallback || 'tmux')
+    .replace(/[^a-zA-Z0-9._-]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^[^a-zA-Z0-9]+|[^a-zA-Z0-9]+$/g, '');
+  return value || 'tmux';
+}
+
+export function sanitizeTmuxName(value, { fallback = 'tmux', maxLength = 80 } = {}) {
+  const limit = Math.max(16, Number(maxLength) || 80);
+  const original = String(value || '');
+  let name = original
+    .replace(/[^a-zA-Z0-9._-]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^[^a-zA-Z0-9]+|[^a-zA-Z0-9]+$/g, '');
+
+  if (!name) name = safeFallback(fallback);
+  if (name.length <= limit) return name;
+
+  const hash = crypto.createHash('sha256').update(original || name).digest('hex').slice(0, 8);
+  const prefixLength = Math.max(1, limit - hash.length - 1);
+  const fallbackPrefix = safeFallback(fallback).slice(0, prefixLength);
+  const prefix = name.slice(0, prefixLength).replace(/[^a-zA-Z0-9]+$/g, '') || fallbackPrefix;
+  return `${prefix}-${hash}`.slice(0, limit);
+}
+
+export function sanitizeTmuxSessionName(value, options = {}) {
+  return sanitizeTmuxName(value, { fallback: 'input-kanban', ...options });
+}
+
+export function sanitizeTmuxWindowName(value, options = {}) {
+  return sanitizeTmuxName(value, { fallback: 'worker', ...options });
+}
+
+export async function checkTmuxAvailable(options = {}) {
+  const tmuxBin = options.tmuxBin || DEFAULT_TMUX_BIN;
+  const result = await runCommand(tmuxBin, ['-V'], options);
+  return {
+    available: result.code === 0,
+    tmuxBin,
+    version: result.code === 0 ? result.stdout.trim() : '',
+    result
+  };
+}
+
+export async function ensureTmuxAvailable(options = {}) {
+  const status = await checkTmuxAvailable(options);
+  if (!status.available) throw new TmuxUnavailableError(status.tmuxBin, status.result);
+  return status;
+}
+
+export async function runTmux(args, options = {}) {
+  const tmuxBin = options.tmuxBin || DEFAULT_TMUX_BIN;
+  await ensureTmuxAvailable({ ...options, tmuxBin });
+  const result = await runCommand(tmuxBin, args, options);
+  if (result.code !== 0) {
+    const detail = result.stderr || result.stdout || 'command failed';
+    throw new Error(`tmux command failed: ${tmuxBin} ${args.join(' ')} (${detail.trim()})`);
+  }
+  return result;
+}
+
+export async function tmuxHasSession(sessionName, options = {}) {
+  const tmuxBin = options.tmuxBin || DEFAULT_TMUX_BIN;
+  const session = sanitizeTmuxSessionName(sessionName);
+  await ensureTmuxAvailable({ ...options, tmuxBin });
+  const result = await runCommand(tmuxBin, ['has-session', '-t', session], options);
+  return result.code === 0;
+}
+
+export async function tmuxNewSession(sessionName, options = {}) {
+  const session = sanitizeTmuxSessionName(sessionName);
+  const args = ['new-session', '-d', '-s', session];
+  if (options.windowName) args.push('-n', sanitizeTmuxWindowName(options.windowName));
+  if (options.cwd) args.push('-c', options.cwd);
+  if (options.command) args.push(options.command);
+  return runTmux(args, options);
+}
+
+export async function tmuxNewWindow(sessionName, windowName, options = {}) {
+  const session = sanitizeTmuxSessionName(sessionName);
+  const window = sanitizeTmuxWindowName(windowName);
+  const args = ['new-window', '-t', session, '-n', window];
+  if (options.cwd) args.push('-c', options.cwd);
+  if (options.command) args.push(options.command);
+  return runTmux(args, options);
+}
+
+export async function tmuxKillSession(sessionName, options = {}) {
+  return runTmux(['kill-session', '-t', sanitizeTmuxSessionName(sessionName)], options);
+}
+
+export async function tmuxKillWindow(sessionName, windowName, options = {}) {
+  const session = sanitizeTmuxSessionName(sessionName);
+  const window = sanitizeTmuxWindowName(windowName);
+  return runTmux(['kill-window', '-t', `${session}:${window}`], options);
+}

package/src/utils.js

@@ -7,6 +7,15 @@ export const APP_ROOT = path.resolve(path.dirname(new URL(import.meta.url).pathn
 export const DEFAULT_REPO = path.resolve(process.env.KANBAN_DEFAULT_REPO || process.cwd());
 export const RUNS_DIR = path.resolve(process.env.KANBAN_RUNS_DIR || path.join(process.env.HOME || APP_ROOT, '.input-kanban', 'runs'));
 export const CODEX_BIN = process.env.KANBAN_CODEX_BIN || 'codex';
+export const VALID_RUNNERS = ['headless', 'tmux'];
+
+export function normalizeRunner(value = 'headless', source = 'KANBAN_RUNNER') {
+  const runner = String(value || '').trim();
+  if (VALID_RUNNERS.includes(runner)) return runner;
+  throw new Error(`invalid ${source}: ${value}; expected one of: ${VALID_RUNNERS.join(', ')}`);
+}
+
+export const RUNNER = normalizeRunner(process.env.KANBAN_RUNNER || 'headless');
 
 export async function ensureDir(dir) { await fsp.mkdir(dir, { recursive: true }); }
 export function nowIso() { return new Date().toISOString(); }