tasks-toolkit 0.1.3__py3-none-any.whl

scripts/kilo-task.sh

@@ -0,0 +1,226 @@
+#!/usr/bin/env bash
+# Delegates one task to the Kilo CLI agent inside its own worktree, then verifies it.
+# Same contract as junie-task.sh (worktree, heartbeat, verification, patch), different runner.
+#
+#   scripts/kilo-task.sh <name> "<task text>" [--task-id <id>]
+#   scripts/kilo-task.sh <name> --file tmp/tasks/<name>.md [--task-id <id>]
+#
+# --task-id reports progress to the task tracker (scripts/task-report.sh): the task is
+# marked in progress at the start, and after the commit and verification it is closed
+# automatically (done on success, blocked on failure); failures only warn.
+#
+# Env: KILO_MODEL (default kilo/deepseek/deepseek-v4-flash), KILO_AGENT (default code),
+#      KILO_TIMEOUT (default 1200 s), KILO_PING (default 30 s),
+#      KILO_VERIFY_CMD (tests only: replaces the dotnet verification).
+# Output: tmp/runs/<name>.{status,events.jsonl,result.txt,verify.log,summary.json},
+#         tmp/patches/<name>.patch. Every status line ends with
+#         "model=<model> runner=kilo" so it can be parsed.
+# Exit code: 0 verified, 1 verification failed, 3 Kilo itself failed.
+#
+# Notes:
+# - ~/.config/kilo/kilo.jsonc is written by the VS Code extension in the V2 permission format,
+#   which the CLI rejects; the run therefore uses an empty XDG_CONFIG_HOME (credentials live in
+#   XDG_DATA_HOME and are unaffected). The project's kilo.json still applies in the worktree.
+# - --auto approves every permission that kilo.json does not explicitly deny (git push, hard reset,
+#   git clean, amend and rm -rf are denied there). The worktree is disposable; review the patch.
+set -euo pipefail
+
+root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$root"
+
+runner="kilo"
+name="${1:?usage: kilo-task.sh <name> \"<task>\" | --file <path> [--task-id <id>]}"
+shift
+if [ "${1:-}" = "--file" ]; then
+  task="$(cat "${2:?missing task file}")"
+  shift 2
+else
+  task="${1:?missing task text}"
+  shift
+fi
+task_id=""
+if [ "${1:-}" = "--task-id" ]; then
+  task_id="${2:?--task-id needs a value}"
+fi
+
+model="${KILO_MODEL:-configured-default}"
+agent="${KILO_AGENT:-code}"
+limit="${KILO_TIMEOUT:-1200}"
+ping_every="${KILO_PING:-30}"
+model_args=()
+if [ -n "${KILO_MODEL:-}" ]; then
+  model_args=(-m "$KILO_MODEL")
+fi
+
+if [ -d "tmp/worktrees/$name" ]; then
+  wt="$root/tmp/worktrees/$name"
+else
+  wt="$(bash scripts/worktree.sh new "$name" ${task_id:+--task-id "$task_id"})"
+fi
+mkdir -p tmp/runs tmp/xdg-empty
+
+run_file="$root/agents/$runner/RUN.md"
+[ -f "$run_file" ] || { echo "error: missing $run_file" >&2; exit 1; }
+prompt="$task
+
+$(cat "$run_file")"
+
+status_file="$root/tmp/runs/$name.status"
+events="$root/tmp/runs/$name.events.jsonl"
+base="$(cat "tmp/meta/$name.base")"
+started=$SECONDS
+started_epoch="$(date +%s)"
+
+report() {  # report <state> [detail]: one line to stdout and the status file
+  local line
+  line="$(printf '[%02d:%02d] %s' $(((SECONDS - started) / 60)) $(((SECONDS - started) % 60)) "$1${2:+ - $2}")"
+  echo "$line model=$model runner=$runner"
+  echo "$line model=$model runner=$runner" >"$status_file"
+}
+
+# last_activity: the latest tool call or text of the agent, from the JSON event stream.
+last_activity() {
+  python3 - "$events" <<'PY'
+import json, sys
+last = ""
+try:
+    for line in open(sys.argv[1], errors="replace"):
+        try:
+            part = json.loads(line).get("part", {})
+        except ValueError:
+            continue
+        if part.get("type") == "tool":
+            last = "tool " + str(part.get("tool"))
+        elif part.get("type") == "text" and part.get("text"):
+            last = "text: " + " ".join(part["text"].split())
+except OSError:
+    pass
+print(last[:110])
+PY
+}
+
+bash scripts/task-report.sh start "$task_id"
+report "starting" "agent=$agent worktree=$wt${task_id:+ task=$task_id}"
+GIT_CONFIG_COUNT=1 \
+GIT_CONFIG_KEY_0=core.hooksPath \
+GIT_CONFIG_VALUE_0="$root/scripts/coder-git-hooks" \
+XDG_CONFIG_HOME="$root/tmp/xdg-empty" timeout "$limit" kilo run --dir "$wt" "${model_args[@]}" --agent "$agent" \
+  --format json --auto "$prompt" >"$events" 2>"$root/tmp/runs/$name.stderr.log" &
+kilo_pid=$!
+
+stalled=0
+while kill -0 "$kilo_pid" 2>/dev/null; do
+  sleep "$ping_every" & wait $! || true
+  kill -0 "$kilo_pid" 2>/dev/null || break
+  changed="$(git -C "$wt" status --porcelain | wc -l)"
+  # Stall detector: an agent that has changed nothing after RUNNER_STALL seconds is stuck
+  # (seen with Kilo: 8+ minutes, 0 files). Kill it so the planner can switch runner early.
+  if [ "$changed" -eq 0 ] && [ $((SECONDS - started)) -ge "${RUNNER_STALL:-420}" ]; then
+    report "stalled" "no file changed after ${RUNNER_STALL:-420}s; killing the agent"
+    kill "$kilo_pid" 2>/dev/null || true
+    stalled=1
+    break
+  fi
+  last="$(last_activity)"
+  report "kilo running" "$changed file(s) changed; last: ${last:-<no output yet>}"
+done
+set +e
+wait "$kilo_pid"
+kilo_rc=$?
+set -e
+report "kilo finished" "exit $kilo_rc, verifying"
+
+python3 - "$events" >"$root/tmp/runs/$name.result.txt" <<'PY'
+import json, sys
+out = []
+for line in open(sys.argv[1], errors="replace"):
+    try:
+        part = json.loads(line).get("part", {})
+    except ValueError:
+        continue
+    if part.get("type") == "text" and part.get("text"):
+        out.append(part["text"])
+print(out[-1] if out else "")
+PY
+
+# Commit the agent's work on task/<name> (path guard first); agents never commit themselves.
+commit_rc=0
+if [ "$kilo_rc" -eq 0 ]; then
+  task_head="$(git -C "$wt" rev-parse HEAD)"
+  if [ "$task_head" != "$base" ]; then
+    commit_rc=1
+    printf 'Kilo changed task HEAD itself; only the parent runner may commit.\n' >"tmp/runs/$name.commit.log"
+  elif ! git -C "$wt" add -A; then
+    commit_rc=1
+    printf 'Could not stage the Kilo task diff for guarded commit.\n' >"tmp/runs/$name.commit.log"
+  else
+    changed_lines="$(git -C "$wt" diff --cached --numstat "$base" \
+      | awk '$1 ~ /^[0-9]+$/ && $2 ~ /^[0-9]+$/ { total += $1 + $2 } END { print total + 0 }')"
+    if [ "$changed_lines" -gt 300 ]; then
+      commit_rc=1
+      printf 'Kilo task diff has %s added/deleted lines (limit 300); split the task before committing.\n' \
+        "$changed_lines" >"tmp/runs/$name.commit.log"
+    else
+      title="$(printf '%s\n' "$task" | grep -m1 -v '^[[:space:]]*$' | cut -c1-72)"
+      bash scripts/worktree.sh commit "$name" --runner "$runner" --model "$model" \
+        ${task_id:+--task-id "$task_id"} --title "${title:-$name}" >"tmp/runs/$name.commit.log" 2>&1 || commit_rc=$?
+    fi
+  fi
+fi
+patch="$(bash scripts/worktree.sh patch "$name")"
+
+verify_rc=0
+{
+  if [ -n "${KILO_VERIFY_CMD:-}" ]; then
+    echo "== verify (KILO_VERIFY_CMD override) =="
+    (cd "$wt" && bash -c "$KILO_VERIFY_CMD") || verify_rc=1
+  elif ! bash "$root/scripts/needs-dotnet-checks.sh" "$wt" "$base" HEAD; then
+    echo "== conditional verification (no .NET files changed): script tests =="
+    (cd "$wt" && bash scripts/test_worktree.sh && bash scripts/test_runners.sh \
+       && python3 -m unittest discover -s scripts -p "test_*.py") || verify_rc=1
+  else
+    echo "== format =="; (cd "$wt" && dotnet format VibeEmulator.slnx --verify-no-changes) || verify_rc=1
+    echo "== build ==";  (cd "$wt" && dotnet build VibeEmulator.slnx --no-incremental -warnaserror) || verify_rc=1
+    echo "== test ==";   (cd "$wt" && dotnet test VibeEmulator.slnx --no-build) || verify_rc=1
+  fi
+} >"tmp/runs/$name.verify.log" 2>&1
+
+if [ "$commit_rc" -ne 0 ]; then
+  verify_rc=1
+  echo "== commit failed (exit $commit_rc): see tmp/runs/$name.commit.log ==" >>"tmp/runs/$name.verify.log"
+fi
+finished="$(date +%s)"
+files_changed="$(git -C "$wt" diff --cached --name-only "$base" | wc -l)"
+if [ "$kilo_rc" -ne 0 ]; then
+  verdict="agent_failed"
+elif [ "$verify_rc" -ne 0 ]; then
+  verdict="verify_failed"
+else
+  verdict="verified"
+fi
+if ! python3 scripts/run_summary.py "$root/tmp/runs/$name.summary.json" name="$name" runner="$runner" model="$model" \
+    agent="$agent" task_id="$task_id" started="$started_epoch" finished="$finished" \
+    agent_exit="$kilo_rc" verify_exit="$verify_rc" verdict="$verdict" \
+    patch="$patch" files_changed="$files_changed"; then
+  echo "warning: could not write run summary (tmp/runs/$name.summary.json)" >&2
+fi
+
+report "done" "kilo exit $kilo_rc, verification $([ "$verify_rc" -eq 0 ] && echo PASSED || echo FAILED)"
+echo "runner:       $runner"
+echo "model:        $model"
+echo "kilo exit:    $kilo_rc"
+echo "verification: $([ "$verify_rc" -eq 0 ] && echo PASSED || echo FAILED) (tmp/runs/$name.verify.log)"
+echo "patch:        $patch"
+git -C "$wt" diff --cached --stat "$base" | tail -n 15
+if [ "$kilo_rc" -ne 0 ]; then
+  bash scripts/task-report.sh note "$task_id" "kilo '$name' failed (exit 3) model=$model; see tmp/runs/$name.verify.log"
+  bash scripts/task-report.sh close "$task_id" red "agent exit $kilo_rc; see tmp/runs/$name.verify.log"
+  exit 3
+elif [ "$verify_rc" -ne 0 ]; then
+  bash scripts/task-report.sh note "$task_id" "kilo '$name' failed (exit 1) model=$model; see tmp/runs/$name.verify.log"
+  bash scripts/task-report.sh close "$task_id" red "verification failed; see tmp/runs/$name.verify.log"
+  exit 1
+else
+  bash scripts/task-report.sh note "$task_id" "kilo '$name' verified model=$model; patch tmp/patches/$name.patch"
+  bash scripts/task-report.sh close "$task_id" green
+fi

