input-kanban 0.0.8 → 0.0.10

package/ENVIRONMENT.md

@@ -8,16 +8,18 @@ CLI options take precedence over environment variables. Environment variables ta
 
 - `PORT`: HTTP server port. Default: `8787`. CLI option: `--port`.
 - `HOST`: HTTP bind host. Default: `127.0.0.1`. CLI option: `--host`.
-- `KANBAN_DEFAULT_REPO`: Default target repository path for new runs. Default: the current working directory when `input-kanban` is launched. CLI option: `--repo`. Creating a run validates that this path is inside a Git work tree.
+- `KANBAN_DEFAULT_WORKSPACE`: Default workspace path for new runs. Default: the current working directory when `input-kanban` is launched. CLI option: `--workspace`. `KANBAN_DEFAULT_REPO` remains as a compatibility alias. Creating a run only requires this path to exist and be a directory; Git is detected and marked when available.
 - `KANBAN_RUNS_DIR`: Directory for run state, logs, and artifacts. Default: `.input-kanban/runs` under the user's home directory. CLI option: `--runs-dir`.
 - `KANBAN_CODEX_BIN`: Codex CLI executable name or path. Default: `codex`. CLI option: `--codex-bin`.
 - `KANBAN_RUNNER`: Runner mode. Supported values: `headless`, `tmux`. Default: `headless`. CLI option: `--runner`.
+- `KANBAN_AUTO_POLL_MS`: Poll interval for the Web server background scheduler. Default: `3000`.
+- `KANBAN_AUTO_MAX_RETRIES`: Maximum automatic retries for recoverable failed/unknown tasks in the scheduler. Default: `1`.
 
 ## Environment Example
 
 ```bash
 PORT=8787 \
-KANBAN_DEFAULT_REPO=/path/to/child-repo \
+KANBAN_DEFAULT_WORKSPACE=/path/to/workspace \
 KANBAN_RUNS_DIR=/path/to/kanban-runs \
 KANBAN_CODEX_BIN=codex \
 KANBAN_RUNNER=headless \
@@ -29,7 +31,7 @@ input-kanban
 ```bash
 input-kanban \
   --port 8787 \
-  --repo /path/to/child-repo \
+  --workspace /path/to/workspace \
   --runs-dir /path/to/kanban-runs \
   --codex-bin codex \
   --runner headless
@@ -37,7 +39,8 @@ input-kanban \
 
 ## Notes
 
-- `KANBAN_DEFAULT_REPO` / `--repo` should point to the actual git repository where work should run.
+- `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.
 - `KANBAN_RUNNER` / `--runner tmux` runs Codex tasks inside tmux windows while keeping scheduling and status tracking in the Node.js orchestrator.
 - `KANBAN_RUNNER=tmux` is optional. Use it when you want live terminal visibility into planner, worker, and final judge sessions.
 - tmux mode uses one session per run and one window for planner, each batch, and judge. Batch windows contain an overview pane plus worker panes.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zhang3xing1
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PROJECT_GUIDE.md

@@ -33,9 +33,9 @@ The intended use case is:
 
 ## Important Boundaries
 
-- If the current workspace is a multi-repo umbrella, the target repo must be a concrete child repository, not the umbrella root.
-- Workers can modify the target repository. Failed workers are not automatically retried because a partial modification may already exist.
-- The planner only creates a plan and does not modify the target repo. Planner failures, invalid output, and empty plans can be safely retried before any worker or judge starts.
+- If the current workspace is a multi-repo umbrella, the target workspace must be a concrete child directory, not the umbrella root.
+- Workers can modify the target workspace. Failed workers are not automatically retried because a partial modification may already exist.
+- The planner only creates a plan and does not modify the target workspace. Planner failures, invalid output, and empty plans can be safely retried before any worker or judge starts.
 - Local process state, `exit_code`, logs, and artifacts are the source of truth. Codex App Server session lookup is auxiliary.
 - tmux mode changes terminal visibility only. Node.js still owns scheduling, batch barriers, `maxParallel`, stop/archive, `judge_input.json`, and status refresh from `exit_code` plus artifacts.
 - tmux windows stay open after command completion for human inspection, but `exit_code` is written before the keep-open shell starts so state can advance without closing the window.
@@ -58,6 +58,7 @@ Supported serve options:
 ```text
 --host <host>
 --port <port>
