input-kanban 0.0.12 → 0.0.14

package/ENVIRONMENT.md

@@ -40,7 +40,7 @@ input-kanban \
 ## Notes
 
 - `KANBAN_DEFAULT_WORKSPACE` / `--workspace` should point to the local directory where work should run; `KANBAN_DEFAULT_REPO` / `--repo` remain compatibility aliases.
-- `input-kanban serve` starts a lightweight background scheduler that uses the same orchestrator auto-advance path as CLI `submit --auto` / `input-kanban auto <runId>`. It advances planned runs, serial batches, final judge startup, and bounded automatic retries without relying on an open browser tab.
+- `input-kanban serve` starts a lightweight background scheduler that uses the same orchestrator auto-advance path as CLI `submit --auto` / `input-kanban auto <runId>`. It advances planned runs, serial batches, final judge startup, and bounded automatic retries without relying on an open browser tab. If a run was created with `--plan-approval` / plan approval gate enabled, the scheduler stops after planning until the user confirms the plan.
 - `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.
 - With `KANBAN_RUNNER=tmux`, stopping and restarting `input-kanban serve` does not interrupt already-running Codex sessions; tmux keeps them alive and the scheduler resumes after restart. Do not assume the same safety for `headless` runner child processes.

package/PROJECT_GUIDE.md

@@ -121,6 +121,7 @@ Supported submit options:
 --task-file <path|->
 --max-parallel <n>
 --worker-sandbox <read-only|workspace-write|danger-full-access>
+--plan-approval
 --runner <headless|tmux>
 --runs-dir <path>
 --auto
@@ -130,7 +131,7 @@ Supported submit options:
 --poll-ms <ms>
 ```
 
-`input-kanban submit` creates a run and starts the planner. Task content can come from `--task <text>` or `--task-file <path|->`; omitting `--workspace` uses the current working directory as the target workspace, and `--repo` remains a compatibility alias. Omitting `--label` derives the run label from the first non-empty task line. Auto mode is the default for submit: it keeps polling the run through the shared orchestrator auto-advance path, dispatches batches when the plan is ready, and starts the final judge once all batches complete. `--no-auto` keeps submit to create + plan only. `-d` / `--detach` starts a background supervisor process for the same auto loop and lets the submitting terminal return immediately. The Web server also starts a lightweight scheduler that uses this shared path, so serial batch advancement does not depend on an open browser tab. The submit output includes `input-kanban status <runId> --watch` for terminal-side observation. Because it writes to the same runs directory as the Web server, CLI-created runs are visible in the 8787 dashboard when both processes use the same `--runs-dir`.
+`input-kanban submit` creates a run and starts the planner. Task content can come from `--task <text>` or `--task-file <path|->`; omitting `--workspace` uses the current working directory as the target workspace, and `--repo` remains a compatibility alias. Omitting `--label` derives the run label from the first non-empty task line. Auto mode is the default for submit: it keeps polling the run through the shared orchestrator auto-advance path, dispatches batches when the plan is ready, and starts the final judge once all batches complete. `--plan-approval` adds a durable Planner → Worker gate: auto advances through planning, then pauses at the completed plan until the user confirms it from the Web dashboard by clicking `开始执行`. `--no-auto` keeps submit to create + plan only for the current CLI process, but a running Web server scheduler can still advance the run unless a durable gate such as `--plan-approval` is configured. `-d` / `--detach` starts a background supervisor process for the same auto loop and lets the submitting terminal return immediately. The Web server also starts a lightweight scheduler that uses this shared path, so serial batch advancement does not depend on an open browser tab. The submit output includes `input-kanban status <runId> --watch` for terminal-side observation. Because it writes to the same runs directory as the Web server, CLI-created runs are visible in the 8787 dashboard when both processes use the same `--runs-dir`.
 
 Default behavior:
 
@@ -160,8 +161,8 @@ Key points:
 - `result` prefers `judge/verdict.json` and falls back to `judge/last_message.md`; `--copy` copies the result to the clipboard.
 - `stop` requires an explicit `runId` and uses the same stop path as the Web dashboard.
 - `retry` retries failed/unknown workers while preserving the failed attempt directory.
-- `submit` defaults to auto mode: planner -> dispatch -> final judge, with one automatic retry for `batch_blocked` by default. `--no-auto` keeps create + plan only, and `-d/--detach` moves the auto loop to a background supervisor.
-- The Web dashboard now follows the same default auto behavior while the page is open: after planning it auto-dispatches planned runs and auto-starts the final judge once all batches complete.
+- `submit` defaults to auto mode: planner -> dispatch -> final judge, with one automatic retry for `batch_blocked` by default. `--plan-approval` changes this to planner -> wait for plan confirmation -> dispatch -> final judge. `--no-auto` keeps create + plan only for the CLI process, and `-d/--detach` moves the auto loop to a background supervisor.
+- The Web server scheduler follows the same shared auto behavior: after planning it auto-dispatches planned runs and auto-starts the final judge once all batches complete, unless a plan approval gate is required and still unapproved.
 
 Example agent loop:
 

package/README.md

@@ -56,7 +56,15 @@ input-kanban submit --task "修复登录问题，并补充回归测试" --label
 
 `submit` 默认会创建任务批次、发起拆分、自动派发所有批次，并在全部完成后自动发起最终验收。默认 workspace 是当前目录；如果不传 `--label`，任务批次名称会从任务内容自动生成。它使用同一个 runs 目录，所以只要 8787 Web 看板也使用相同的 `--runs-dir`，CLI 创建的任务会在 Web 界面里可见。
 
-`input-kanban serve` 会启动一个轻量后台 scheduler，持续刷新并推进未完成的 run：plan ready 后派发 batch、串行 batch 完成后启动下一批、全部 batch 完成后启动 final judge。CLI `submit --auto` / `input-kanban auto <runId>` 与 Web server 共用同一套 orchestrator 自动推进逻辑，因此任务推进不再依赖浏览器页面是否打开或刷新。
+如果希望 Planner 拆分完成后先看一眼计划，再放行执行，可以加计划确认 Gate：
+
+```bash
+input-kanban submit --task-file task.md --plan-approval
+```
+
+开启后，auto 会推进到 Planner 完成并停在“已拆分，待确认”；用户在 Web 上点一次“开始执行”即确认计划，随后 worker 批次和 final judge 继续自动推进。
+
+`input-kanban serve` 会启动一个轻量后台 scheduler，持续刷新并推进未完成的 run：plan ready 后派发 batch、串行 batch 完成后启动下一批、全部 batch 完成后启动 final judge。CLI `submit --auto` / `input-kanban auto <runId>` 与 Web server 共用同一套 orchestrator 自动推进逻辑，因此任务推进不再依赖浏览器页面是否打开或刷新。若 run 配置了计划确认 Gate，auto/scheduler 会停在该 Gate，不会越过未确认的计划。
 
 如果希望提交后立即返回，让任务在后台自动执行，可以加 `-d` / `--detach`：
 

package/RELEASE_NOTES.md

@@ -1,5 +1,41 @@
 # Release Notes
 