scripts/needs-dotnet-checks.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# Exit 0 when the diff needs the .NET checks (it touches C#/MSBuild/format configuration), 1 when the
+# change is docs/scripts only, so the caller can run the matching script tests instead (task 6.6).
+#
+#   scripts/needs-dotnet-checks.sh <dir> <base> [<head>]
+#
+# With an empty <base> the working tree against HEAD is inspected.
+set -euo pipefail
+
+dir="${1:-.}"
+base="${2:-}"
+head="${3:-HEAD}"
+
+if [ -n "$base" ]; then
+    files="$(git -C "$dir" diff --name-only "$base" "$head" 2>/dev/null || true)"
+else
+    files="$(git -C "$dir" diff --name-only HEAD 2>/dev/null || true)"
+    files+=$'\n'"$(git -C "$dir" ls-files --others --exclude-standard 2>/dev/null || true)"
+fi
+
+if printf '%s\n' "$files" | grep -qE '\.(cs|csproj|props|targets|slnx|sln|editorconfig)$|(^|/)(Directory\.[A-Za-z]+\.props|stylecop\.json|global\.json|\.editorconfig)$'; then
+    exit 0
+fi
+exit 1

scripts/plan-sprint.sh

@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+# Asks the Kilo planner agent (OpenAI Sol via the Kilo Gateway) to PROPOSE a sprint, then validates it.
+# Nothing is written to the tracker: review tmp/plans/<name>.json, then run scripts/apply-plan.sh <name>.
+# Design: knowledge/local-planner-design.md
+#
+#   scripts/plan-sprint.sh <name> --goal "<what the sprint should achieve>" [--goal-file F]
+#                          [--model M] [--variant V] [--no-lint]
+#
+# Env: VIBE_PLANNER_MODEL (default kilo/openai/gpt-6.1-sol), VIBE_PLANNER_VARIANT (default high),
+#      PLANNER_TIMEOUT (default 900 s), KILO_BIN (default kilo; tests put a stub here).
+# Output: tmp/plans/<name>.{input.md,events.jsonl,raw.txt,json,stderr.log}, tmp/tasks/<spec_name>.md
+# Exit: 0 valid plan | 1 usage | 3 Kilo failed or timed out | 4 plan invalid (specs are not written)
+set -euo pipefail
+
+root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$root"
+
+usage() { echo "usage: $0 <name> --goal \"<text>\" [--goal-file F] [--model M] [--variant V] [--no-lint]" >&2; exit 1; }
+
+name="${1:-}"
+[[ "$name" =~ ^[a-z0-9][a-z0-9-]*$ ]] || { echo "error: <name> must match ^[a-z0-9][a-z0-9-]*\$" >&2; usage; }
+shift
+goal="" model="${VIBE_PLANNER_MODEL:-kilo/openai/gpt-6.1-sol}" variant="${VIBE_PLANNER_VARIANT:-high}" lint_flag=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --goal)      goal="${2:?--goal needs text}"; shift 2 ;;
+    --goal-file) [ -f "${2:?--goal-file needs a path}" ] || { echo "error: no such file '$2'" >&2; exit 1; }
+                 goal="$(cat "$2")"; shift 2 ;;
+    --model)     model="${2:?--model needs a value}"; shift 2 ;;
+    --variant)   variant="${2:?--variant needs a value}"; shift 2 ;;
+    --no-lint)   lint_flag="--no-lint"; shift ;;
+    *) echo "unknown option '$1'" >&2; usage ;;
+  esac
+done
+[ -n "$goal" ] || { echo "error: --goal is required" >&2; usage; }
+
+kilo_bin="${KILO_BIN:-kilo}"
+limit="${PLANNER_TIMEOUT:-900}"
+mkdir -p tmp/plans tmp/tasks tmp/xdg-empty
+input="tmp/plans/$name.input.md"
+events="tmp/plans/$name.events.jsonl"
+raw="tmp/plans/$name.raw.txt"
+plan="tmp/plans/$name.json"
+rm -f "$plan" "tmp/plans/$name.applied"
+
+# Input bundle: only tracker state, recent history and the goal go to the model (see the privacy note in the design).
+{
+  echo "# Planning input: $name"
+  echo
+  echo "## Goal"
+  printf '%s\n' "$goal"
+  echo
+  echo "## Tracker overview"
+  python3 scripts/tasks.py overview
+  echo
+  echo "## Recent history"
+  git log --oneline -15
+  echo
+  echo "## Current branch"
+  git branch --show-current
+} >"$input"
+
+prompt="Plan the next sprint for this repository. Follow agents/kilo/PLANNER.md exactly and answer with the single JSON block it specifies. Input bundle: $input"
+
+echo "planning '$name' with $model (variant $variant), timeout ${limit}s" >&2
+rc=0
+XDG_CONFIG_HOME="$root/tmp/xdg-empty" timeout "$limit" "$kilo_bin" run --dir "$root" --agent planner -m "$model" \
+  --variant "$variant" --format json "$prompt" >"$events" 2>"tmp/plans/$name.stderr.log" || rc=$?
+if [ "$rc" -ne 0 ]; then
+  echo "error: planner agent failed (exit $rc); see tmp/plans/$name.stderr.log" >&2
+  exit 3
+fi
+
+python3 - "$events" >"$raw" <<'PY'
+import json, sys
+texts = []
+for line in open(sys.argv[1], errors="replace"):
+    try:
+        part = json.loads(line).get("part", {})
+    except ValueError:
+        continue
+    if part.get("type") == "text" and part.get("text"):
+        texts.append(part["text"])
+print(texts[-1] if texts else "")
+PY
+
+python3 scripts/sprint_plan.py extract "$raw" "$plan" || { echo "error: no usable plan in $raw" >&2; exit 4; }
+python3 scripts/sprint_plan.py validate "$plan" $lint_flag || { echo "error: plan rejected; raw answer kept in $raw" >&2; exit 4; }
+python3 scripts/sprint_plan.py specs "$plan" >/dev/null
+python3 scripts/sprint_plan.py preview "$plan"
+echo ""
+echo "plan: $plan  (apply with: scripts/apply-plan.sh $name)"