+--workspace <path>
 --repo <path>
 --runs-dir <path>
 --codex-bin <path>
@@ -87,6 +88,19 @@ Supported result options:
 
 `input-kanban result [runId]` prints the final judge result. It prefers `judge/verdict.json` and falls back to `judge/last_message.md`. If no `runId` is provided, it uses the latest run. `--copy` sends the result to the system clipboard.
 
+Supported retry options:
+
+```text
+<runId>
+[taskId]
+--runs-dir <path>
+--reason <text>
+--max-retries <n>
+--json
+```
+
+`input-kanban retry <runId> [taskId]` retries failed or unknown worker tasks. If `taskId` is omitted, it retries failed/unknown tasks in the current blocked batch. Before retrying, the worker output directory is moved under `worker_attempts/<taskId>/attempt-XX/` so failed logs, stderr, exit code, and last message remain available for audit. Retry resets the task to `pending`, records retry history, then reuses the existing scheduler.
+
 Supported stop options:
 
 ```text
@@ -100,6 +114,7 @@ Supported stop options:
 Supported submit options:
 
 ```text
+--workspace <path>
 --repo <path>
 --label <label>
 --task <text>
@@ -115,16 +130,48 @@ 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 `--repo` uses the current working directory as the target Git work tree. 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, 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 auto loop and lets the submitting terminal return immediately. 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. `--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`.
 
 Default behavior:
 
-- default repo: current working directory when `input-kanban` is launched; run creation validates that the selected repo is inside a Git work tree;
+- default workspace: current working directory when `input-kanban` is launched; run creation only validates that the selected directory exists and is a directory; Git is detected and labeled when available;
 - default host: `127.0.0.1`;
 - default port: `8787`;
 - default runs directory: `~/.input-kanban/runs`;
 - default Codex binary: `codex`.
 
+## Agent Workflow
+
+This project already exposes an agent-friendly CLI path. Use `--json` for machine-readable output and `runs --active` to discover current work before asking for per-run details.
+
+Discovery / lookup pattern:
+
+```text
+input-kanban --json runs --active
+input-kanban --json status <runId>
+input-kanban --json result <runId>
+input-kanban --json stop <runId>
+```
+
+Key points:
+
+- `runs` lists visible batches from the shared runs directory; `--active` filters to runs that have not reached a terminal state or still have running tasks.
+- `status` resolves a single run by id and defaults to the latest run when the id is omitted.
+- `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.
+
+Example agent loop:
+
+```text
+1. input-kanban --json runs --active
+2. input-kanban --json status <runId>
+3. input-kanban --json result <runId>
+4. input-kanban --json stop <runId>   # only when necessary
+```
+
 ## Data Model
 
 ### Run
@@ -190,18 +237,81 @@ If the planner returns valid JSON with zero tasks, the run is marked `plan_empty
 
 ## Worker Failure Policy
 
-Workers are not automatically retried.
+Failed or unknown workers can be retried explicitly with `input-kanban retry <runId> [taskId]` or via Web/API retry. CLI/Web auto mode may retry a blocked batch once by default.
+
+Retry rules:
 
-Reason: a worker may have already changed files in the target repository. Retrying could duplicate edits, overwrite partial work, or create conflicts.
+- Retry is an orchestrator-level state transition, not a runner auto-restart.
+- Retry refuses stopped or archived runs.
+- Retry refuses tasks that still have a live process.
+- Retry preserves failed output under `worker_attempts/<taskId>/attempt-XX/` before resetting the task.
+- Retry resets failed/unknown tasks to `pending`, records retry history, and reuses the existing scheduler.
 
-Recovery options:
+Recovery options after retries are exhausted:
 
-- Inspect `events.pretty`, `stderr.log`, `last_message.md`, and artifacts.
+- Inspect `events.pretty`, `stderr.log`, `last_message.md`, archived worker attempts, and artifacts.
 - Manually mark `failed` or `unknown` workers as completed if the user confirms the work is actually done.
 - Manual completion writes `workers/<taskId>/manual_completion.json`.
 - If the user pastes a manual success result, it is saved as `workers/<taskId>/manual_result.md` and included in final judge input.
 - The UI preserves the original failed or unknown status while also showing the manual completion marker.
 