+## v0.0.14
+
+### Highlights
+
+- Add a durable Plan Approval Gate: runs can now pause after planning until the generated plan is manually confirmed.
+- Add `input-kanban submit --plan-approval`, which lets auto advance through planning and then stop at the unapproved plan gate instead of dispatching workers immediately.
+- Make `dispatchRun()` confirm the plan gate before starting workers, so Web `开始执行` means “approve this plan and continue execution.”
+- Clarify auto semantics in docs: auto advances to completion, failure, or the first unapproved gate; `--no-auto` is not a durable scheduler gate.
+- Update the Web create form wording to `计划生成后手动确认后执行` and show planned gated runs as `已拆分，待确认`.
+- Rework the run detail header layout: keep title/status on the left, move `Run ID ⧉` and `tmux ⧉` copy tools to a lightweight right-side tool group, and keep long unreadable IDs out of metadata chips.
+- Record the Agent Profile / Candidate / Reviewer design direction in the private KB while keeping the current executor Codex-only.
+
+### Verification
+
+- `npm run check` passed locally with 78 tests.
+- `npm run check` passed on the remote Windows validation host `zhangxing_win` with 78 tests for the release-candidate working tree.
+- Windows Web smoke confirmed the plan approval input, compact title copy tools, `/api/health`, and `/api/codex`.
+
+## v0.0.13
+
+### Highlights
+
+- Harden Codex launching on Windows by resolving npm `codex.cmd` shims and explicit JavaScript launchers through a shared `resolveCodexLauncher()` adapter.
+- Use the shared Codex launcher path from the app-server client, headless runner, tmux runner, and Web footer Codex detection.
+- Add `/api/codex` and a compact Web footer Codex status that shows the backend-visible CLI version, for example `codex-cli 0.139.0`, without relying on npm registry `latest` by default.
+- Improve Web action feedback by turning run action buttons into lightweight state indicators: pending actions disable immediately, active backend states pulse subtly, and retry/done states use concise labels.
+- Keep `batch_blocked` runs discoverable via `input-kanban runs --active`, so agent/CLI auto loops can continue recoverable work instead of hiding blocked batches.
+- Make retry preparation atomic when selected tasks include a live process: no worker attempt is archived until all selected tasks are confirmed safe to retry.
+- Add Windows-focused regression coverage for Codex launcher resolution, app-server spawn failures, headless spawn failures, and tmux launcher quoting.
+
+### Verification
+
+- `npm run check` passed locally with 76 tests.
+- `npm run check` passed on the remote Windows validation host `zhangxing_win` with 76 tests after installing `@openai/codex` CLI.
+- Windows backend Codex detection returned `codex-cli 0.139.0` through `detectCodexInfo()`.
+
 ## v0.0.12
 
 ### Highlights

package/bin/input-kanban.js

