input-kanban 0.0.10 → 0.0.13

package/ENVIRONMENT.md

@@ -43,6 +43,7 @@ input-kanban \
 - `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.
 - `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.
 - tmux mode uses one session per run and one window for planner, each batch, and judge. Batch windows contain an overview pane plus worker panes.
 - tmux role windows stay open after the Codex command exits. The runner writes `exit_code` before entering the keep-open shell so Node.js status refresh can continue to advance from filesystem state.
 - The dashboard exposes the run-level `tmux attach-session` copy action after tmux metadata is available. File viewer panels do not repeat tmux terminal details.

package/README.en.md

@@ -117,6 +117,8 @@ Defaults:
 
 tmux mode still leaves batch barriers, `maxParallel`, final judge sequencing, and `judge_input.json` generation in Node.js. Each role output directory gets `run.sh` and `tmux.json`; status continues to be driven by `events.jsonl`, `stderr.log`, `last_message.md`, `exit_code`, and existing artifact files. After a tmux role command finishes, it writes `exit_code` first and then keeps the window open for inspection; the user closes the window manually from tmux.
 
+If you are using `--runner tmux`, stopping and restarting `input-kanban serve` does not interrupt Codex sessions that are already running; the tmux session keeps going, and the scheduler resumes orchestration after the server comes back. With the `headless` runner, do not assume that restarting the service is safe for in-flight child processes.
+
 tmux mode is optional and intended for live terminal viewing of each Codex role. `codex exec` is currently non-interactive and does not normally show manual approval prompts; if you select `danger-full-access` when creating a run, you explicitly relax the worker sandbox and should only do so in a controlled test workspace.
 
 After run-level tmux metadata is available, the dashboard shows `Copy tmux attach command`. The file viewer no longer repeats tmux terminal details; use the run detail header to copy the attach command and inspect the tmux session.

package/README.md

@@ -117,6 +117,8 @@ input-kanban --open
 
 tmux 模式仍由 Node.js 负责 batch barrier、`maxParallel`、final judge 顺序和 `judge_input.json` 生成。每个角色输出目录会写入 `run.sh` 和 `tmux.json`，状态继续由 `events.jsonl`、`stderr.log`、`last_message.md`、`exit_code` 和既有 artifact 文件驱动。tmux 角色命令完成后会先写入 `exit_code`，再保留 window，方便查看现场；需要关闭时由用户在 tmux 里手动退出。
 
+如果当前使用的是 `--runner tmux`，中断并重新启动 `input-kanban serve` 不会中断正在执行中的 Codex 会话；tmux session 会继续运行，服务重启后 scheduler 会重新接管后续推进。若使用 `headless` runner，则不应假设服务重启对正在运行的子进程是安全的。
+
 tmux 模式是可选能力，主要用于在终端里实时查看每个 Codex 角色的执行过程。`codex exec` 当前属于非交互模式，默认不会弹出人工 approval；如果创建任务时选择 `danger-full-access`，表示显式放开 worker sandbox 限制，应只在受控测试工作区中使用。
 
 看板会在 run 生成 tmux 元数据后显示 `复制tmux attach指令`。文件查看区域不再重复展示 tmux 终端信息；如需查看现场，请从批次详情顶部复制 attach 指令进入 tmux session。

package/RELEASE_NOTES.md

@@ -1,5 +1,51 @@
 # Release Notes
 
+## 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
+
+- Fix Windows startup/static serving by resolving `APP_ROOT` with `fileURLToPath(import.meta.url)` instead of URL pathname parsing.
+- Add a regression test for serving `/` and `/api/health` from the HTTP server.
+- Add task-detail hover guidance for sandbox and network capability issues, clarifying that sandbox-denied errors are not necessarily task failures.
+- Remember the last selected Web worker sandbox mode in browser local storage, so users do not need to reselect `danger-full-access` or other modes each time.
+- Auto-scroll the execution process view to the end when opened, while preserving the user's scroll position during refresh if they have scrolled upward.
+
+### Verification
+
+- `npm run check` passed with 64 tests.
+- `npm pack --dry-run` passed before release prep.
+
+## v0.0.11
+
+### Highlights
+
+- Simplify the Web sidebar header: show `任务批次` as the section title with a compact `新建` action on the right, removing repeated wording.
+- Document safe `input-kanban serve` restarts for `tmux` runner: already-running Codex sessions in tmux continue while the server is down, and the scheduler resumes after restart.
+- Clarify that `headless` runner does not provide the same safe-restart guarantee for in-flight child processes.
+
+### Verification
+
+- `npm run check` passed with 63 tests.
+- `npm pack --dry-run` passed before release prep.
+
 ## v0.0.10
 
 ### Highlights