+## Run State Concurrency and Retry Implementation Notes
+
+### Failure Retry
+
+Retry is implemented as an explicit orchestrator state transition.
+
+Implemented behavior:
+
+- `input-kanban retry <runId> [taskId]` retries either one failed/unknown task or, when `taskId` is omitted, failed/unknown tasks in the current blocked batch.
+- CLI/Web auto mode retries a `batch_blocked` run once by default via the same retry path.
+- Retry reuses the existing scheduler and does not trigger replanning.
+- Planner retry remains separate and only applies before any worker or judge starts.
+
+Safety requirements enforced by implementation:
+
+1. Refuse retry when the run is `stopped` or `archived`.
+2. Refuse retry if the target task still has a live process.
+3. Preserve the failed attempt directory under `worker_attempts/<taskId>/attempt-XX/` before resetting the task to `pending`.
+4. Reset the run back to `running` when there is pending retry work, then let the existing scheduler start workers naturally.
+5. Keep retry counters and history on the task so agents can tell transient noise from deterministic task failure.
+
+Why this shape was favored:
+
+- Runner-level auto-restart hides intent from the state machine and would have to be duplicated for headless/tmux.
+- Auto-replan is too heavy for a single failed worker and would throw away useful per-task evidence.
+- The retry decision belongs to orchestration, where agents and humans can see it explicitly.
+
+### `run_state.json` Concurrency Safety
+
+The backend now uses a per-run lock file to protect state writes. Atomic writes prevent partial files; the lock prevents common lost-update races between detach supervisors, CLI commands, and Web API actions.
+
+Implemented shape:
+
+- The lock file is `run_state.lock` inside the run directory.
+- Lock acquisition uses exclusive file creation and stores `pid`, `runId`, and timestamp in the lock file.
+- Stale locks can be recovered when the owning PID is gone and the lock is older than the stale threshold.
+- Lock granularity is one run, so different runs do not block each other.
+- State transition paths re-read the run inside the lock before mutating it.
+
+Write paths under lock include:
+
+- planner start and completion callback;
+- dispatch;
+- retry;
+- stop;
+- archive;
+- rename;
+- manual task completion;
+- judge start and completion callback;
+- refresh/recovery state materialization.
+
+Risk notes:
+
+- A stale-lock timeout that is too short can accidentally steal a lock from a slow or paused process; too long slows recovery.
+- `child.onExit` callbacks must continue to take the write lock.
+- If the workspace ever moves to shared network storage, the current single-machine exclusive-file assumptions should be re-evaluated.
+
 ## Stop and Archive
 
 ### Stop
@@ -307,6 +417,7 @@ runs/<runId>/plan.json
 runs/<runId>/planner/
 runs/<runId>/planner_attempts/attempt-XX/
 runs/<runId>/workers/<taskId>/
+runs/<runId>/worker_attempts/<taskId>/attempt-XX/
 runs/<runId>/judge/judge_input.json
 runs/<runId>/workers/<taskId>/events_timed.jsonl
 runs/<runId>/workers/<taskId>/manual_result.md
@@ -324,6 +435,7 @@ runs/<runId>/judge/verdict.json
 - `POST /api/runs/:runId/plan`
 - `POST /api/runs/:runId/dispatch`
 - `POST /api/runs/:runId/judge`
+- `POST /api/runs/:runId/retry`
 - `POST /api/runs/:runId/stop`
 - `POST /api/runs/:runId/archive`
 - `PATCH /api/runs/:runId/label`
@@ -390,13 +502,13 @@ change. Record the exact commands, run ids, and artifact paths in the release
 notes or handoff.
 
 1. Headless runner:
-   - Start the app with `input-kanban --runner headless --runs-dir <tmp-runs-dir> --repo <target-repo> --port <free-port>`.
+   - Start the app with `input-kanban --runner headless --runs-dir <tmp-runs-dir> --workspace <target-workspace> --port <free-port>`.
    - Create a small run, plan it, dispatch at least one worker, and run the final judge if the plan requires it.
    - Verify the run state reports `runner: headless`, no task exposes `tmux` metadata, and role directories contain the expected `prompt.md`, `events.jsonl`, `events_timed.jsonl`, `stderr.log`, `last_message.md`, and `exit_code` files.
    - Stop the run and verify no unrelated local process is affected.
 
 2. tmux runner, only when `tmux -V` succeeds:
