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

@@ -87,6 +87,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
@@ -125,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
@@ -190,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.
+
+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 repository ever moves to shared network storage, the current single-machine exclusive-file assumptions should be re-evaluated.
+
 ## Stop and Archive
 
 ### Stop
@@ -307,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
@@ -324,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

@@ -73,15 +73,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>`. 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
 
@@ -117,10 +123,10 @@ After run-level tmux metadata is available, the dashboard shows `Copy tmux attac
 2. Enter a label, target repository, 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
 

package/README.md

@@ -73,15 +73,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>` 查详情。不传 `runId` 时，`status` 和 `result` 默认查看最近一次任务批次。`result --copy` 会复制最终验收结果；`retry` 会保留失败现场并重试失败/未知任务；`--json` 适合给 agent/脚本做结构化读取；停止任务请显式传入 `runId`，避免误停。
 
 ## 常用启动参数
 
@@ -117,10 +123,10 @@ tmux 模式是可选能力，主要用于在终端里实时查看每个 Codex
 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。
 
 ## 它适合做什么
 

package/RELEASE_NOTES.md

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