package/bin/input-kanban.js

@@ -509,7 +509,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) {

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "input-kanban",
-  "version": "0.0.10",
+  "version": "0.0.13",
   "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%; }
@@ -60,12 +69,14 @@
     .muted { color: var(--muted); font-size: 12px; }
     .hidden { display: none; }
     .toolbar { margin: 8px 0 12px; display: flex; flex-wrap: wrap; gap: 4px; align-items: center; }
+    .section-header { display: flex; align-items: center; justify-content: space-between; gap: 10px; margin: 10px 0 8px; }
+    .section-header h2 { margin: 0; }
     .workspace-filter-panel { margin: 4px 0 10px; display: flex; align-items: center; gap: 6px; }
     .workspace-filter-select { flex: 1 1 auto; min-width: 0; font-size: 12px; padding: 7px 9px; color: #cbd5e1; }
     .task-text { max-height: 180px; color: #cbd5e1; }
     .empty { color: var(--muted); padding: 18px 0; }
-    .runs-load-icon { flex: 0 0 auto; display: inline-flex; align-items: center; justify-content: center; width: 14px; height: 14px; border: 1px solid var(--line); border-radius: 999px; color: var(--muted); font-size: 10px; cursor: help; opacity: .72; }
-    .runs-load-icon:hover { opacity: 1; color: #cbd5e1; border-color: var(--line-strong); }
+    .info-icon, .runs-load-icon { flex: 0 0 auto; display: inline-flex; align-items: center; justify-content: center; width: 14px; height: 14px; border: 1px solid var(--line); border-radius: 999px; color: var(--muted); font-size: 10px; cursor: help; opacity: .72; }
+    .info-icon:hover, .runs-load-icon:hover { opacity: 1; color: #cbd5e1; border-color: var(--line-strong); }
     .run-list { display: flex; flex-direction: column; gap: 10px; flex: 1; min-height: 0; overflow-y: auto; padding-right: 4px; }
     .run-list-more { width: 100%; margin-top: 4px; }
     .run-card { border: 1px solid var(--line); border-radius: 12px; padding: 12px; background: var(--panel-2); cursor: pointer; transition: border-color .15s, transform .15s, background .15s; }
@@ -115,6 +126,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; }
@@ -131,10 +145,10 @@
 <main>
   <div class="sidebar">
     <section>
-      <div class="toolbar">
-        <button onclick="showCreateForm()">新建任务批次</button>
+      <div class="section-header">
+        <h2>任务批次</h2>
+        <button class="secondary" onclick="showCreateForm()">新建</button>
       </div>
-      <h2>任务批次</h2>
       <div class="workspace-filter-panel">
         <select id="workspaceFilterSelect" class="workspace-filter-select" onchange="setWorkspaceFilter(this.value)" title="未筛选工作区"></select>
         <span id="runsLoadHint" class="runs-load-icon" title="批次列表尚未加载" aria-label="批次列表尚未加载">ⓘ</span>
@@ -154,7 +168,7 @@
         <option value="read-only">read-only（只读）</option>
         <option value="danger-full-access">danger-full-access（高风险，跳过沙箱限制）</option>
       </select>
-      <div class="muted">仅影响 worker；任务拆分和汇总验收仍保持 read-only。</div>
+      <div class="muted">仅影响 worker；任务拆分和汇总验收仍保持 read-only。若执行过程提示 Permission denied / sandbox denied，这通常不是任务本身失败，而是当前沙箱能力不足；在可信工作区可改用 danger-full-access。DNS / 网络失败则通常需要检查代理、VPN 或本地 evidence。</div>
       <label>任务说明</label><textarea id="taskText" placeholder="粘贴任务说明"></textarea>
       <div class="toolbar">
         <button onclick="createRun()">创建批次</button>
@@ -168,14 +182,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>
@@ -183,7 +190,10 @@
     </section>
 
     <section id="filePanel" class="log-panel">
-      <h2>任务详情</h2>
+      <div class="section-header">
+        <h2>任务详情</h2>
+        <span class="info-icon" title="若执行过程提示 Permission denied / sandbox denied，这通常不是任务本身失败，而是当前 worker 沙箱能力不足；在可信工作区可改用 danger-full-access。DNS / 网络失败则通常需要检查代理、VPN 或本地 evidence。" aria-label="任务详情权限与网络提示">ⓘ</span>
+      </div>
       <div id="fileTitle" class="muted">点击任务后查看详情</div>
       <div id="fileTabs" class="toolbar file-tabs"></div>
       <div id="executionSummary" class="execution-summary hidden"></div>
@@ -194,7 +204,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>
@@ -214,6 +224,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;
@@ -223,6 +234,8 @@ const statusByRunId = new Map();
 const AUTO_REFRESH_MS = 3000;
 const RUN_LIST_PAGE_SIZE = 10;
 const WORKSPACE_FILTER_ALL = '';
+const WORKER_SANDBOX_STORAGE_KEY = 'input-kanban.workerSandbox';
+const VALID_WORKER_SANDBOXES = new Set(['read-only', 'workspace-write', 'danger-full-access']);
 let currentWorkspacePath = '';
 let selectedWorkspaceFilter = localStorage.getItem('input-kanban.workspaceFilter') || WORKSPACE_FILTER_ALL;
 
@@ -349,6 +362,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();
@@ -361,7 +393,20 @@ function hideCreateForm() {
   document.getElementById('detailPanel').classList.remove('hidden');
   document.getElementById('filePanel').classList.remove('hidden');
 }
+function saveWorkerSandboxPreference() {
+  const select = document.getElementById('workerSandbox');
+  const value = select?.value || '';
+  if (VALID_WORKER_SANDBOXES.has(value)) localStorage.setItem(WORKER_SANDBOX_STORAGE_KEY, value);
+}
+function initializeWorkerSandboxPreference() {
+  const select = document.getElementById('workerSandbox');
+  if (!select) return;
+  const saved = localStorage.getItem(WORKER_SANDBOX_STORAGE_KEY);
+  if (VALID_WORKER_SANDBOXES.has(saved)) select.value = saved;
+  select.addEventListener('change', saveWorkerSandboxPreference);
+}
 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 r = await api('/api/runs', { method: 'POST', body: JSON.stringify(body) });
   selectedRun = r.runId; selectedTask = null; selectedFileName = null;
@@ -466,6 +511,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();
@@ -511,6 +557,97 @@ 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' || status === 'batch_blocked') return { label: '执行', disabled: false, state: status === 'batch_blocked' ? '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;
@@ -559,7 +696,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 || '');
@@ -656,6 +794,7 @@ async function loadFile(name, { preserveScroll = false } = {}) {
   selectedFileName = name;
   const pre = document.getElementById('fileContent');
   const previousScrollTop = pre.scrollTop;
+  const wasAtBottom = pre.scrollHeight - pre.scrollTop - pre.clientHeight < 24;
   let text;
   const selected = taskById(selectedTask);
   if (name === 'result.json' && selected?.manualCompletion?.hasManualResult) {
@@ -665,7 +804,8 @@ async function loadFile(name, { preserveScroll = false } = {}) {
     text = await api(`/api/runs/${selectedRun}/tasks/${selectedTask}/file?name=${encodeURIComponent(name)}`);
   }
   pre.textContent = text;
-  if (preserveScroll) pre.scrollTop = previousScrollTop;
+  if (name === 'events.pretty' && (!preserveScroll || wasAtBottom)) pre.scrollTop = pre.scrollHeight;
+  else if (preserveScroll) pre.scrollTop = previousScrollTop;
   else pre.scrollTop = 0;
   if (name === 'events.pretty') await renderExecutionSummary();
   else hideExecutionSummary();
@@ -883,25 +1023,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;
@@ -924,7 +1059,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' })
@@ -964,16 +1099,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

@@ -1048,6 +1048,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);

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,16 +3,23 @@ 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(new URL(import.meta.url).pathname), '..');
+export const APP_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 export { PACKAGE_VERSION };
 export const DEFAULT_WORKSPACE = path.resolve(process.env.KANBAN_DEFAULT_WORKSPACE || process.env.KANBAN_DEFAULT_REPO || process.cwd());
 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') {
@@ -43,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);