-   - Start the app with `input-kanban --runner tmux --runs-dir <tmp-runs-dir> --repo <target-repo> --port <free-port>`.
+   - Start the app with `input-kanban --runner tmux --runs-dir <tmp-runs-dir> --workspace <target-workspace> --port <free-port>`.
    - Create a small run and click Plan. Verify a session named `input-kanban-<runId>` exists and has a planner window.
    - Dispatch workers. Verify each batch gets its own window with an overview pane plus worker panes, and each role directory writes `run.sh` and `tmux.json` with the expected `sessionName`, `windowName`, `target`, and `attachCommand`.
    - Verify `run.sh` writes `exit_code` before printing the keep-open summary, then keeps the window open for manual inspection.
@@ -417,7 +529,7 @@ Keep a single repository-level `RELEASE_NOTES.md` with recent version history. D
 ## Change Guidelines
 
 - Do not add automatic worker retry unless there is a verified rollback or idempotency mechanism.
-- Do not default to `--skip-git-repo-check`; prefer a concrete target child repository.
+- Do not default to bypassing workspace validation; prefer a concrete target child workspace.
 - Preserve batch barriers when modifying scheduling logic.
 - Decide clearly between soft archive and physical directory archive before changing archive semantics.
 - Keep the frontend buildless unless there is a strong reason to introduce a build pipeline.

package/README.en.md

@@ -2,7 +2,7 @@
 
 [中文](README.md) | English
 
-Input Kanban is a local Codex orchestration dashboard. The recommended path is to install it from npm, run `input-kanban` inside the target repository, and use the browser UI to manage planning, worker execution, and final judging.
+Input Kanban is a local Codex orchestration dashboard. The recommended path is to install it from npm, run `input-kanban` inside the target workspace, and use the browser UI to manage planning, worker execution, and final judging. If the workspace is a Git repository, the UI marks it as such.
 
 ## Recommended Usage
 
@@ -18,12 +18,12 @@ Verify the installation:
 input-kanban --help
 ```
 
-### 2. Start in the Target Repository
+### 2. Start in the Target Workspace
 
-Enter the repository you want Codex to modify or inspect:
+Enter the workspace you want Codex to modify or inspect:
 
 ```bash
-cd /path/to/your/repo
+cd /path/to/your/workspace
 input-kanban
 ```
 
@@ -35,14 +35,16 @@ http://127.0.0.1:8787
 
 Open that URL in your browser to use the dashboard.
 
-### 3. Start with an Explicit Repository
+### 3. Start with an Explicit Workspace
 
-If you do not want to `cd` into the target repository first, pass it explicitly:
+If you do not want to `cd` into the target workspace first, pass it explicitly:
 
 ```bash
-input-kanban --repo /path/to/your/repo
+input-kanban --workspace /path/to/your/workspace
 ```
 
+`--repo` remains available as a compatibility alias.
+
 ## CLI Auto Execution
 
 To submit a task from the terminal and let it advance automatically, use `submit`. Task content supports two input modes:
@@ -52,7 +54,9 @@ input-kanban submit --task-file task.md --label "Fix login issue"
 input-kanban submit --task "Fix the login issue and add regression tests" --label "Fix login issue"
 ```
 
-`submit` creates a run, starts planning, dispatches all batches, and starts the final judge after all workers finish by default. The default repo is the current directory. If `--label` is omitted, the run label is generated from the task text. It uses the same runs directory, so CLI-created runs are visible in the Web dashboard on port 8787 as long as the dashboard uses the same `--runs-dir`.
+`submit` creates a run, starts planning, dispatches all batches, and starts the final judge after all workers finish by default. The default workspace is the current directory. If `--label` is omitted, the run label is generated from the task text. It uses the same runs directory, so CLI-created runs are visible in the Web dashboard on port 8787 as long as the dashboard uses the same `--runs-dir`.
+
+`input-kanban serve` starts a lightweight background scheduler that keeps refreshing and advancing unfinished runs: it dispatches batches when a plan is ready, starts the next serial batch after the previous one completes, and starts the final judge after all batches complete. CLI `submit --auto` / `input-kanban auto <runId>` and the Web server share the same orchestrator auto-advance path, so progress no longer depends on whether a browser page is open or refreshed.
 
 To return immediately and let a background supervisor continue the auto loop, pass `-d` / `--detach`:
 