scripts/run-task.sh

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+# One entry point for the orchestrator to delegate one task to a coder runner.
+# Codex is the default; Junie and Kilo remain explicit opt-ins. There is no fallback by default.
+#
+#   scripts/run-task.sh <name> --file tmp/tasks/<name>.md [--task-id <id>] [--runner junie|kilo|codex] [--fallback kilo|codex|none]
+#
+# Default runner codex, default fallback none. Run it in the background (Bash run_in_background): it prints the
+# runner's report and exits with the runner's code (0 verified, 1 verification failed,
+# 3 agent failed or stalled on every attempt). Every attempt is appended to
+# tmp/runs/<name>.attempts (runner, exit code, seconds). A verification failure (exit 1)
+# is NOT retried on another runner: it needs a precise fix list from the planner.
+set -euo pipefail
+
+root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$root"
+
+name="${1:?usage: run-task.sh <name> --file <spec> [--task-id <id>] [--runner kilo|junie|codex] [--fallback none]}"
+shift
+spec="" task_id="" runner="codex" fallback="none"
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --file)     spec="${2:?--file needs a path}"; shift 2 ;;
+    --task-id)  task_id="${2:?--task-id needs a value}"; shift 2 ;;
+    --runner)   runner="${2:?--runner needs a value}"; shift 2 ;;
+    --fallback) fallback="${2:?--fallback needs a value}"; shift 2 ;;
+    *) echo "unknown option '$1'" >&2; exit 1 ;;
+  esac
+done
+[ -n "$spec" ] && [ -f "$spec" ] || { echo "spec file missing: '$spec'" >&2; exit 1; }
+bash scripts/spec-lint.sh "$spec" || { echo "run-task: spec failed lint" >&2; exit 1; }
+case "$runner" in junie|kilo|codex) ;; *) echo "unknown runner '$runner'" >&2; exit 1 ;; esac
+case "$fallback" in junie|kilo|codex|none) ;; *) echo "unknown fallback '$fallback'" >&2; exit 1 ;; esac
+[ "$fallback" != "$runner" ] || fallback="none"
+mkdir -p tmp/runs
+
+# Record the spec's "Files:" header as scope links, used by `tasks.py plan-batch`.
+if [ -n "$task_id" ]; then
+  python3 - "$spec" > "tmp/runs/$name.scopes" <<'PY'
+import sys
+lines = open(sys.argv[1], encoding="utf-8").read().splitlines()
+in_block, out = False, []
+for line in lines:
+    text = line.strip()
+    if text[:6].lower() == "files:":
+        in_block = True
+        rest = text[6:].strip()
+        if rest:
+            out += [x.strip() for x in rest.split(",")]
+        continue
+    if in_block:
+        if not text or (text[0].isalpha() and text.endswith(":")):
+            in_block = False
+        else:
+            out += [x.strip() for x in text.lstrip("-").split(",")]
+for value in out:
+    value = value.strip()
+    if value:
+        print(value)
+PY
+  while IFS= read -r scope; do
+    [ -n "$scope" ] && python3 scripts/tasks.py link "$task_id" scope "$scope" >/dev/null 2>&1 || true
+  done < "tmp/runs/$name.scopes"
+fi
+
+attempt() {  # attempt <runner>: run one runner, record it, leave its exit code in $rc
+  local r="$1" began=$SECONDS
+  rc=0
+  bash "scripts/$r-task.sh" "$name" --file "$spec" ${task_id:+--task-id "$task_id"} || rc=$?
+  printf '%s runner=%s exit=%s seconds=%s\n' "$(date +%H:%M:%S)" "$r" "$rc" "$((SECONDS - began))" >>"tmp/runs/$name.attempts"
+}
+
+rc=0
+attempt "$runner"
+if [ "$rc" -eq 3 ] && [ "$fallback" != "none" ]; then
+  echo "run-task: $runner failed or stalled (exit 3); retrying once with $fallback in the same worktree" >&2
+  bash scripts/task-report.sh note "$task_id" "run-task: $runner failed or stalled; falling back to $fallback" || true
+  attempt "$fallback"
+fi
+exit "$rc"

