input-kanban 0.0.1

package/ENVIRONMENT.md

@@ -0,0 +1,39 @@
+# Environment Variables
+
+This file documents the runtime environment variables supported by Input Kanban. It is intended for local deployment and runtime configuration, not as the main implementation guide for agents.
+
+CLI options take precedence over environment variables. Environment variables take precedence over defaults.
+
+## Variables
+
+- `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`.
+- `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`.
+
+## Environment Example
+
+```bash
+PORT=8787 \
+KANBAN_DEFAULT_REPO=/path/to/child-repo \
+KANBAN_RUNS_DIR=/path/to/kanban-runs \
+KANBAN_CODEX_BIN=codex \
+input-kanban
+```
+
+## Equivalent CLI Example
+
+```bash
+input-kanban \
+  --port 8787 \
+  --repo /path/to/child-repo \
+  --runs-dir /path/to/kanban-runs \
+  --codex-bin codex
+```
+
+## Notes
+
+- `KANBAN_DEFAULT_REPO` / `--repo` should point to the actual git repository where work should run.
+- The runtime runs directory contains task text, logs, model output, artifacts, and possible audit information. It should not be committed to git.
+- Avoid writing machine-specific absolute paths into public or shared documentation.

package/PROJECT_GUIDE.md

@@ -0,0 +1,331 @@
+# Input Kanban Project Guide
+
+This document explains how Input Kanban is implemented so that humans and coding agents can quickly understand the project before making changes.
+
+## Current Status
+
+Implementation status:
+
+```text
+mvp / batch-scheduler / codex-exec-primary / buildkite-style-ui / manual-recovery / stop-archive / cli-bootstrap
+```
+
+Recent validation:
+
+- `npm run check` passes for the CLI entry and backend modules.
+- A smoke test can start `input-kanban` on a temporary port and read `GET /api/health`.
+- The frontend is a single HTML file; its inline script can be extracted and checked with `node --check` when edited.
+
+## Project Purpose
+
+Input Kanban is a local Codex orchestration dashboard. It is not a business service and not a CI system.
+
+It runs local `codex exec --json` processes, stores run state and logs on the filesystem, and serves a static HTML dashboard that polls the backend.
+
+The intended use case is:
+
+1. Create a run from a user task.
+2. Ask a planner to split the task into batches and workers.
+3. Dispatch workers by strict batch barriers.
+4. Observe logs, status, artifacts, and Codex session IDs.
+5. Stop or archive runs when needed.
+6. Run one final judge pass after all batches complete.
+
+## 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.
+- Local process state, `exit_code`, logs, and artifacts are the source of truth. Codex App Server session lookup is auxiliary.
+- There is no batch-level judge. Only one final judge pass runs after all batches complete.
+
+## CLI Entry
+
+The npm CLI entry is:
+
+```text
+bin/input-kanban.js
+```
+
+It parses CLI options, sets environment variables before importing backend modules, and starts the HTTP server.
+
+Supported options:
+
+```text
+--host <host>
+--port <port>
+--repo <path>
+--runs-dir <path>
+--codex-bin <path>
+--open
+--no-open
+```
+
+Default behavior:
+
+- default repo: current working directory when `input-kanban` is launched;
+- default host: `127.0.0.1`;
+- default port: `8787`;
+- default runs directory: `~/.input-kanban/runs`;
+- default Codex binary: `codex`.
+
+## Data Model
+
+### Run
+
+A run is one user-submitted task batch. It appears as one card in the left sidebar and maps to one runtime directory:
+
+```text
+runs/<runId>/
+```
+
+Main files:
+
+```text
+task.md
+plan.json
+run_state.json
+```
+
+### Batch
+
+A batch is a strict scheduling barrier produced by the planner. Only the first incomplete batch is eligible for scheduling. Later batches must wait until all earlier batches complete.
+
+### Task
+
+A task is one worker inside a batch. Batch-level parallelism is controlled by `batch.maxParallel`.
+
+### Roles
+
+- `planner`: read-only `codex exec` that returns a plan.
+- `worker`: normally `workspace-write` `codex exec` that performs work.
+- `judge`: read-only `codex exec` that performs final evaluation.
+
+## Run State Machine
+
+Common run states:
+
+- `created`: run exists, planner has not started.
+- `planning`: planner is running.
+- `plan_failed`: planner failed or returned output that could not be parsed.
+- `plan_empty`: planner returned valid JSON but zero tasks.
+- `planned`: planner produced executable tasks.
+- `running`: at least one worker in the current batch is running.
+- `batch_blocked`: the current batch has a `failed` or `unknown` worker; later batches will not start.
+- `batches_completed`: all batches completed; final judge can run.
+- `judging`: final judge is running.
+- `judged`: final judge process completed.
+- `judge_failed`: final judge process failed.
+- `stopped`: user stopped the run; no further scheduling occurs.
+
+## Planner Retry Policy
+
+Planner retry is allowed only before any worker or judge has started.
+
+Before retrying, the backend:
+
+1. Moves the current `planner/` directory to `planner_attempts/attempt-XX/`.
+2. Clears current `tasks` and `batches`.
+3. Resets `judge` state.
+4. Deletes old `plan.json`.
+5. Starts a new planner in a clean `planner/` directory.
+
+If the planner returns valid JSON with zero tasks, the run is marked `plan_empty`. The UI shows a warning and allows planning again.
+
+## Worker Failure Policy
+
+Workers are not automatically retried.
+
+Reason: a worker may have already changed files in the target repository. Retrying could duplicate edits, overwrite partial work, or create conflicts.
+
+Recovery options:
+
+- Inspect `events.pretty`, `stderr.log`, `last_message.md`, 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`.
+- The UI preserves the original failed or unknown status while also showing the manual completion marker.
+
+## Stop and Archive
+
+### Stop
+
+`POST /api/runs/:runId/stop` terminates still-running local `codex exec` child processes for that run and freezes the run as `stopped`.
+
+### Archive
+
+`POST /api/runs/:runId/archive` performs a soft archive:
+
+- writes `archived: true` to `run_state.json`;
+- does not move the run directory;
+- hides the run from default `GET /api/runs` and the left sidebar.
+
+Archived runs can be queried with:
+
+```text
+GET /api/runs?includeArchived=1
+```
+
+## Left Sidebar Behavior
+
+The left sidebar is rendered from API summaries, not direct file reads.
+
+Flow:
+
+1. Backend scans `runs/<runId>/run_state.json`.
+2. `summaryOfRun()` creates summaries.
+3. `GET /api/runs` returns those summaries.
+4. Frontend renders run cards.
+
+Current behavior:
+
+- Shows the newest 10 runs by default.
+- `Show more` appends 10 more runs.
+- Sidebar height is fixed to the viewport; the run list has its own vertical scroll.
+- Each card shows label, status, run ID, creation time, progress, running count, and failed count.
+- Long labels are clamped to two lines with a browser tooltip for the full value.
+
+## Final Judge
+
+Final Judge runs once after all batches complete.
+
+Before starting the judge, the backend generates:
+
+```text
+runs/<runId>/judge/judge_input.json
+```
+
+This manifest is the judge's primary source of truth. It contains:
+
+- run metadata;
+- original task text;
+- `plan.json`;
+- batch summaries and task order;
+- planner status, output, and parse errors;
+- worker status, exit code, start/end timestamps, expected artifacts;
+- each worker's `last_message.md`, `result.json`, `evidence.json`, `manual_completion.json`, and stderr tail.
+
+The judge prompt instructs the model to use `judge_input.json` first and inspect other run artifacts only if needed. This makes final evaluation more deterministic than asking the judge to discover files on its own.
+
+## File Viewer
+
+The file viewer calls:
+
+```text
+GET /api/runs/:runId/tasks/:taskId/file?name=...
+```
+
+It can read planner, worker, and judge files.
+
+Current behavior:
+
+- Selecting a task updates the file viewer title to `runId / taskId`.
+- If a file tab is already open, switching tasks reloads the same file for the newly selected task.
+- Auto refresh also reloads the selected task's selected file and attempts to preserve scroll position.
+- `events.pretty` is a virtual file generated by formatting `events.jsonl` into a readable Chinese execution log.
+- The execution view shows event counts and a jump-to-bottom button.
+- `last_message.md` has a hover copy button in the top-left of the text area.
+- `judge_input.json` can be viewed through the `Judge Input` tab.
+
+## Files and Responsibilities
+
+```text
+bin/input-kanban.js       CLI entry; parses args and starts server
+src/server.js             HTTP server, static files, API routes
+src/orchestrator.js       run state machine, scheduling, codex exec, stop/archive, file formatting
+src/appServerClient.js    Codex App Server stdio client and session lookup
+src/utils.js              paths, IDs, atomic JSON writes, file info, JSON extraction
+public/index.html         single-file frontend, no build step
+README.md                 user-facing overview
+PROJECT_GUIDE.md          implementation guide for humans and agents
+ENVIRONMENT.md            runtime environment variable reference
+```
+
+Runtime files:
+
+```text
+runs/<runId>/run_state.json
+runs/<runId>/task.md
+runs/<runId>/plan.json
+runs/<runId>/planner/
+runs/<runId>/planner_attempts/attempt-XX/
+runs/<runId>/workers/<taskId>/
+runs/<runId>/judge/judge_input.json
+runs/<runId>/judge/verdict.json
+```
+
+## API
+
+- `GET /`
+- `GET /api/health`
+- `GET /api/runs`
+- `GET /api/runs?includeArchived=1`
+- `POST /api/runs`
+- `GET /api/runs/:runId/status`
+- `POST /api/runs/:runId/plan`
+- `POST /api/runs/:runId/dispatch`
+- `POST /api/runs/:runId/judge`
+- `POST /api/runs/:runId/stop`
+- `POST /api/runs/:runId/archive`
+- `GET /api/runs/:runId/task-text`
+- `GET /api/runs/:runId/tasks/:taskId/file?name=...`
+- `POST /api/runs/:runId/tasks/:taskId/mark-completed`
+
+## Planner Output
+
+Preferred shape:
+
+```json
+{
+  "batches": [
+    {
+      "id": "batch-1",
+      "name": "first batch",
+      "maxParallel": 3,
+      "tasks": [
+        {
+          "id": "T-01",
+          "name": "short name",
+          "prompt": "worker prompt",
+          "sandbox": "workspace-write",
+          "expectedArtifacts": []
+        }
+      ]
+    }
+  ],
+  "finalJudgeRequired": true
+}
+```
+
+Backward-compatible shape:
+
+```json
+{
+  "tasks": [
+    {
+      "id": "T-01",
+      "name": "short name",
+      "prompt": "worker prompt",
+      "sandbox": "workspace-write",
+      "expectedArtifacts": []
+    }
+  ]
+}
+```
+
+The old `tasks` format is wrapped into `batch-1` automatically.
+
+## Development Checks
+
+```bash
+npm run check
+```
+
+When editing `public/index.html`, also consider extracting the inline script and checking it with `node --check`.
+
+## 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.
+- 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.md

@@ -0,0 +1,157 @@
+# Input Kanban
+
+Input Kanban is a lightweight local dashboard for splitting a Codex task into batches and workers, running them with `codex exec`, observing status, stopping or archiving runs, and performing a final judge pass.
+
+For implementation details and agent-facing project context, see:
+
+```text
+PROJECT_GUIDE.md
+```
+
+For runtime environment variables, see:
+
+```text
+ENVIRONMENT.md
+```
+
+## Features
+
+- Static HTML dashboard with no frontend build step.
+- Node.js backend that can:
+  - create multiple runs;
+  - start a `codex exec` planner and materialize `plan.json`;
+  - safely retry planner runs before any worker or judge starts;
+  - detect `plan_empty` when the planner returns zero tasks;
+  - schedule workers by strict batch barriers and `batch.maxParallel`;
+  - generate `judge_input.json` before the final judge pass;
+  - start an independent `codex exec` final judge;
+  - aggregate PID, exit code, events, stderr, last message, artifacts, and Codex session IDs;
+  - stop runs, soft-archive runs, and manually mark failed or unknown workers as completed.
+
+## CLI Usage
+
+Run from the target repository directory:
+
+```bash
+input-kanban
+```
+
+Or provide the target repository explicitly:
+
+```bash
+input-kanban --repo /path/to/repo
+```
+
+Then open:
+
+```text
+http://127.0.0.1:8787
+```
+
+Common options:
+
+```bash
+input-kanban --port 8787
+input-kanban --host 127.0.0.1
+input-kanban --runs-dir ~/.input-kanban/runs
+input-kanban --codex-bin codex
+input-kanban --open
+```
+
+## Development
+
+```bash
+npm start
+```
+
+For local CLI development:
+
+```bash
+npm link
+input-kanban
+```
+
+## Workflow
+
+1. Click `New Run`, then enter a label, target repo, max parallel value, and task text.
+2. Click `Create Run`.
+3. Click `Plan` to start the planner:
+   - planner uses `codex exec --json --sandbox read-only`;
+   - output is stored under `runs/<runId>/planner/`.
+4. When planning succeeds, `plan.json` is created and the worker list is shown.
+5. Click `Dispatch` to start workers according to batch barriers and `batch.maxParallel`.
+6. The page polls status every 3 seconds.
+7. After all batches complete, click `Final Judge` to run the final judge pass.
+
+The current UI labels are localized, but the project documentation is written in English for easier agent consumption.
+
+## Planner Output Format
+
+The preferred planner response is a JSON object with `batches`. The older `tasks` shape is also supported.
+
+```json
+{
+  "batches": [
+    {
+      "id": "batch-1",
+      "name": "first batch name",
+      "maxParallel": 3,
+      "tasks": [
+        {
+          "id": "T-01",
+          "name": "short name",
+          "prompt": "complete worker prompt",
+          "sandbox": "workspace-write",
+          "expectedArtifacts": ["tmp/example-result.json"]
+        }
+      ]
+    }
+  ],
+  "finalJudgeRequired": true
+}
+```
+
+The backend extracts the first JSON object from `last_message.md`. If the planner succeeds but returns zero tasks, the run is marked `plan_empty` and can be planned again before any worker or judge starts.
+
+## Status Sources
+
+Worker status is primarily determined from local state:
+
+- Node child process tracking
+- `exit_code`
+- `events.jsonl`
+- `stderr.log`
+- `last_message.md`
+- expected artifacts
+
+Codex App Server is an auxiliary source only:
+
+- the backend starts `codex app-server --stdio`;
+- it calls `thread/list`;
+- it matches sessions using prompt markers:
+  - `ORCHESTRATOR_RUN_ID`
+  - `ORCHESTRATOR_TASK_ID`
+
+A Codex App Server `notLoaded` state does not mean a worker failed. The local process, exit code, logs, and artifacts remain the source of truth.
+
+## Runtime Directory
+
+```text
+runs/<runId>/
+├── task.md
+├── plan.json
+├── run_state.json
+├── planner/
+├── workers/<taskId>/
+└── judge/
+    ├── judge_input.json
+    └── verdict.json
+```
+
+The development `runs/` directory is gitignored. For CLI usage, the default runtime directory is `~/.input-kanban/runs`.
+
+## Checks
+
+```bash
+npm run check
+```

package/bin/input-kanban.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+
+function parseArgs(argv) {
+  const args = { host: '127.0.0.1', port: undefined, repo: undefined, runsDir: undefined, codexBin: undefined, open: false, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    const next = () => argv[++i];
+    if (arg === '--help' || arg === '-h') args.help = true;
+    else if (arg === '--open') args.open = true;
+    else if (arg === '--no-open') args.open = false;
+    else if (arg === '--host') args.host = next();
+    else if (arg === '--port' || arg === '-p') args.port = Number(next());
+    else if (arg === '--repo' || arg === '-r') args.repo = next();
+    else if (arg === '--runs-dir') args.runsDir = next();
+    else if (arg === '--codex-bin') args.codexBin = next();
+    else throw new Error(`unknown argument: ${arg}`);
+  }
+  return args;
+}
+
+function printHelp() {
+  console.log(`input-kanban
+
+Usage:
+  input-kanban [options]
+
+Options:
+  --host <host>          Host to bind, default 127.0.0.1
+  -p, --port <port>      Port to bind, default 8787
+  -r, --repo <path>      Default target repository, default current directory
+  --runs-dir <path>      Runtime runs directory, default ~/.input-kanban/runs
+  --codex-bin <path>     Codex CLI executable, default codex
+  --open                 Open browser after starting
+  --no-open              Do not open browser, default
+  -h, --help             Show help
+`);
+}
+
+function openBrowser(url) {
+  const command = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd' : 'xdg-open';
+  const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url];
+  const child = spawn(command, args, { stdio: 'ignore', detached: true });
+  child.unref();
+}
+
+try {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) { printHelp(); process.exit(0); }
+  if (args.port) process.env.PORT = String(args.port);
+  if (args.host) process.env.HOST = args.host;
+  if (args.repo) process.env.KANBAN_DEFAULT_REPO = path.resolve(args.repo);
+  else if (!process.env.KANBAN_DEFAULT_REPO) process.env.KANBAN_DEFAULT_REPO = process.cwd();
+  if (args.runsDir) process.env.KANBAN_RUNS_DIR = path.resolve(args.runsDir);
+  if (args.codexBin) process.env.KANBAN_CODEX_BIN = args.codexBin;
+
+  const { startServer } = await import('../src/server.js');
+  const instance = await startServer({ host: process.env.HOST, port: Number(process.env.PORT || 8787), log: false });
+  console.log('Input Kanban started');
+  console.log(`URL:  ${instance.url}`);
+  console.log(`Repo: ${instance.defaultRepo}`);
+  console.log(`Runs: ${instance.runsDir}`);
+  if (args.open) openBrowser(instance.url);
+  const shutdown = () => { instance.stop().finally(() => process.exit(0)); };
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+} catch (error) {
+  console.error(error.message || String(error));
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "input-kanban",
+  "version": "0.0.1",
+  "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 src/server.js && node --check src/orchestrator.js && node --check src/appServerClient.js && node --check src/utils.js"
+  },
+  "dependencies": {},
+  "description": "A local Codex orchestration kanban dashboard",
+  "files": [
+    "bin",
+    "src",
+    "public",
+    "README.md",
+    "PROJECT_GUIDE.md",
+    "ENVIRONMENT.md"
+  ],
+  "keywords": [
+    "codex",
+    "kanban",
+    "orchestration",
+    "cli",
+    "agent"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zhang3xing1/Input-Kanban.git"
+  },
+  "bugs": {
+    "url": "https://github.com/zhang3xing1/Input-Kanban/issues"
+  },
+  "homepage": "https://github.com/zhang3xing1/Input-Kanban#readme",
+  "engines": {
+    "node": ">=20"
+  }
+}