@@ -73,15 +77,21 @@ input-kanban submit --runs-dir ~/.input-kanban/runs --runner tmux -d
 Check and stop:
 
 ```bash
+input-kanban runs
+input-kanban --json runs --active
 input-kanban status
 input-kanban status --watch
 input-kanban status <runId> --watch
+input-kanban --json status <runId>
 input-kanban result
 input-kanban result <runId> --copy
+input-kanban --json result <runId>
+input-kanban retry <runId> [taskId]
+input-kanban --json retry <runId> [taskId]
 input-kanban stop <runId>
 ```
 
-Without a `runId`, `status` and `result` use the latest run by default. `result --copy` copies the final judge result. Stopping requires an explicit `runId` to avoid stopping the wrong run.
+Use `runs` to discover visible run batches first; `runs --active` shows only runs that have not reached a terminal state or still have running tasks, which lets an agent find `runId` values before calling `status <runId>`. To focus on one workspace, use `input-kanban runs --workspace /path/to/workspace`; the Web sidebar has the same workspace filter. Without a `runId`, `status` and `result` use the latest run by default. `result --copy` copies the final judge result. `retry` preserves the failed attempt and retries failed/unknown tasks. `--json` is handy for agents/scripts that need structured output. Stopping requires an explicit `runId` to avoid stopping the wrong run.
 
 ## Common Startup Options
 
@@ -96,7 +106,7 @@ input-kanban --open
 
 Defaults:
 
-- target repository: the current directory where `input-kanban` is launched; creating a run validates that it is inside a Git work tree
+- workspace: the current directory where `input-kanban` is launched; creating a run only requires an existing directory, and Git is shown as an optional capability when detected
 - host: `127.0.0.1`
 - port: `8787`
 - runs directory: `~/.input-kanban/runs`
@@ -107,20 +117,20 @@ 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.
 
-tmux mode is optional and intended for live terminal viewing of each Codex role. `codex exec` is currently non-interactive and does not normally show manual approval prompts; if you select `danger-full-access` when creating a run, you explicitly relax the worker sandbox and should only do so in a controlled test repository.
+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.
 
 ## Using the Dashboard
 
 1. Click `New Run`.
-2. Enter a label, target repository, worker sandbox, and task description.
+2. Enter a label, workspace, worker sandbox, and task description.
 3. Click `Create Run`.
 4. The dashboard automatically starts `Plan` so the Codex planner can generate batches and workers.
-5. Click `Dispatch` to run workers by batch barrier and concurrency limits.
-6. Inspect execution logs, final messages, error logs, and artifacts.
-7. After all batches complete, click `Final Judge`.
-8. Stop or archive a run when needed, or manually mark a confirmed failed/unknown worker as completed.
+5. After planning completes, Web auto mode dispatches workers by batch barrier and concurrency limits by default.
+6. After all batches complete, Web auto mode starts the final judge by default.
+7. Inspect execution logs, final messages, error logs, and artifacts.
+8. Stop or archive a run when needed, or manually click buttons to retry/advance, or manually mark a confirmed failed/unknown worker as completed.
 
 ## What It Is For
 
@@ -153,7 +163,7 @@ runs/<runId>/
     └── verdict.json
 ```
 
-These files are local run records and do not need to be committed to your application repository.
+These files are local run records and do not need to be committed to your application workspace.
 
 ## Requirements
 

package/README.md

@@ -2,7 +2,7 @@
 
 中文 | [English](README.en.md)
 
-Input Kanban 是一个本地 Codex 编排看板。推荐通过 npm 安装，然后在目标代码仓库里运行 `input-kanban`，用浏览器管理任务拆分、并发执行和最终验收。
+Input Kanban 是一个本地 Codex 编排看板。推荐通过 npm 安装，然后在目标工作区里运行 `input-kanban`，用浏览器管理任务拆分、并发执行和最终验收；如果工作区恰好是 Git 仓库，界面会额外标识出来。
 
 ## 推荐使用方式
 
@@ -18,12 +18,12 @@ npm install -g input-kanban
 input-kanban --help
 ```
 
-### 2. 在目标仓库启动
+### 2. 在目标工作区启动
 
-进入你希望 Codex 修改或检查的代码仓库：
+进入你希望 Codex 修改或检查的工作区：
 
 ```bash
-cd /path/to/your/repo
+cd /path/to/your/workspace
 input-kanban
 ```
 
@@ -35,14 +35,16 @@ http://127.0.0.1:8787
 
 打开浏览器访问这个地址即可使用看板。
 
-### 3. 指定目标仓库启动
+### 3. 指定目标工作区启动
 