@@ -171,7 +171,7 @@ function parseSubmitArgs(argv) {
   const args = {
     host: '127.0.0.1', port: 8787, workspace: undefined, repo: undefined, runsDir: undefined, codexBin: undefined,
     runner: undefined, label: undefined, taskText: undefined, taskFile: undefined, maxParallel: 3,
-    workerSandbox: 'workspace-write', auto: true, detach: false, watch: true, json: false, pollMs: 3000, maxRetries: 1, help: false
+    workerSandbox: 'workspace-write', planApproval: false, auto: true, detach: false, watch: true, json: false, pollMs: 3000, maxRetries: 1, help: false
   };
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
@@ -190,6 +190,7 @@ function parseSubmitArgs(argv) {
     else if (arg === '--task-file') args.taskFile = next();
     else if (arg === '--max-parallel') args.maxParallel = Number(next());
     else if (arg === '--worker-sandbox') args.workerSandbox = validateSandbox(next(), '--worker-sandbox');
+    else if (arg === '--plan-approval') args.planApproval = true;
     else if (arg === '--auto') { args.auto = true; args.watch = true; }
     else if (arg === '--no-auto') { args.auto = false; args.watch = false; }
     else if (arg === '--detach' || arg === '-d') args.detach = true;
@@ -290,6 +291,7 @@ Submit options:
   --task-file <path>         Read task description from file, use - for stdin
   --max-parallel <n>         Default max parallel workers, default 3
   --worker-sandbox <mode>    read-only, workspace-write, or danger-full-access
+  --plan-approval            Pause after planning until the generated plan is confirmed
   --runner <mode>            Runner mode: headless or tmux
   --runs-dir <path>          Runtime runs directory shared with the Web UI
   --auto                     Plan, dispatch all batches, judge, and watch, default for submit
@@ -318,6 +320,7 @@ Options:
   --task-file <path>         Read task description from file, use - for stdin
   --max-parallel <n>         Default max parallel workers, default 3
   --worker-sandbox <mode>    read-only, workspace-write, or danger-full-access
+  --plan-approval            Pause after planning until the generated plan is confirmed
   --runner <mode>            Runner mode: headless or tmux
   --runs-dir <path>          Runtime runs directory shared with the Web UI
   --auto                     Plan, dispatch all batches, judge, and watch, default for submit
@@ -509,7 +512,7 @@ function isFailureTerminal(state) {
 function isActiveRunSummary(run) {
   if (!run) return false;
   if (Number(run.running) > 0) return true;
-  return !['judged', 'judge_failed', 'batch_blocked', 'plan_failed', 'plan_empty', 'stopped'].includes(run.status);
+  return !['judged', 'judge_failed', 'plan_failed', 'plan_empty', 'stopped'].includes(run.status);
 }
 
 function hasRecoverableUnknownTask(state) {
@@ -735,7 +738,8 @@ async function submit(args) {
     workspace: process.env.KANBAN_DEFAULT_WORKSPACE || process.env.KANBAN_DEFAULT_REPO,
     repo: process.env.KANBAN_DEFAULT_REPO,
     maxParallel: args.maxParallel,
-    workerSandbox: args.workerSandbox
+    workerSandbox: args.workerSandbox,
+    planApproval: args.planApproval
   });
   if (!args.json) {
     console.log(`已创建任务批次: ${state.runId}`);

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "input-kanban",
-  "version": "0.0.12",
+  "version": "0.0.14",
   "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 bin/input-kanban-format-events.js && node --check bin/input-kanban-timestamp-events.js && node --check bin/input-kanban-tmux-overview.js && node --check src/server.js && node --check src/scheduler.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"
+    "check": "node --check bin/input-kanban.js && node --check bin/input-kanban-format-events.js && node --check bin/input-kanban-timestamp-events.js && node --check bin/input-kanban-tmux-overview.js && node --check src/server.js && node --check src/scheduler.js && node --check src/orchestrator.js && node --check src/appServerClient.js && node --check src/codexLauncher.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 --check test/app-server-client.test.js && node --check test/app-server-client-stop.test.js && node --test"
   },
   "description": "A local Codex orchestration kanban dashboard",
   "license": "MIT",

package/public/index.html

@@ -26,10 +26,19 @@
     textarea:focus, input:focus, select:focus { border-color: #60a5fa; box-shadow: 0 0 0 2px rgba(37,99,235,.25); }
     textarea { min-height: 240px; }
     label { display: block; margin-top: 10px; color: #cbd5e1; font-weight: 700; }
-    button { background: var(--blue); color: white; border: 0; border-radius: 9px; padding: 8px 11px; margin: 4px 4px 4px 0; cursor: pointer; font-weight: 700; }
-    button:hover { filter: brightness(1.08); }
+    button { background: var(--blue); color: white; border: 0; border-radius: 9px; padding: 8px 11px; margin: 4px 4px 4px 0; cursor: pointer; font-weight: 700; transition: filter .15s, opacity .15s, transform .15s, box-shadow .15s; }
+    button:hover:not(:disabled) { filter: brightness(1.08); }
+    button:disabled { cursor: default; opacity: .72; }
     button.secondary { background: var(--gray); }
     button.danger { background: #dc2626; }
+    button.state-pending { position: relative; opacity: .82; }
+    button.state-pending::after { content: ''; display: inline-block; width: 5px; height: 5px; margin-left: 7px; border-radius: 999px; background: currentColor; vertical-align: middle; animation: action-dot 1s ease-in-out infinite; }
+    button.state-active { animation: action-pulse 1.6s ease-in-out infinite; box-shadow: 0 0 0 1px rgba(96,165,250,.18), 0 0 18px rgba(37,99,235,.16); }
+    button.state-done { opacity: .58; filter: saturate(.75); }
+    button.state-retry { background: var(--orange); }
+    @keyframes action-pulse { 0%, 100% { filter: brightness(1); transform: translateY(0); } 50% { filter: brightness(1.12); transform: translateY(-1px); } }
+    @keyframes action-dot { 0%, 100% { opacity: .35; transform: scale(.75); } 50% { opacity: 1; transform: scale(1.15); } }
+    @media (prefers-reduced-motion: reduce) { button, button.state-active, button.state-pending::after, .refresh-pulse-chip.pulse .refresh-pulse-dot { animation: none !important; transition: none !important; } }
     table { width: 100%; border-collapse: collapse; font-size: 13px; table-layout: fixed; }
     th, td { border-bottom: 1px solid var(--line); padding: 9px 8px; text-align: left; vertical-align: top; }
     th:nth-child(1), td:nth-child(1) { width: 34%; }
@@ -82,8 +91,11 @@
     .run-card-meta .meta-chip { padding: 4px 7px; font-size: 11px; }
     .run-card-meta .meta-chip.long .meta-value { max-width: 248px; }
     .build-header { border: 1px solid var(--line); border-radius: 12px; padding: 14px; background: var(--panel-2); margin-bottom: 14px; }
-    .build-title { display: flex; align-items: center; gap: 10px; font-size: 22px; font-weight: 900; }
-    .build-meta { margin-top: 10px; display: flex; flex-wrap: wrap; gap: 7px; align-items: center; }
+    .build-title { display: grid; grid-template-columns: minmax(0, 1fr) auto; gap: 10px; align-items: center; font-size: 22px; font-weight: 900; }
+    .build-title-main { min-width: 0; display: flex; align-items: center; gap: 10px; }
+    .build-title-text { min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+    .build-title-tools { display: inline-flex; align-items: center; gap: 6px; justify-self: end; }
+    .build-meta { margin-top: 12px; display: flex; flex-wrap: wrap; gap: 7px; align-items: center; }
     .meta-chip { display: inline-flex; align-items: center; gap: 6px; max-width: 100%; padding: 5px 8px; border: 1px solid var(--line); border-radius: 999px; background: #020617; color: #cbd5e1; font-size: 12px; line-height: 1.2; }
     .meta-chip.danger { border-color: #f97316; color: #fed7aa; background: rgba(180,83,9,.14); }
     .meta-label { color: var(--muted); font-weight: 800; white-space: nowrap; }
@@ -97,6 +109,9 @@
     .log-panel { margin-top: 16px; }
     .file-tabs button { font-size: 13px; }
     .copy-btn { padding: 2px 6px; margin: 0 0 0 6px; border-radius: 6px; font-size: 12px; line-height: 1.2; background: var(--gray); vertical-align: middle; }
+    .title-copy-btn { display: inline-flex; align-items: center; gap: 5px; opacity: .78; font-size: 12px; padding: 5px 8px; margin: 0; }
+    .title-copy-btn:hover, .title-copy-btn:focus { opacity: 1; }
+    .title-copy-btn .icon-svg { width: 12px; height: 12px; }
     .rename-btn { opacity: 0; pointer-events: none; transition: opacity .15s ease; }
     .run-card:hover .rename-btn, .run-card:focus-within .rename-btn, .build-title:hover .rename-btn, .build-title:focus-within .rename-btn, .rename-btn:focus { opacity: 1; pointer-events: auto; }
     .run-card-title-actions { display: inline-flex; align-items: center; gap: 3px; }
@@ -117,6 +132,9 @@
     .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); }
+    .codex-status { margin-top: 4px; color: var(--muted); font-size: 12px; }
+    .codex-status.warning { color: #fbbf24; }
+    .codex-status code { color: #bfdbfe; }
     .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; }
@@ -157,6 +175,8 @@
         <option value="danger-full-access">danger-full-access（高风险，跳过沙箱限制）</option>
       </select>
       <div class="muted">仅影响 worker；任务拆分和汇总验收仍保持 read-only。若执行过程提示 Permission denied / sandbox denied，这通常不是任务本身失败，而是当前沙箱能力不足；在可信工作区可改用 danger-full-access。DNS / 网络失败则通常需要检查代理、VPN 或本地 evidence。</div>
+      <label><input id="planApproval" type="checkbox" style="width:auto; margin-right:6px;" />计划生成后手动确认后执行</label>
+      <div class="muted">开启后会停在“已拆分，待确认”；点击“开始执行”后继续自动执行到验收。</div>
       <label>任务说明</label><textarea id="taskText" placeholder="粘贴任务说明"></textarea>
       <div class="toolbar">
         <button onclick="createRun()">创建批次</button>
@@ -170,14 +190,7 @@
         <div id="selected" class="muted">未选择任务批次</div>
         <div id="autoRefreshHint" class="muted hidden">自动刷新：未启动</div>
         <div id="runNotice" class="notice warning hidden"></div>
-        <div class="toolbar">
-          <button onclick="planRun()">拆分任务</button>
-          <button onclick="dispatchRun()">派发执行</button>
-          <button onclick="judgeRun()">汇总验收</button>
-          <button class="secondary" onclick="refreshSelected()">刷新状态</button>
-          <button class="secondary" onclick="stopSelectedRun()">停止</button>
-          <button class="danger" onclick="archiveSelectedRun()">归档</button>
-        </div>
+        <div id="actionToolbar" class="toolbar"></div>
       </div>
       <h3>任务说明</h3>
       <pre id="taskDescription" class="task-text">未选择任务批次</pre>
@@ -199,7 +212,7 @@
     </section>
   </div>
 </main>
-<footer id="pageFooter" class="page-footer">版本：-</footer>
+<footer class="page-footer"><div id="pageFooter">版本：-</div><div id="codexStatus" class="codex-status hidden"></div></footer>
 <div id="manualCompleteModal" class="modal-backdrop hidden">
   <div class="modal-card">
     <h2>手动标记成功</h2>
@@ -219,6 +232,7 @@ let selectedTask = null;
 let selectedFileName = null;
 let manualCompleteTaskId = null;
 let pendingArchiveRunId = null;
+let pendingAction = null;
 let currentState = null;
 let lastAutoRefreshAt = null;
 let runListVisibleCount = 10;
@@ -267,6 +281,9 @@ const roleText = { planner: '任务拆分', judge: '汇总验收' };
 function displayStatus(s) { return statusText[s] || s || '-'; }
 function displayRole(s) { return roleText[s] || s || '-'; }
 function pill(s) { return `<span class="pill ${s || ''}">${displayStatus(s)}</span>`; }
+function planApprovalPending(state = currentState) { return !!(state?.gates?.planApproval?.required && !state.gates.planApproval.approved); }
+function runStatusLabel(state = currentState) { return planApprovalPending(state) ? '已拆分，待确认' : displayStatus(state?.status); }
+function statusPill(state = currentState) { return `<span class="pill ${state?.status || ''}">${esc(runStatusLabel(state))}</span>`; }
 function esc(s) { return String(s ?? '').replace(/[&<>]/g, c => ({'&':'&amp;','<':'&lt;','>':'&gt;'}[c])); }
 function formatDateTime(s) {
   if (!s) return '-';
@@ -308,6 +325,12 @@ function gitChip() { return '<span class="meta-chip" title="Git 工作区"><span
 function editIcon() {
   return '<svg class="icon-svg" viewBox="0 0 24 24" focusable="false" aria-hidden="true"><path d="M4 16.5V20h3.5L18.1 9.4l-3.5-3.5L4 16.5Z" fill="currentColor"/><path d="m16 4.5 3.5 3.5" stroke="currentColor" stroke-width="2" stroke-linecap="round"/></svg>';
 }
+function copyIcon() {
+  return '<svg class="icon-svg" viewBox="0 0 24 24" focusable="false" aria-hidden="true"><path d="M8 8h11v11H8V8Z" fill="none" stroke="currentColor" stroke-width="2"/><path d="M5 16H4V4h12v1" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"/></svg>';
+}
+function titleCopyLabel(kind) {
+  return kind === 'tmux' ? `<span>tmux</span>${copyIcon()}` : `<span>Run ID</span>${copyIcon()}`;
+}
 function archiveIcon() {
   return '<svg class="icon-svg" viewBox="0 0 24 24" focusable="false" aria-hidden="true"><path d="M4 5h16v4H4V5Z" fill="currentColor"/><path d="M6 10h12v9H6v-9Z" fill="currentColor" opacity=".72"/><path d="M9 13h6" stroke="#020617" stroke-width="2" stroke-linecap="round"/></svg>';
 }
@@ -356,6 +379,25 @@ async function loadHealth() {
   renderWorkspaceFilterOptions();
   updateWorkspaceFilterTitle();
 }
+async function loadCodexStatus() {
+  const el = document.getElementById('codexStatus');
+  if (!el) return;
+  try {
+    const data = await api('/api/codex');
+    const codex = data.codex || {};
+    el.classList.remove('hidden', 'warning');
+    if (!codex.installed) {
+      el.classList.add('warning');
+      el.innerHTML = `Codex 未安装｜<code>${esc(codex.installCommand || 'npm install -g @openai/codex')}</code>`;
+    } else {
+      el.innerHTML = `<code>${esc(codex.versionText || codex.installedVersion || 'codex')}</code>`;
+    }
+  } catch (error) {
+    el.classList.remove('hidden');
+    el.classList.add('warning');
+    el.innerHTML = `Codex：检测失败｜${esc(errorDetail(error))}`;
+  }
+}
 function showCreateForm() {
   selectedRun = null; selectedTask = null; selectedFileName = null; currentState = null;
   clearFileView();
@@ -382,7 +424,7 @@ function initializeWorkerSandboxPreference() {
 }
 async function createRun() {
   saveWorkerSandboxPreference();
-  const body = { label: label.value, workspace: repo.value, repo: repo.value, maxParallel: maxParallel.value, workerSandbox: workerSandbox.value, taskText: taskText.value };
+  const body = { label: label.value, workspace: repo.value, repo: repo.value, maxParallel: maxParallel.value, workerSandbox: workerSandbox.value, planApproval: planApproval.checked, taskText: taskText.value };
   const r = await api('/api/runs', { method: 'POST', body: JSON.stringify(body) });
   selectedRun = r.runId; selectedTask = null; selectedFileName = null;
   clearFileView();
@@ -419,7 +461,7 @@ function renderRunList() {
   const visibleRuns = latestRuns.slice(0, runListVisibleCount);
   const cards = visibleRuns.map(r => `
     <div class="run-card ${selectedRun === r.runId ? 'active' : ''}" onclick="selectRun('${r.runId}')" onmouseleave="clearArchiveConfirm('${r.runId}')">
-      <div class="run-card-title"><span class="run-card-name-wrap"><span class="run-card-name" title="${esc(r.label)}">${esc(r.label)}</span><span class="run-card-title-actions"><button class="secondary copy-btn rename-btn" title="修改任务批次名称" onclick="renameRunLabel(event, '${r.runId}')">${editIcon()}</button><button class="secondary copy-btn rename-btn ${pendingArchiveRunId === r.runId ? 'archive-confirm-btn' : ''}" title="${pendingArchiveRunId === r.runId ? '再次点击确认归档' : '归档任务批次（运行中请先停止）'}" onclick="archiveRunFromCard(event, '${r.runId}')">${pendingArchiveRunId === r.runId ? '确认' : archiveIcon()}</button></span></span><span>${pill(r.status)}</span></div>
+      <div class="run-card-title"><span class="run-card-name-wrap"><span class="run-card-name" title="${esc(r.label)}">${esc(r.label)}</span><span class="run-card-title-actions"><button class="secondary copy-btn rename-btn" title="修改任务批次名称" onclick="renameRunLabel(event, '${r.runId}')">${editIcon()}</button><button class="secondary copy-btn rename-btn ${pendingArchiveRunId === r.runId ? 'archive-confirm-btn' : ''}" title="${pendingArchiveRunId === r.runId ? '再次点击确认归档' : '归档任务批次（运行中请先停止）'}" onclick="archiveRunFromCard(event, '${r.runId}')">${pendingArchiveRunId === r.runId ? '确认' : archiveIcon()}</button></span></span><span>${statusPill(r)}</span></div>
       <div class="run-card-meta">
         ${metaChip('工作区', basenamePath(r.workspacePath || r.repo), { title: r.workspacePath || r.repo, long: true, extra: `<button class="secondary copy-btn" title="复制工作区地址" onclick="copyRunRepoPath(event, '${r.runId}')">⧉</button>` })}
         ${r.git?.isGit ? gitChip() : ''}
@@ -486,6 +528,7 @@ async function refreshSelected({auto=false} = {}) {
   statusByRunId.set(selectedRun, currentState);
   if (auto) lastAutoRefreshAt = new Date();
   document.getElementById('selected').innerHTML = renderSelectedHeader();
+  renderActionToolbar();
   if (auto) requestAnimationFrame(triggerRefreshPulse);
   updateAutoRefreshHint();
   updateRunNotice();
@@ -496,8 +539,11 @@ async function refreshSelected({auto=false} = {}) {
 function renderSelectedHeader() {
   if (!currentState) return '<div class="muted">未选择任务批次</div>';
   const sandbox = currentState.workerSandbox || 'workspace-write';
+  const titleActions = [`<button class="secondary copy-btn title-copy-btn" title="复制 Run ID：${esc(currentState.runId)}" data-copy-kind="run-id" onclick="copyRunId(event)">${titleCopyLabel('run-id')}</button>`];
+  if (currentState.runner === 'tmux' && hasRunTmuxMetadata(currentState)) {
+    titleActions.push(`<button class="secondary copy-btn title-copy-btn" title="复制 tmux attach 指令" data-copy-kind="tmux" onclick="copyTmuxRunCommand(event)">${titleCopyLabel('tmux')}</button>`);
+  }
   const chips = [
-    metaChip('Run ID', currentState.runId, { long: true }),
     metaChip('工作区', basenamePath(currentState.workspacePath || currentState.repo), {
       title: currentState.workspacePath || currentState.repo,
       long: true,
@@ -510,18 +556,8 @@ function renderSelectedHeader() {
   if (currentState.git?.isGit || currentState.workspace?.git?.isGit) {
     chips.push(gitChip());
   }
-  if (currentState.runner === 'tmux') {
-    if (hasRunTmuxMetadata(currentState)) {
-      chips.push(metaChip('终端', tmuxSessionName(currentState), {
-        long: true,
-        extra: `<button class="secondary copy-btn" onclick="copyTmuxRunCommand(event)">复制tmux attach指令</button>`
-      }));
-    } else {
-      chips.push(metaChip('终端', 'tmux 现场尚未生成'));
-    }
-  }
   chips.push(refreshPulseChip());
-  return `<div class="build-title"><span>${esc(currentState.label)}</span><button class="secondary copy-btn rename-btn" title="修改任务批次名称" onclick="renameRunLabel(event, currentState.runId)">${editIcon()}</button>${pill(currentState.status)}</div><div class="build-meta">${chips.join('')}</div>`;
+  return `<div class="build-title"><div class="build-title-main"><span class="build-title-text">${esc(currentState.label)}</span><button class="secondary copy-btn rename-btn" title="修改任务批次名称" onclick="renameRunLabel(event, currentState.runId)">${editIcon()}</button>${statusPill(currentState)}</div><div class="build-title-tools">${titleActions.join('')}</div></div><div class="build-meta">${chips.join('')}</div>`;
 }
 async function loadTaskDescription() {
   if (!selectedRun) { document.getElementById('taskDescription').textContent = '未选择任务批次'; return; }
@@ -531,6 +567,98 @@ function refreshPulseChip() {
   const last = lastAutoRefreshAt ? lastAutoRefreshAt.toLocaleTimeString() : '尚未触发';
   return `<span id="refreshPulse" class="refresh-pulse-chip" title="自动刷新：每 ${AUTO_REFRESH_MS / 1000} 秒；上次 ${esc(last)}"><span class="refresh-pulse-dot"></span></span>`;
 }
+function actionButton({ key, label, onclick, variant = '', state = '', disabled = false, title = '' }) {
+  const classes = [variant, state ? `state-${state}` : ''].filter(Boolean).join(' ');
+  return `<button${classes ? ` class="${classes}"` : ''}${disabled ? ' disabled' : ''}${title ? ` title="${esc(title)}"` : ''} onclick="${onclick}">${esc(label)}</button>`;
+}
+function runActionState(key) {
+  if (!selectedRun || !currentState) return { label: '-', disabled: true, state: '' };
+  if (pendingAction === key) {
+    return {
+      plan: { label: '拆分中…', disabled: true, state: 'pending' },
+      dispatch: { label: '启动中…', disabled: true, state: 'pending' },
+      judge: { label: '验收中…', disabled: true, state: 'pending' },
+      stop: { label: '停止中…', disabled: true, state: 'pending' },
+      archive: { label: '归档中…', disabled: true, state: 'pending' }
+    }[key];
+  }
+  const status = currentState.status;
+  const anyWorkerRunning = (currentState.tasks || []).some(t => t.status === 'running');
+  if (key === 'plan') {
+    if (status === 'planning' || currentState.planner?.status === 'running') return { label: '拆分中', disabled: true, state: 'active' };
+    if (status === 'planned' || status === 'running' || status === 'workers_completed' || status === 'batches_completed' || status === 'judging' || status === 'judged') return { label: '已拆分', disabled: true, state: 'done' };
+    if (status === 'plan_failed' || status === 'plan_empty') return { label: '重试拆分', disabled: false, state: 'retry' };
+    return { label: '拆分', disabled: false, state: '' };
+  }
+  if (key === 'dispatch') {
+    if (status === 'running' || anyWorkerRunning) return { label: '执行中', disabled: true, state: 'active' };
+    if (status === 'planned') return { label: planApprovalPending() ? '开始执行' : '执行', disabled: false, state: '' };
+    if (status === 'batch_blocked') return { label: '执行', disabled: false, state: 'retry' };
+    if (status === 'workers_failed') return { label: '重试执行', disabled: false, state: 'retry' };
+    if (['workers_completed','batches_completed','judging','judged'].includes(status)) return { label: '已完成', disabled: true, state: 'done' };
+    return { label: '执行', disabled: true, state: 'done' };
+  }
+  if (key === 'judge') {
+    if (status === 'judging' || currentState.judge?.status === 'running') return { label: '验收中', disabled: true, state: 'active' };
+    if (status === 'judged') return { label: '已验收', disabled: true, state: 'done' };
+    if (status === 'judge_failed') return { label: '重试验收', disabled: false, state: 'retry' };
+    if (status === 'batches_completed' || status === 'workers_completed') return { label: '验收', disabled: false, state: '' };
+    return { label: '验收', disabled: true, state: 'done' };
+  }
+  if (key === 'stop') {
+    if (status === 'stopped') return { label: '已停止', disabled: true, state: 'done' };
+    const stoppable = ['planning','running','judging','planned','batch_blocked'].includes(status) || anyWorkerRunning;
+    return { label: '停止', disabled: !stoppable, state: stoppable ? '' : 'done' };
+  }
+  if (key === 'archive') return { label: '归档', disabled: false, state: '' };
+  return { label: key, disabled: false, state: '' };
+}
+function renderActionToolbar() {
+  const el = document.getElementById('actionToolbar');
+  if (!el) return;
+  if (!selectedRun || !currentState) {
+    el.innerHTML = actionButton({ key: 'refresh', label: '刷新状态', onclick: 'refreshSelected()', variant: 'secondary', disabled: true });
+    return;
+  }
+  const plan = runActionState('plan');
+  const dispatch = runActionState('dispatch');
+  const judge = runActionState('judge');
+  const stop = runActionState('stop');
+  const archive = runActionState('archive');
+  el.innerHTML = [
+    actionButton({ key: 'plan', label: plan.label, onclick: 'planRun()', state: plan.state, disabled: plan.disabled, title: '拆分任务' }),
+    actionButton({ key: 'dispatch', label: dispatch.label, onclick: 'dispatchRun()', state: dispatch.state, disabled: dispatch.disabled, title: '派发执行' }),
+    actionButton({ key: 'judge', label: judge.label, onclick: 'judgeRun()', state: judge.state, disabled: judge.disabled, title: '汇总验收' }),
+    actionButton({ key: 'refresh', label: '刷新', onclick: 'refreshSelected()', variant: 'secondary' }),
+    actionButton({ key: 'stop', label: stop.label, onclick: 'stopSelectedRun()', variant: 'secondary', state: stop.state, disabled: stop.disabled, title: '停止当前批次' }),
+    actionButton({ key: 'archive', label: archive.label, onclick: 'archiveSelectedRun()', variant: 'danger', state: archive.state, disabled: archive.disabled, title: '归档当前批次' })
+  ].join('');
+}
+async function runAction(fn) {
+  try { await fn(); }
+  catch (error) {
+    console.error('操作失败', error);
+    alert(userFacingErrorMessage(error));
+  }
+}
+function renderPendingActionState() {
+  renderActionToolbar();
+  if (currentState) renderTasks();
+}
+async function runActionWithPending(actionKey, fn) {
+  if (pendingAction === actionKey) return;
+  pendingAction = actionKey;
+  renderPendingActionState();
+  try {
+    await fn();
+  } catch (error) {
+    console.error('操作失败', error);
+    alert(userFacingErrorMessage(error));
+  } finally {
+    pendingAction = null;
+    renderPendingActionState();
+  }
+}
 function triggerRefreshPulse() {
   const el = document.getElementById('refreshPulse');
   if (!el) return;
@@ -579,7 +707,8 @@ function taskActionCell(id, t) {
   if (!t || id === 'planner' || id === 'judge') return '-';
   if (t.manualCompletion) return '<span class="muted">已人工确认</span>';
   if (!['unknown', 'failed'].includes(t.status)) return '-';
-  return `<button class="danger" onclick="markTaskCompleted(event, '${id}')">手动标记成功</button>`;
+  const pending = pendingAction === `manual:${id}`;
+  return `<button class="danger ${pending ? 'state-pending' : ''}"${pending ? ' disabled' : ''} onclick="markTaskCompleted(event, '${id}')">${pending ? '标记中…' : '手动标记成功'}</button>`;
 }
 function shortSessionId(thread) {
   const text = String(thread || '');
@@ -726,6 +855,19 @@ function hideExecutionSummary() {
   el.classList.add('hidden');
   el.innerHTML = '';
 }
+async function copyRunId(event) {
+  event.stopPropagation();
+  const runId = currentState?.runId || selectedRun || '';
+  if (!runId) return;
+  try {
+    await navigator.clipboard.writeText(runId);
+    const kind = event.currentTarget.dataset.copyKind || 'run-id';
+    event.currentTarget.textContent = '✓';
+    setTimeout(() => { event.currentTarget.innerHTML = titleCopyLabel(kind); }, 900);
+  } catch {
+    prompt('复制 Run ID', runId);
+  }
+}
 async function copyRepoPath(event, repoPath = currentState?.workspacePath || currentState?.repo || '') {
   event.stopPropagation();
   if (!repoPath) return;
@@ -746,9 +888,10 @@ async function copyTmuxRunCommand(event) {
   const command = runAttachCommand(currentState);
   if (!command) return;
   try {
+    const kind = event.currentTarget.dataset.copyKind || 'tmux';
     await navigator.clipboard.writeText(command);
-    event.currentTarget.textContent = '已复制';
-    setTimeout(() => { event.currentTarget.textContent = '复制tmux attach指令'; }, 900);
+    event.currentTarget.textContent = '✓';
+    setTimeout(() => { event.currentTarget.innerHTML = titleCopyLabel(kind); }, 900);
   } catch {
     prompt('复制 tmux attach 命令', command);
   }
@@ -905,25 +1048,20 @@ async function renameRunLabel(event, runId = selectedRun) {
     else await refreshRuns();
   });
 }
-async function planRun() { if (selectedRun) await runAction(async () => { await api(`/api/runs/${selectedRun}/plan`, {method:'POST'}); await refreshSelected(); }); }
-async function dispatchRun() { if (selectedRun) await runAction(async () => { await api(`/api/runs/${selectedRun}/dispatch`, {method:'POST'}); await refreshSelected(); }); }
-async function judgeRun() { if (selectedRun) await runAction(async () => { await api(`/api/runs/${selectedRun}/judge`, {method:'POST'}); await refreshSelected(); }); }
-async function runAction(fn) {
-  try { await fn(); }
-  catch (error) {
-    console.error('操作失败', error);
-    alert(userFacingErrorMessage(error));
-  }
-}
+async function planRun() { if (selectedRun) await runActionWithPending('plan', async () => { await api(`/api/runs/${selectedRun}/plan`, {method:'POST'}); await refreshSelected(); }); }
+async function dispatchRun() { if (selectedRun) await runActionWithPending('dispatch', async () => { await api(`/api/runs/${selectedRun}/dispatch`, {method:'POST'}); await refreshSelected(); }); }
+async function judgeRun() { if (selectedRun) await runActionWithPending('judge', async () => { await api(`/api/runs/${selectedRun}/judge`, {method:'POST'}); await refreshSelected(); }); }
 async function stopSelectedRun() {
   if (!selectedRun) return;
   const ok = confirm('确认停止当前任务批次？\n\n停止会终止仍在运行的 codex exec 子进程，并冻结后续调度。');
   if (!ok) return;
-  await api(`/api/runs/${selectedRun}/stop`, {
-    method: 'POST',
-    body: JSON.stringify({ reason: 'stopped from dashboard' })
+  await runActionWithPending('stop', async () => {
+    await api(`/api/runs/${selectedRun}/stop`, {
+      method: 'POST',
+      body: JSON.stringify({ reason: 'stopped from dashboard' })
+    });
+    await refreshSelected();
   });
-  await refreshSelected();
 }
 function clearArchiveConfirm(runId) {
   if (pendingArchiveRunId !== runId) return;
@@ -946,7 +1084,7 @@ async function archiveRunById(runId, { confirmFirst = true } = {}) {
     const ok = confirm('确认归档当前任务批次？\n\n归档后会从默认任务批次列表隐藏。若仍有任务运行，请先停止。');
     if (!ok) return;
   }
-  await runAction(async () => {
+  await runActionWithPending('archive', async () => {
     await api(`/api/runs/${runId}/archive`, {
       method: 'POST',
       body: JSON.stringify({ reason: 'archived from dashboard' })
@@ -986,17 +1124,21 @@ async function submitManualComplete() {
   if (!selectedRun || !taskId) return;
   const resultText = document.getElementById('manualCompleteResult').value.trim();
   if (!resultText) { alert('请粘贴人工成功执行结果。'); return; }
-  await api(`/api/runs/${selectedRun}/tasks/${taskId}/mark-completed`, {
-    method: 'POST',
-    body: JSON.stringify({ reason: 'manual success confirmed from dashboard', resultText })
+  await runActionWithPending(`manual:${taskId}`, async () => {
+    await api(`/api/runs/${selectedRun}/tasks/${taskId}/mark-completed`, {
+      method: 'POST',
+      body: JSON.stringify({ reason: 'manual success confirmed from dashboard', resultText })
+    });
+    closeManualCompleteModal();
+    selectedTask = taskId;
+    await refreshSelected();
+    await loadFile('result.json');
   });
-  closeManualCompleteModal();
-  selectedTask = taskId;
-  await refreshSelected();
-  await loadFile('result.json');
 }
 
 initializeWorkerSandboxPreference();
+renderActionToolbar();
+loadCodexStatus().catch(console.error);
 loadHealth().then(refreshRuns);
 setInterval(() => { if (selectedRun) refreshSelected({auto:true}).catch(console.error); else refreshRuns().catch(console.error); }, AUTO_REFRESH_MS);
 </script>

package/src/appServerClient.js

@@ -1,6 +1,7 @@
 import { spawn } from 'node:child_process';
 import readline from 'node:readline';
 import { CODEX_BIN } from './utils.js';
+import { resolveCodexLauncher } from './codexLauncher.js';
 
 export class CodexAppServerClient {
   constructor() {
@@ -9,20 +10,49 @@ export class CodexAppServerClient {
     this.pending = new Map();
     this.initialized = false;
     this.stderrTail = [];
+    this.rl = null;
   }
 
   start() {
-    if (this.proc) return;
-    this.proc = spawn(CODEX_BIN, ['app-server', '--stdio'], { stdio: ['pipe', 'pipe', 'pipe'] });
+    if (this.proc) return this.proc;
+    const { command, argsPrefix } = resolveCodexLauncher(CODEX_BIN);
+    this.proc = spawn(command, [...argsPrefix, 'app-server', '--stdio'], { stdio: ['pipe', 'pipe', 'pipe'] });
+    const proc = this.proc;
     const rl = readline.createInterface({ input: this.proc.stdout });
+    this.rl = rl;
     rl.on('line', line => this.#handleLine(line));
-    this.proc.stderr.on('data', d => this.#pushStderr(String(d)));
-    this.proc.on('exit', code => {
-      for (const { reject } of this.pending.values()) reject(new Error(`app-server exited: ${code}`));
-      this.pending.clear();
+    proc.stderr.on('data', d => this.#pushStderr(String(d)));
+    proc.on('error', error => {
+      this.#rejectPendingFor(proc, error);
+      this.#clearProcess(proc, rl);
+    });
+    proc.on('exit', code => {
+      this.#rejectPendingFor(proc, new Error(`app-server exited: ${code}`));
+      this.#clearProcess(proc, rl);
+    });
+    return proc;
+  }
+
+  #rejectPendingFor(proc, error) {
+    for (const [id, pending] of this.pending.entries()) {
+      if (pending.proc !== proc) continue;
+      this.pending.delete(id);
+      pending.reject(error);
+    }
+  }
+
+  #rejectAllPending(error) {
+    for (const { reject } of this.pending.values()) reject(error);
+    this.pending.clear();
+  }
+
+  #clearProcess(proc = this.proc, rl = this.rl) {
+    rl?.close();
+    if (this.rl === rl) this.rl = null;
+    if (this.proc === proc) {
       this.proc = null;
       this.initialized = false;
-    });
+    }
   }
 
   #pushStderr(s) {
@@ -42,17 +72,36 @@ export class CodexAppServerClient {
   }
 
   async request(method, params = null, timeoutMs = 15000) {
-    this.start();
+    const proc = this.start();
     const id = this.nextId++;
     const msg = { id, method };
     if (params !== null) msg.params = params;
     return await new Promise((resolve, reject) => {
-      const timer = setTimeout(() => {
+      let timer;
+      let pending;
+      const fail = error => {
+        if (this.pending.get(id) !== pending) return;
         this.pending.delete(id);
-        reject(new Error(`app-server request timeout: ${method}`));
-      }, timeoutMs);
-      this.pending.set(id, { resolve: v => { clearTimeout(timer); resolve(v); }, reject: e => { clearTimeout(timer); reject(e); } });
-      this.proc.stdin.write(JSON.stringify(msg) + '\n');
+        pending.reject(error);
+      };
+      pending = {
+        proc,
+        resolve: v => { clearTimeout(timer); resolve(v); },
+        reject: e => { clearTimeout(timer); reject(e); }
+      };
+      timer = setTimeout(() => fail(new Error(`app-server request timeout: ${method}`)), timeoutMs);
+      this.pending.set(id, pending);
+      if (this.proc !== proc || !proc?.stdin?.writable || proc.stdin.destroyed) {
+        fail(new Error(`app-server unavailable: ${method}`));
+        return;
+      }
+      try {
+        proc.stdin.write(JSON.stringify(msg) + '\n', error => {
+          if (error) fail(error);
+        });
+      } catch (error) {
+        fail(error);
+      }
     });
   }
 
@@ -79,8 +128,11 @@ export class CodexAppServerClient {
 
   stop() {
     if (!this.proc) return;
-    this.proc.kill('TERM');
-    this.proc = null;
+    const proc = this.proc;
+    const rl = this.rl;
+    this.proc.kill();
+    this.#rejectAllPending(new Error('app-server stopped'));
+    this.#clearProcess(proc, rl);
   }
 }
 

package/src/codexLauncher.js

@@ -0,0 +1,88 @@
+import fs from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+
+const MAX_SHIM_BYTES = 64 * 1024;
+const WHERE_TIMEOUT_MS = 5000;
+
+function existingPath(filePath) {
+  return fs.existsSync(filePath) ? filePath : null;
+}
+
+function codexJsCandidatesFromShim(shimPath) {
+  const dir = path.dirname(shimPath);
+  return [
+    path.join(dir, 'node_modules', '@openai', 'codex', 'bin', 'codex.js'),
+    path.join(dir, '..', '@openai', 'codex', 'bin', 'codex.js')
+  ];
+}
+
+function codexJsFromShim(shimPath) {
+  for (const candidate of codexJsCandidatesFromShim(shimPath)) {
+    const found = existingPath(candidate);
+    if (found) return found;
+  }
+  return null;
+}
+
+function readShimTarget(filePath) {
+  try {
+    if (/codex\.js$/i.test(filePath)) return filePath;
+    const stat = fs.statSync(filePath);
+    if (!stat.isFile() || stat.size > MAX_SHIM_BYTES) return null;
+    const text = fs.readFileSync(filePath, 'utf8');
+    const shimJs = codexJsFromShim(filePath);
+    if (shimJs && /(?:@openai[\\/]+codex|node_modules[\\/]+@openai[\\/]+codex)[\\/]+bin[\\/]+codex\.js/i.test(text)) return shimJs;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function hasPathSeparator(value) {
+  return path.isAbsolute(value) || value.includes(path.sep) || value.includes('/') || value.includes('\\');
+}
+
+function resolvePathCandidate(value) {
+  if (/\.(?:c?js|mjs)$/i.test(value)) return { command: process.execPath, argsPrefix: [value] };
+  const shimJs = readShimTarget(value);
+  if (shimJs) return { command: process.execPath, argsPrefix: [shimJs] };
+  return { command: value, argsPrefix: [] };
+}
+
+function whereCandidates(value) {
+  const where = spawnSync('where.exe', [value], {
+    encoding: 'utf8',
+    timeout: WHERE_TIMEOUT_MS,
+    windowsHide: true
+  });
+  return String(where.stdout || '').split(/\r?\n/).map(line => line.trim()).filter(Boolean);
+}
+
+function resolveFromPath(value) {
+  const seen = new Set();
+  for (const candidate of whereCandidates(value)) {
+    if (seen.has(candidate)) continue;
+    seen.add(candidate);
+    const resolved = resolvePathCandidate(candidate);
+    if (resolved.command !== candidate || fs.existsSync(candidate)) return resolved;
+  }
+  return null;
+}
+
+function resolveWindowsCodexLauncher(spec) {
+  const value = String(spec || '').trim() || 'codex';
+  if (hasPathSeparator(value)) return resolvePathCandidate(value);
+
+  const pathResolved = resolveFromPath(value);
+  if (pathResolved) return pathResolved;
+
+  return resolvePathCandidate(value);
+}
+
+export function resolveCodexLauncher(spec = 'codex') {
+  const value = String(spec || '').trim() || 'codex';
+  if (/\.(?:c?js|mjs)$/i.test(value)) return { command: process.execPath, argsPrefix: [value] };
+  if (process.platform === 'win32') return resolveWindowsCodexLauncher(value);
+  return { command: value, argsPrefix: [] };
+}

package/src/orchestrator.js

@@ -220,8 +220,28 @@ function deriveRunLabel(label, taskText) {
   return truncateDisplayWidth(cleaned, MAX_DERIVED_LABEL_DISPLAY_WIDTH) || 'task';
 }
 
+function normalizePlanApprovalGate(value = false) {
+  const required = !!value;
+  return { required, approved: !required, approvedAt: null, approvedBy: null };
+}
+
+function planApprovalGate(state) {
+  return state?.gates?.planApproval || { required: false, approved: true, approvedAt: null, approvedBy: null };
+}
+
+function requiresPlanApproval(state) {
+  const gate = planApprovalGate(state);
+  return !!gate.required && !gate.approved;
+}
 
-export async function createRun({ label = '', taskText = '', workspace = '', repo = DEFAULT_REPO, maxParallel = 3, workerSandbox = 'workspace-write' } = {}) {
+function approvePlanGate(state, approvedBy = 'local-user') {
+  const gate = planApprovalGate(state);
+  if (!gate.required || gate.approved) return false;
+  state.gates = { ...(state.gates || {}), planApproval: { ...gate, approved: true, approvedAt: nowIso(), approvedBy } };
+  return true;
+}
+
+export async function createRun({ label = '', taskText = '', workspace = '', repo = DEFAULT_REPO, maxParallel = 3, workerSandbox = 'workspace-write', planApproval = false, requiresPlanApproval = false } = {}) {
   const resolvedWorkspace = await assertWorkspacePath(workspace || repo || DEFAULT_WORKSPACE);
   const workspaceMeta = await detectWorkspaceMetadata(resolvedWorkspace);
   const runLabel = deriveRunLabel(label, taskText);
@@ -243,6 +263,7 @@ export async function createRun({ label = '', taskText = '', workspace = '', rep
     repo: resolvedWorkspace,
     maxParallel: Number(maxParallel) || 3,
     workerSandbox: normalizeSandbox(workerSandbox),
+    gates: { planApproval: normalizePlanApprovalGate(planApproval || requiresPlanApproval) },
     runner: RUNNER,
     status: 'created', createdAt: nowIso(), updatedAt: nowIso(),
     planner: { status: 'pending' }, batches: [], tasks: [], judge: { status: 'pending' }
@@ -580,6 +601,7 @@ export async function dispatchRun(runId) {
     if (!state.tasks?.length) throw new Error('no tasks in plan');
     if (state.status === 'batch_blocked') throw new Error('current batch is blocked by failed/unknown tasks');
     if (allBatchesCompleted(state)) throw new Error('all batches completed; run final judge next');
+    approvePlanGate(state);
     state.status = 'running';
     await scheduleMoreWorkers(state);
     recomputeRunStatus(state);
@@ -816,6 +838,7 @@ export async function autoAdvanceRun(runId, { appClient = null, startCreated = f
     return await refreshRun(runId, appClient) || state;
   }
   if (state.status === 'planned') {
+    if (requiresPlanApproval(state)) return state;
     try { state = await dispatchRun(runId); }
     catch (error) { if (!/all batches completed|current batch is blocked/i.test(error.message || '')) throw error; }
     return await refreshRun(runId, appClient) || state;
@@ -1048,6 +1071,8 @@ async function retryTasksInState(state, taskIds = null, { auto = false, maxRetri
   if (!tasksToRetry.length) return { retried: [], state };
   for (const task of tasksToRetry) {
     if (hasLiveRunnerProcess(state, task.id, task)) throw new Error(`task still has a live process: ${task.id}`);
+  }
+  for (const task of tasksToRetry) {
     const batch = (state.batches || []).find(item => item.id === task.batchId);
     task.retryReason = reason;
     await rotateWorkerAttempt(state, task);
@@ -1228,7 +1253,7 @@ export function summaryOfRun(s) {
   const tasks = s.tasks || [];
   const workspacePath = s.workspacePath || s.repo || '';
   const git = s.git || s.workspace?.git || null;
-  return { runId: s.runId, label: s.label, repo: s.repo || workspacePath, workspacePath, workspaceName: s.workspaceName || path.basename(workspacePath || ''), git, status: s.status, runner: s.runner || RUNNER, workerSandbox: s.workerSandbox || 'workspace-write', archived: !!s.archived, createdAt: s.createdAt, updatedAt: s.updatedAt, durationEnd: runDurationEndOfState(s), 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 || workspacePath, workspacePath, workspaceName: s.workspaceName || path.basename(workspacePath || ''), git, status: s.status, runner: s.runner || RUNNER, workerSandbox: s.workerSandbox || 'workspace-write', gates: s.gates || {}, archived: !!s.archived, createdAt: s.createdAt, updatedAt: s.updatedAt, durationEnd: runDurationEndOfState(s), 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 })) };
 }
 
 export async function readRunTaskText(runId) {

package/src/runners/headlessRunner.js

@@ -2,6 +2,7 @@ import { spawn } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { CODEX_BIN } from '../utils.js';
+import { resolveCodexLauncher } from '../codexLauncher.js';
 
 function processKey(runId, taskId) {
   return `${runId}:${taskId}`;
@@ -47,18 +48,34 @@ export function createHeadlessRunner({ codexBin = CODEX_BIN } = {}) {
     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'] });
+    const { command, argsPrefix } = resolveCodexLauncher(codexBin);
+    const child = spawn(command, [...argsPrefix, ...args], { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
     captureEventsWithTimestamps(child.stdout, events, timedEvents);
     child.stderr.pipe(fs.createWriteStream(stderr, { flags: 'a' }));
     const key = processKey(runId, taskId);
-    runningProcesses.set(key, child);
-    child.on('exit', code => {
+    const listeners = [];
+    let exited = false;
+    let exitCode = null;
+    const finish = code => {
+      if (exited) return;
+      exited = true;
+      exitCode = code;
       try { fs.writeFileSync(path.join(outDir, 'exit_code'), String(code)); } catch {}
       runningProcesses.delete(key);
+      for (const listener of listeners) listener(code);
+    };
+    runningProcesses.set(key, child);
+    child.on('error', error => {
+      try { fs.appendFileSync(stderr, `${error.message || String(error)}\n`); } catch {}
+      finish(error?.code === 'ENOENT' ? 127 : 1);
     });
+    child.on('exit', code => finish(code));
     return {
-      pid: child.pid,
-      onExit(listener) { child.on('exit', listener); },
+      pid: child.pid ?? null,
+      onExit(listener) {
+        if (exited) listener(exitCode);
+        else listeners.push(listener);
+      },
       stop(signal = 'TERM') { child.kill(signal); }
     };
   }

package/src/runners/tmuxRunner.js

@@ -8,6 +8,7 @@ import {
   readTextMaybe,
   writeJsonAtomic
 } from '../utils.js';
+import { resolveCodexLauncher } from '../codexLauncher.js';
 import {
   DEFAULT_TMUX_BIN,
   sanitizeTmuxSessionName,
@@ -44,6 +45,10 @@ function shellQuote(value) {
   return `'${String(value).replace(/'/g, `'\\''`)}'`;
 }
 
+function bashArrayAssignment(name, values) {
+  return `${name}=(${values.map(value => shellQuote(value)).join(' ')})`;
+}
+
 const BIN_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../bin');
 const FORMATTER_BIN = path.join(BIN_DIR, 'input-kanban-format-events.js');
 const TIMESTAMP_BIN = path.join(BIN_DIR, 'input-kanban-timestamp-events.js');
@@ -55,11 +60,12 @@ function buildOverviewCommand(runStatePath) {
   return `while true; do clear; node ${quotedOverviewBin} ${quotedStatePath}; sleep 2; done`;
 }
 
-function buildRunScript({ codexBin, formatterBin = FORMATTER_BIN, timestampBin = TIMESTAMP_BIN, sandbox, cwd, outDir, runId, taskId, role }) {
+function buildRunScript({ codexCommand, codexArgsPrefix = [], formatterBin = FORMATTER_BIN, timestampBin = TIMESTAMP_BIN, sandbox, cwd, outDir, runId, taskId, role }) {
+  const codexLauncher = bashArrayAssignment('CODEX_LAUNCHER', [codexCommand, ...codexArgsPrefix]);
   return `#!/usr/bin/env bash
 set -u
 
-CODEX_BIN=${shellQuote(codexBin)}
+${codexLauncher}
 SANDBOX=${shellQuote(sandbox)}
 CWD=${shellQuote(cwd)}
 OUT_DIR=${shellQuote(outDir)}
@@ -78,7 +84,7 @@ EXIT_CODE="$OUT_DIR/exit_code"
 cd "$CWD"
 rm -f "$EXIT_CODE"
 touch "$EVENTS" "$TIMED_EVENTS" "$STDERR_LOG"
-"$CODEX_BIN" exec --json --sandbox "$SANDBOX" -C "$CWD" -o "$LAST_MESSAGE" "$(<"$PROMPT_FILE")" > >(node "$TIMESTAMP_BIN" "$EVENTS" "$TIMED_EVENTS" | node "$FORMATTER_BIN") 2> >(tee -a "$STDERR_LOG" >&2)
+"\${CODEX_LAUNCHER[@]}" exec --json --sandbox "$SANDBOX" -C "$CWD" -o "$LAST_MESSAGE" "$(<"$PROMPT_FILE")" > >(node "$TIMESTAMP_BIN" "$EVENTS" "$TIMED_EVENTS" | node "$FORMATTER_BIN") 2> >(tee -a "$STDERR_LOG" >&2)
 code=$?
 printf '%s' "$code" > "$EXIT_CODE"
 printf '\\nInput Kanban tmux task completed.\\n'
@@ -113,7 +119,8 @@ export function createTmuxRunner({
     const startedAt = nowIso();
 
     await fsp.writeFile(promptFile, prompt);
-    await fsp.writeFile(runScript, buildRunScript({ codexBin, sandbox, cwd, outDir, runId, taskId, role }));
+    const { command: codexCommand, argsPrefix: codexArgsPrefix } = resolveCodexLauncher(codexBin);
+    await fsp.writeFile(runScript, buildRunScript({ codexCommand, codexArgsPrefix, sandbox, cwd, outDir, runId, taskId, role }));
     await fsp.chmod(runScript, 0o755);
 
     const metadata = {

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_WORKSPACE, DEFAULT_REPO, PACKAGE_VERSION, RUNNER, RUNS_DIR } from './utils.js';
+import { APP_ROOT, CODEX_BIN, DEFAULT_WORKSPACE, DEFAULT_REPO, PACKAGE_VERSION, RUNNER, RUNS_DIR, detectCodexInfo } from './utils.js';
 import { createRun, listRuns, startPlanner, dispatchRun, startJudge, refreshRun, readRunFile, readRunTaskText, markTaskCompleted, stopRun, archiveRun, renameRun, retryRun } from './orchestrator.js';
 import { startAutoScheduler } from './scheduler.js';
 
@@ -43,7 +43,10 @@ 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, version: PACKAGE_VERSION, appRoot: APP_ROOT, runsDir: RUNS_DIR, defaultWorkspace: DEFAULT_WORKSPACE, defaultRepo: DEFAULT_REPO, runner: RUNNER });
+      return send(res, 200, { ok: true, version: PACKAGE_VERSION, appRoot: APP_ROOT, runsDir: RUNS_DIR, defaultWorkspace: DEFAULT_WORKSPACE, defaultRepo: DEFAULT_REPO, runner: RUNNER, codexBin: CODEX_BIN });
+    }
+    if (req.method === 'GET' && url.pathname === '/api/codex') {
+      return send(res, 200, { ok: true, codex: await detectCodexInfo() });
     }
     if (parts[1] === 'runs' && parts.length === 2) {
       if (req.method === 'GET') return send(res, 200, { runs: await listRuns({ includeArchived: url.searchParams.get('includeArchived') === '1', workspace: url.searchParams.get('workspace') || '' }) });

package/src/utils.js

@@ -3,9 +3,13 @@ import fsp from 'node:fs/promises';
 import path from 'node:path';
 import crypto from 'node:crypto';
 import { createRequire } from 'node:module';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
 import { fileURLToPath } from 'node:url';
+import { resolveCodexLauncher } from './codexLauncher.js';
 
 const require = createRequire(import.meta.url);
+const execFileAsync = promisify(execFile);
 const { version: PACKAGE_VERSION } = require('../package.json');
 
 export const APP_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
@@ -14,6 +18,8 @@ export const DEFAULT_WORKSPACE = path.resolve(process.env.KANBAN_DEFAULT_WORKSPA
 export const DEFAULT_REPO = DEFAULT_WORKSPACE;
 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 CODEX_NPM_PACKAGE = '@openai/codex';
+export const CODEX_CHECK_LATEST = process.env.KANBAN_CODEX_CHECK_LATEST === '1';
 export const VALID_RUNNERS = ['headless', 'tmux'];
 
 export function normalizeRunner(value = 'headless', source = 'KANBAN_RUNNER') {
@@ -44,6 +50,48 @@ export async function fileInfo(file) {
   try { const st = await fsp.stat(file); return { exists: true, size: st.size, mtimeMs: st.mtimeMs, mtime: st.mtime.toISOString() }; }
   catch { return { exists: false }; }
 }
+
+function parseCodexVersion(output) {
+  const text = String(output || '').trim();
+  const match = text.match(/(\d+\.\d+\.\d+)/);
+  return match ? match[1] : text || null;
+}
+
+export async function detectCodexInfo(codexBin = CODEX_BIN, { checkLatest = CODEX_CHECK_LATEST } = {}) {
+  const info = {
+    command: codexBin,
+    packageName: CODEX_NPM_PACKAGE,
+    installCommand: `npm install -g ${CODEX_NPM_PACKAGE}`,
+    updateCommand: `npm install -g ${CODEX_NPM_PACKAGE}`,
+    installed: false,
+    installedVersion: null,
+    latestVersion: null,
+    updateAvailable: false,
+    versionText: '',
+    installHint: '',
+    latestCheckEnabled: !!checkLatest
+  };
+  try {
+    const { command, argsPrefix } = resolveCodexLauncher(codexBin);
+    const { stdout } = await execFileAsync(command, [...argsPrefix, '--version'], { timeout: 5000, windowsHide: true });
+    const text = String(stdout || '').trim();
+    info.installed = true;
+    info.versionText = text;
+    info.installedVersion = parseCodexVersion(text);
+  } catch (error) {
+    info.installHint = error?.code === 'ENOENT' ? 'codex command not found' : (error?.message || String(error));
+  }
+  if (checkLatest) {
+    try {
+      const { stdout } = await execFileAsync('npm', ['view', CODEX_NPM_PACKAGE, 'version', '--json'], { timeout: 5000, windowsHide: true });
+      const parsed = JSON.parse(String(stdout || '').trim());
+      const latest = Array.isArray(parsed) ? parsed.at(-1) : parsed;
+      if (typeof latest === 'string' && latest.trim()) info.latestVersion = latest.trim();
+    } catch {}
+  }
+  info.updateAvailable = !!(info.installedVersion && info.latestVersion && info.installedVersion !== info.latestVersion);
+  return info;
+}
 export async function readTextMaybe(file, maxBytes=200000) {
   try {
     const st = await fsp.stat(file);