scripts/run.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$root"
+
+exec dotnet run --project src/VibeEmulator.Cli -- "$@"

scripts/run_stats.py

@@ -0,0 +1,141 @@
+#!/usr/bin/env python3
+"""Delivery-speed statistics for the delegation runners.
+
+Reads tmp/runs/<name>.summary.json when present (exact) and falls back to the last line of
+tmp/runs/<name>.status for older runs ("[mm:ss] done - junie exit 0, verification PASSED").
+A run whose status never reached "done" counts as unfinished (killed, stalled or crashed).
+Prints, per runner: runs, verified, failed, unfinished, median and p90 duration, plus the
+share of runs that did not end verified ("rework rate"). Standard library only, read-only.
+
+Usage: scripts/run_stats.py [--runs-dir DIR] [--json] [--since YYYY-MM-DD]
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import statistics
+import sys
+from datetime import datetime
+from pathlib import Path
+
+LAST_STAMP = re.compile(r"^\[(\d+):(\d{2})\]\s+(.*)$")
+RUNNER_TAIL = re.compile(r"\brunner=(\w+)")
+DONE_RUNNER = re.compile(r"^done - (junie|kilo|codex|haiku) exit (\d+), verification (PASSED|FAILED)")
+
+
+def parse_status(path: Path) -> dict | None:
+    """Best-effort record for a run that has only a .status file."""
+    try:
+        lines = [ln for ln in path.read_text(encoding="utf-8", errors="replace").splitlines() if ln.strip()]
+    except OSError:
+        return None
+    if not lines:
+        return None
+    match = LAST_STAMP.match(lines[-1])
+    if not match:
+        return None
+    seconds = int(match.group(1)) * 60 + int(match.group(2))
+    body = RUNNER_TAIL.sub("", match.group(3)).strip()
+    model_match = re.search(r"\bmodel=(\S+)", match.group(3))
+    runner_match = RUNNER_TAIL.search(match.group(3))
+    done = DONE_RUNNER.match(body.split(" model=")[0].strip())
+    record = {"name": path.stem, "duration_s": seconds, "source": "status",
+              "runner": runner_match.group(1) if runner_match else None,
+              "model": model_match.group(1) if model_match else None}
+    if done:
+        record["runner"] = record["runner"] or done.group(1)
+        agent_exit, verify = int(done.group(2)), done.group(3)
+        record["verdict"] = ("agent_failed" if agent_exit else
+                             "verified" if verify == "PASSED" else "verify_failed")
+    else:
+        record["verdict"] = "unfinished"
+    return record
+
+
+def load_runs(runs_dir: Path) -> list[dict]:
+    """All runs found in runs_dir; a summary.json wins over the .status of the same name."""
+    runs: dict[str, dict] = {}
+    for status in sorted(runs_dir.glob("*.status")):
+        record = parse_status(status)
+        if record:
+            record["mtime"] = status.stat().st_mtime
+            runs[record["name"]] = record
+    for summary in sorted(runs_dir.glob("*.summary.json")):
+        try:
+            data = json.loads(summary.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            continue
+        name = data.get("name") or summary.name.removesuffix(".summary.json")
+        record = {"name": name, "duration_s": int(data.get("duration_s", 0)), "source": "summary",
+                  "runner": data.get("runner"), "model": data.get("model"),
+                  "verdict": data.get("verdict", "unfinished"), "mtime": summary.stat().st_mtime}
+        runs[name] = record
+    return list(runs.values())
+
+
+def percentile(values: list[int], pct: float) -> int:
+    ordered = sorted(values)
+    index = max(0, min(len(ordered) - 1, round(pct * (len(ordered) - 1))))
+    return ordered[index]
+
+
+def summarize(runs: list[dict]) -> dict:
+    """Per-runner aggregates plus an overall block."""
+    groups: dict[str, list[dict]] = {}
+    for run in runs:
+        groups.setdefault(run.get("runner") or "unknown", []).append(run)
+    groups["ALL"] = list(runs)
+    result = {}
+    for runner, items in sorted(groups.items()):
+        finished = [r for r in items if r["verdict"] != "unfinished"]
+        durations = [r["duration_s"] for r in finished]
+        verified = sum(1 for r in items if r["verdict"] == "verified")
+        result[runner] = {
+            "runs": len(items),
+            "verified": verified,
+            "verify_failed": sum(1 for r in items if r["verdict"] == "verify_failed"),
+            "agent_failed": sum(1 for r in items if r["verdict"] == "agent_failed"),
+            "unfinished": sum(1 for r in items if r["verdict"] == "unfinished"),
+            "median_s": int(statistics.median(durations)) if durations else None,
+            "p90_s": percentile(durations, 0.9) if durations else None,
+            "rework_rate": round(1 - verified / len(items), 2) if items else None,
+        }
+    return result
+
+
+def fmt(seconds: int | None) -> str:
+    return "-" if seconds is None else f"{seconds // 60}:{seconds % 60:02d}"
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("--runs-dir", default=str(Path(__file__).resolve().parent.parent / "tmp" / "runs"))
+    parser.add_argument("--json", action="store_true", help="print the aggregates as JSON")
+    parser.add_argument("--since", help="only runs whose status/summary file is newer than YYYY-MM-DD")
+    args = parser.parse_args(argv)
+    runs_dir = Path(args.runs_dir)
+    if not runs_dir.is_dir():
+        print(f"no runs directory: {runs_dir}", file=sys.stderr)
+        return 1
+    runs = load_runs(runs_dir)
+    if args.since:
+        cutoff = datetime.strptime(args.since, "%Y-%m-%d").timestamp()
+        runs = [r for r in runs if r["mtime"] >= cutoff]
+    summary = summarize(runs)
+    if args.json:
+        print(json.dumps(summary, indent=2, sort_keys=True))
+        return 0
+    print(f"{'runner':<9}{'runs':>5}{'ok':>5}{'vfail':>6}{'afail':>6}{'unfin':>6}{'median':>8}{'p90':>8}{'rework':>8}")
+    for runner, s in summary.items():
+        rework = "-" if s["rework_rate"] is None else f"{int(s['rework_rate'] * 100)}%"
+        print(f"{runner:<9}{s['runs']:>5}{s['verified']:>5}{s['verify_failed']:>6}{s['agent_failed']:>6}"
+              f"{s['unfinished']:>6}{fmt(s['median_s']):>8}{fmt(s['p90_s']):>8}{rework:>8}")
+    slow = sorted((r for r in runs if r["verdict"] != "unfinished"), key=lambda r: -r["duration_s"])[:3]
+    if slow:
+        print("slowest: " + ", ".join(f"{r['name']} {fmt(r['duration_s'])} ({r.get('runner') or '?'})" for r in slow))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

scripts/run_summary.py

@@ -0,0 +1,94 @@
+#!/usr/bin/env python3
+"""Writes the machine-readable run summary for the delegation runners.
+
+Called by scripts/junie-task.sh, scripts/kilo-task.sh and scripts/codex-task.sh when a run finishes. Writes one
+JSON object to <outfile> describing the run (identity, timing, exits and verdict), so
+scripts/junie-status.sh and other tools can report on finished runs without parsing logs.
+Standard library only. The runners pass the values as key=value arguments, so bash never
+quotes them itself and odd values (spaces, special characters) cannot break the output.
+
+Usage: scripts/run_summary.py <outfile> <key=value> [<key=value> ...]
+
+Keys:
+    name, runner, model, task_id, patch    str (required)
+    agent                                  str (required for runner=kilo only)
+    started, finished                      int, epoch seconds (required)
+    agent_exit, verify_exit                int (required)
+    files_changed                          int (required)
+    verdict                                verified|verify_failed|agent_failed
+
+duration_s is derived as finished - started. Unknown keys, a wrong runner or verdict, or
+a missing field are errors and nothing is written. Output is deterministic (sorted keys,
+2-space indent, trailing newline).
+"""
+from __future__ import annotations
+
+import json
+import sys
+
+STR_FIELDS = ("name", "runner", "model", "agent", "task_id", "patch", "verdict")
+INT_FIELDS = ("started", "finished", "agent_exit", "verify_exit", "files_changed")
+RUNNERS = ("junie", "kilo", "codex")
+VERDICTS = ("verified", "verify_failed", "agent_failed")
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) < 3:
+        print(f"usage: {argv[0]} <outfile> <key=value> ...", file=sys.stderr)
+        return 2
+    outfile = argv[1]
+
+    data: dict[str, object] = {}
+    for pair in argv[2:]:
+        key, sep, value = pair.partition("=")
+        if not sep:
+            print(f"error: expected key=value, got {pair!r}", file=sys.stderr)
+            return 2
+        if key in INT_FIELDS:
+            try:
+                data[key] = int(value)
+            except ValueError:
+                print(f"error: field {key!r} must be an integer, got {value!r}", file=sys.stderr)
+                return 2
+        elif key in STR_FIELDS:
+            data[key] = value
+        else:
+            print(f"error: unknown field {key!r}", file=sys.stderr)
+            return 2
+
+    required = (set(STR_FIELDS) | set(INT_FIELDS)) - {"agent"}
+    missing = sorted(required - set(data))
+    if missing:
+        print(f"error: missing fields: {', '.join(missing)}", file=sys.stderr)
+        return 2
+
+    if data["runner"] not in RUNNERS:
+        print(f"error: runner must be one of {', '.join(RUNNERS)}, got {data['runner']!r}", file=sys.stderr)
+        return 2
+    if data["verdict"] not in VERDICTS:
+        print(f"error: verdict must be one of {', '.join(VERDICTS)}, got {data['verdict']!r}", file=sys.stderr)
+        return 2
+    if data["runner"] == "kilo" and "agent" not in data:
+        print("error: field 'agent' is required for runner=kilo", file=sys.stderr)
+        return 2
+    if data["runner"] == "junie" and "agent" in data:
+        print("error: field 'agent' is only allowed for runner=kilo", file=sys.stderr)
+        return 2
+
+    duration = int(data["finished"]) - int(data["started"])  # type: ignore[arg-type]
+    if duration < 0:
+        print("error: finished is before started", file=sys.stderr)
+        return 2
+    if int(data["files_changed"]) < 0:  # type: ignore[arg-type]
+        print("error: files_changed must be >= 0", file=sys.stderr)
+        return 2
+    data["duration_s"] = duration
+
+    with open(outfile, "w", encoding="utf-8") as fh:
+        json.dump(data, fh, sort_keys=True, indent=2)
+        fh.write("\n")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))