-如果不想先 `cd` 到目标仓库，也可以显式指定：
+如果不想先 `cd` 到目标工作区，也可以显式指定：
 
 ```bash
-input-kanban --repo /path/to/your/repo
+input-kanban --workspace /path/to/your/workspace
 ```
 
+`--repo` 仍可作为兼容别名使用。
+
 ## CLI 自动执行
 
 如果希望从终端直接提交任务并自动推进，可以使用 `submit`。任务内容支持两种输入方式：
@@ -52,7 +54,9 @@ input-kanban submit --task-file task.md --label "修复登录问题"
 input-kanban submit --task "修复登录问题，并补充回归测试" --label "修复登录问题"
 ```
 
-`submit` 默认会创建任务批次、发起拆分、自动派发所有批次，并在全部完成后自动发起最终验收。默认 repo 是当前目录；如果不传 `--label`，任务批次名称会从任务内容自动生成。它使用同一个 runs 目录，所以只要 8787 Web 看板也使用相同的 `--runs-dir`，CLI 创建的任务会在 Web 界面里可见。
+`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 自动推进逻辑，因此任务推进不再依赖浏览器页面是否打开或刷新。
 
 如果希望提交后立即返回，让任务在后台自动执行，可以加 `-d` / `--detach`：
 
@@ -73,15 +77,21 @@ input-kanban submit --runs-dir ~/.input-kanban/runs --runner tmux -d
 查看和停止：
 
 ```bash
+input-kanban runs
+input-kanban --json runs --active
 input-kanban status
 input-kanban status --watch
 input-kanban status <runId> --watch
+input-kanban --json status <runId>
 input-kanban result
 input-kanban result <runId> --copy
+input-kanban --json result <runId>
+input-kanban retry <runId> [taskId]
+input-kanban --json retry <runId> [taskId]
 input-kanban stop <runId>
 ```
 
-不传 `runId` 时，`status` 和 `result` 默认查看最近一次任务批次。`result --copy` 会复制最终验收结果；停止任务请显式传入 `runId`，避免误停。
+`runs` 用来先列出可见任务批次，`runs --active` 只列出未进入终态或仍有子任务运行的批次，便于 agent 先发现 `runId`，再用 `status <runId>` 查详情。要只看某个工作区，可用 `input-kanban runs --workspace /path/to/workspace`；Web 左栏也提供了工作区筛选。不传 `runId` 时，`status` 和 `result` 默认查看最近一次任务批次。`result --copy` 会复制最终验收结果；`retry` 会保留失败现场并重试失败/未知任务；`--json` 适合给 agent/脚本做结构化读取；停止任务请显式传入 `runId`，避免误停。
 
 ## 常用启动参数
 
@@ -96,7 +106,7 @@ input-kanban --open
 
 默认值：
 
-- 目标仓库：启动 `input-kanban` 时的当前目录；创建批次时会校验它必须位于 Git work tree 内
+- 工作区：启动 `input-kanban` 时的当前目录；创建批次时只要求它是一个存在的目录，若检测到 Git 会额外显示 Git 标识
 - host：`127.0.0.1`
 - port：`8787`
 - runs 目录：`~/.input-kanban/runs`
@@ -107,20 +117,20 @@ 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 里手动退出。
 
-tmux 模式是可选能力，主要用于在终端里实时查看每个 Codex 角色的执行过程。`codex exec` 当前属于非交互模式，默认不会弹出人工 approval；如果创建任务时选择 `danger-full-access`，表示显式放开 worker sandbox 限制，应只在受控测试仓库中使用。
+tmux 模式是可选能力，主要用于在终端里实时查看每个 Codex 角色的执行过程。`codex exec` 当前属于非交互模式，默认不会弹出人工 approval；如果创建任务时选择 `danger-full-access`，表示显式放开 worker sandbox 限制，应只在受控测试工作区中使用。
 
 看板会在 run 生成 tmux 元数据后显示 `复制tmux attach指令`。文件查看区域不再重复展示 tmux 终端信息；如需查看现场，请从批次详情顶部复制 attach 指令进入 tmux session。
 
 ## 在看板里如何使用
 
 1. 点击 `新建任务批次`。
-2. 输入批次名称、目标仓库、Worker 沙箱和任务说明。
+2. 输入批次名称、工作区、Worker 沙箱和任务说明。
 3. 点击 `创建批次`。
 4. 看板会自动发起 `拆分任务`，让 Codex planner 生成 batches 和 workers。
