input-kanban 0.0.7 → 0.0.9

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

@@ -51,9 +51,9 @@ The npm CLI entry is:
 bin/input-kanban.js
 ```
 
-It parses CLI options, sets environment variables before importing backend modules, and starts the HTTP server.
+It parses CLI options and sets environment variables before importing backend modules. Without a subcommand, or with `serve`, it starts the HTTP server. With `submit`, it creates a run directly in the shared runs directory and can optionally run an auto loop.
 
-Supported options:
+Supported serve options:
 
 ```text
 --host <host>
@@ -61,10 +61,75 @@ Supported options:
 --repo <path>
 --runs-dir <path>
 --codex-bin <path>
+--runner <headless|tmux>
 --open
 --no-open
 ```
 
+Supported status options:
+
+```text
+[runId]
+--runs-dir <path>
+--watch
+--poll-ms <ms>
+```
+
+`input-kanban status` refreshes and prints a run summary. If no `runId` is provided, it uses the latest run from the shared runs directory. `--watch` keeps polling until the run reaches a terminal state.
+
+Supported result options:
+
+```text
+[runId]
+--runs-dir <path>
+--copy
+```
+
+`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
+<runId>
+--runs-dir <path>
+--reason <text>
+```
+
+`input-kanban stop <runId>` calls the same orchestrator stop path as the Web dashboard. Stop requires an explicit run id. The backend first asks the active runner to stop known processes and then falls back to killing live stored PIDs, so Web and CLI processes can stop each other's headless workers.
+
+Supported submit options:
+
+```text
+--repo <path>
+--label <label>
+--task <text>
+--task-file <path|->
+--max-parallel <n>
+--worker-sandbox <read-only|workspace-write|danger-full-access>
+--runner <headless|tmux>
+--runs-dir <path>
+--auto
+--no-auto
+--detach / -d
+--watch
+--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`.
+
 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;
@@ -73,6 +138,38 @@ Default behavior:
 - 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
@@ -138,18 +235,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.
 
-Reason: a worker may have already changed files in the target repository. Retrying could duplicate edits, overwrite partial work, or create conflicts.
+Retry rules:
 
-Recovery options:
+- 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.
 
-- Inspect `events.pretty`, `stderr.log`, `last_message.md`, and artifacts.
+Recovery options after retries are exhausted:
+
+- 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 repository ever moves to shared network storage, the current single-machine exclusive-file assumptions should be re-evaluated.
+
 ## Stop and Archive
 
 ### Stop
@@ -255,6 +415,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
@@ -272,6 +433,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`

package/README.en.md

@@ -43,6 +43,52 @@ If you do not want to `cd` into the target repository first, pass it explicitly:
 input-kanban --repo /path/to/your/repo
 ```
 
+## CLI Auto Execution
+
+To submit a task from the terminal and let it advance automatically, use `submit`. Task content supports two input modes:
+
+```bash
+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`.
+
+To return immediately and let a background supervisor continue the auto loop, pass `-d` / `--detach`:
+
+```bash
+input-kanban submit --task-file task.md -d
+```
+
+To create the run and start planning without dispatching or judging, pass `--no-auto`.
+
+Common examples:
+
+```bash
+input-kanban submit --task "Fix login issue"
+input-kanban submit --task-file task.md --max-parallel 2 --worker-sandbox workspace-write
+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>
+```
+
+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>`. 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
 
 ```bash
@@ -76,11 +122,11 @@ After run-level tmux metadata is available, the dashboard shows `Copy tmux attac
 1. Click `New Run`.
 2. Enter a label, target repository, worker sandbox, and task description.
 3. Click `Create Run`.
-4. Click `Plan` to let the Codex planner generate batches and workers.
-5. Click `Dispatch` to run workers by batch barrier and concurrency limits.
-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.
+4. The dashboard automatically starts `Plan` so the Codex planner can generate batches and workers.
+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
 

package/README.md

@@ -43,6 +43,52 @@ http://127.0.0.1:8787
 input-kanban --repo /path/to/your/repo
 ```
 
+## CLI 自动执行
+
+如果希望从终端直接提交任务并自动推进，可以使用 `submit`。任务内容支持两种输入方式：
+
+```bash
+input-kanban submit --task-file task.md --label "修复登录问题"
+input-kanban submit --task "修复登录问题，并补充回归测试" --label "修复登录问题"
+```
+
+`submit` 默认会创建任务批次、发起拆分、自动派发所有批次，并在全部完成后自动发起最终验收。默认 repo 是当前目录；如果不传 `--label`，任务批次名称会从任务内容自动生成。它使用同一个 runs 目录，所以只要 8787 Web 看板也使用相同的 `--runs-dir`，CLI 创建的任务会在 Web 界面里可见。
+
+如果希望提交后立即返回，让任务在后台自动执行，可以加 `-d` / `--detach`：
+
+```bash
+input-kanban submit --task-file task.md -d
+```
+
+如果只想创建并拆分，不自动派发和验收，可以加 `--no-auto`。
+
+常用参数：
+
+```bash
+input-kanban submit --task "修复登录问题"
+input-kanban submit --task-file task.md --max-parallel 2 --worker-sandbox workspace-write
+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>
+```
+
+`runs` 用来先列出可见任务批次，`runs --active` 只列出未进入终态或仍有子任务运行的批次，便于 agent 先发现 `runId`，再用 `status <runId>` 查详情。不传 `runId` 时，`status` 和 `result` 默认查看最近一次任务批次。`result --copy` 会复制最终验收结果；`retry` 会保留失败现场并重试失败/未知任务；`--json` 适合给 agent/脚本做结构化读取；停止任务请显式传入 `runId`，避免误停。
+
 ## 常用启动参数
 
 ```bash
@@ -76,11 +122,11 @@ tmux 模式是可选能力，主要用于在终端里实时查看每个 Codex
 1. 点击 `新建任务批次`。
 2. 输入批次名称、目标仓库、Worker 沙箱和任务说明。
 3. 点击 `创建批次`。
-4. 点击 `拆分任务`，让 Codex planner 生成 batches 和 workers。
-5. 点击 `派发执行`，按 batch barrier 和并发限制运行 workers。
-6. 查看执行日志、最终回复、错误日志和产物。
-7. 所有 batch 完成后，点击 `汇总验收`。
-8. 必要时可以停止或归档 run，也可以手动标记已确认完成的失败/未知 worker。
+4. 看板会自动发起 `拆分任务`，让 Codex planner 生成 batches 和 workers。
+5. 拆分完成后，Web 默认自动派发执行，按 batch barrier 和并发限制运行 workers。
+6. 所有 batch 完成后，Web 默认自动发起 `汇总验收`。
+7. 查看执行日志、最终回复、错误日志和产物。
+8. 必要时可以停止或归档 run，也可以手动点击按钮重试、推进，或手动标记已确认完成的失败/未知 worker。
 
 ## 它适合做什么
 

package/RELEASE_NOTES.md

@@ -1,5 +1,24 @@
 # Release Notes
 
+## v0.0.8
+
+### Highlights
+
+- Add CLI `submit` workflow with two task input modes: `--task-file <markdown>` for Markdown files and `--task <text>` for inline task text.
+- Add CLI auto loop as the default `submit` behavior to create a run, start planning, dispatch batches, and run the final judge while keeping the run visible in the shared Web dashboard.
+- 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 58 tests.
+
 ## v0.0.7
 
 ### Highlights