-5. 点击 `派发执行`，按 batch barrier 和并发限制运行 workers。
-6. 查看执行日志、最终回复、错误日志和产物。
-7. 所有 batch 完成后，点击 `汇总验收`。
-8. 必要时可以停止或归档 run，也可以手动标记已确认完成的失败/未知 worker。
+5. 拆分完成后，Web 默认自动派发执行，按 batch barrier 和并发限制运行 workers。
+6. 所有 batch 完成后，Web 默认自动发起 `汇总验收`。
+7. 查看执行日志、最终回复、错误日志和产物。
+8. 必要时可以停止或归档 run，也可以手动点击按钮重试、推进，或手动标记已确认完成的失败/未知 worker。
 
 ## 它适合做什么
 
@@ -153,7 +163,7 @@ runs/<runId>/
     └── verdict.json
 ```
 
-这些文件是本地运行记录，不需要提交到你的业务仓库。
+这些文件是本地运行记录，不需要提交到你的业务工作区。
 
 ## 使用前提
 

package/RELEASE_NOTES.md

@@ -1,5 +1,40 @@
 # Release Notes
 
+## v0.0.10
+
+### Highlights
+
+- Adopt a workspace-first model: `workspace` / `--workspace` are now the primary identity for runs, while `repo` / `--repo` remain compatibility aliases.
+- Allow non-Git workspace directories and show Git only as an optional capability marker when detected.
+- Add workspace filtering to CLI/API/Web: `input-kanban runs --workspace <path>` and `/api/runs?workspace=<path>` filter runs by workspace.
+- Add a server-side background scheduler for `input-kanban serve` so unfinished runs continue to advance without relying on an open browser tab.
+- Share auto-advance logic between CLI `submit --auto` / `input-kanban auto <runId>` and the Web server scheduler through the orchestrator.
+- Make `/api/runs` lightweight by reading run summaries without refreshing every historical run, improving cold-start list loading.
+- Simplify the Web sidebar: workspace filtering is a compact dropdown, the redundant list refresh button is removed, list load timing is available via a small hover icon, and Git is shown as a simple marker.
+
+### Verification
+
+- `npm run check` passed with 62 tests.
+- `npm pack --dry-run` passed before publishing.
+
+## v0.0.9
+
+### Highlights
+
+- Add MIT license and include it in the published npm package.
+- Add agent-friendly `--json` output for discovery, status lookup, result reading, stop, submit, and auto commands.
+- Add `runs` / `runs --active` to list visible and active run IDs before querying details.
+- Add `retry <runId> [taskId]` with preserved failed attempts and a one-shot auto retry path for blocked batches.
+- Add per-run `run_state.lock` protection around state writes to reduce CLI/Web/supervisor lost-update races.
+- Keep Web auto mode enabled by default after planning: dispatch planned work and auto-start the final judge while the page is open.
+- Keep CLI auto mode enabled by default for `submit`, with `--no-auto` as the create-and-plan-only escape hatch.
+- Add `result --copy` for copying final judge output, and keep version display in both CLI and Web footer.
+
+### Verification
+
+- `npm run check` passed with 58 tests.
+- `npm pack --dry-run` included the MIT `LICENSE` file.
+
 ## v0.0.8
 
 ### Highlights
@@ -9,13 +44,15 @@
 - Add CLI `-d` / `--detach` to run the auto loop in a background supervisor, plus `--no-auto` for create-and-plan-only mode.
 - Add CLI `status [runId] [--watch]`, defaulting to the latest run when `runId` is omitted.
 - Add CLI `result [runId] [--copy]` to print or copy the final judge result.
+- Add CLI `retry <runId> [taskId]` and automatic one-shot retry for blocked batches while preserving failed worker attempts.
+- Add per-run `run_state.lock` protection around state writes to reduce CLI/Web/supervisor lost-update races.
 - Add CLI `stop <runId>` and make backend stop robust across CLI/Web processes by falling back to stored live PIDs.
 - Derive the run label from task text when `--label` / form label is omitted.
 - Add dashboard run-card archive confirmation without modal popups and replace the detail refresh text chips with a one-shot circle animation.
 
 ### Verification
 
-- `npm run check` passed with 51 tests.
+- `npm run check` passed with 58 tests.
 
 ## v0.0.7