@nbardy/oompa 0.5.1 → 0.7.0

package/README.md

@@ -39,7 +39,7 @@ This repo has a fleshed out version of the idea. The oompa loompas are organized
 
 - **Different worker types** — small models for fast execution, big models for planning
 - **Separate review model** — use a smart model to check work before merging
-- **Mixed harnesses** — combine Claude and Codex workers in one swarm
+- **Mixed harnesses** — combine Claude, Codex, and Opencode workers in one swarm
 - **Self-directed tasks** — workers create and claim tasks from shared folders
 
 ### Architecture
@@ -84,20 +84,22 @@ This repo has a fleshed out version of the idea. The oompa loompas are organized
 {
   "workers": [
     {"model": "claude:opus", "prompt": ["config/prompts/planner.md"], "iterations": 5, "count": 1},
-    {"model": "codex:gpt-5.3-codex:medium", "prompt": ["config/prompts/executor.md"], "iterations": 10, "count": 3, "can_plan": false}
+    {"model": "codex:gpt-5.3-codex:medium", "prompt": ["config/prompts/executor.md"], "iterations": 10, "count": 2, "can_plan": false},
+    {"model": "opencode:openai/gpt-5", "prompt": ["config/prompts/executor.md"], "iterations": 10, "count": 1, "can_plan": false}
   ]
 }
 ```
 
 This spawns:
 - **1 planner** (opus) — reads spec, explores codebase, creates/refines tasks
-- **3 executors** (gpt-5.3-codex, medium reasoning) — claims and executes tasks fast
+- **2 codex executors** (gpt-5.3-codex, medium reasoning) — claims and executes tasks fast
+- **1 opencode executor** (openai/gpt-5) — same task loop via `opencode run`
 
 #### Worker fields
 
 | Field | Required | Description |
 |-------|----------|-------------|
-| `model` | yes | `harness:model` or `harness:model:reasoning` (e.g. `codex:gpt-5.3-codex:medium`, `claude:opus`) |
+| `model` | yes | `harness:model` or `harness:model:reasoning` (e.g. `codex:gpt-5.3-codex:medium`, `claude:opus`, `opencode:openai/gpt-5`) |
 | `prompt` | no | String or array of paths — concatenated into one prompt |
 | `iterations` | no | Max iterations per worker (default: 10) |
 | `count` | no | Number of workers with this config (default: 1) |
@@ -111,7 +113,7 @@ This spawns:
 {
   "workers": [
     {"model": "claude:opus-4.5", "prompt": ["prompts/base.md", "prompts/architect.md"], "count": 1},
-    {"model": "codex:codex-5.2-mini", "prompt": ["prompts/base.md", "prompts/frontend.md"], "count": 2},
+    {"model": "opencode:openai/gpt-5-mini", "prompt": ["prompts/base.md", "prompts/frontend.md"], "count": 2},
     {"model": "codex:codex-5.2-mini", "prompt": ["prompts/base.md", "prompts/backend.md"], "count": 2}
   ]
 }
@@ -202,21 +204,28 @@ oompa help                  # Show all commands
 
 `./swarm.bb ...` works the same when running from a source checkout.
 
+## Opencode Harness
+
+`opencode` workers use one-shot `opencode run --format json` calls with the same worker prompt tagging:
+
+- First prompt line still starts with `[oompa:<swarmId>:<workerId>]`
+- `-m/--model` is passed when a worker model is configured
+- First iteration starts without `--session`; the worker captures `sessionID` from that exact run output
+- On resumed iterations, workers pass `-s/--session <captured-id> --continue`
+- Oompa does not call `opencode session list` to guess a "latest" session
+- Worker completion markers (`COMPLETE_AND_READY_FOR_MERGE`, `__DONE__`) are evaluated from extracted text events, preserving existing done/merge behavior
+- Optional attach mode: set `OOMPA_OPENCODE_ATTACH` (or `OPENCODE_ATTACH`) to add `--attach <url>`
+
 ## Worker Conversation Persistence
 
-If `codex-persist` is available, each worker writes its prompt/response messages
-to a per-worker session file for external UIs (for example worker panes in
-`claude-web-view`).
+Workers rely on each CLI's native session persistence (no custom mirror writer):
 
-- Session ID: random lowercase UUID per iteration (one file per iteration)
-- First user message tag format: `[oompa:<swarmId>:<workerId>]`
-- CWD passed to `codex-persist` is the worker worktree absolute path
-- Codex workers use `codex-persist` writes; Claude workers use native `--session-id`
+- Codex: native rollouts under `~/.codex/sessions/YYYY/MM/DD/*.jsonl`
+- Claude: native project sessions under `~/.claude/projects/*/*.jsonl`
+- Opencode: native session store managed by `opencode`
 
-Resolution order for the CLI command:
-1. `CODEX_PERSIST_BIN` (if set)
-2. `codex-persist` on `PATH`
-3. `node ~/git/codex-persist/dist/cli.js`
+Oompa still tags the first prompt line with `[oompa:<swarmId>:<workerId>]`
+so downstream UIs can identify and group worker conversations.
 
 ## Requirements
 
@@ -226,6 +235,7 @@ Resolution order for the CLI command:
 - One of:
   - [Claude CLI](https://github.com/anthropics/claude-cli)
   - [Codex CLI](https://github.com/openai/codex)
+  - [Opencode CLI](https://github.com/sst/opencode)
 
 ## License
 

package/agentnet/src/agentnet/agent.clj

@@ -12,7 +12,8 @@
 
    Supported Backends:
      :codex  - OpenAI Codex CLI (codex exec)
-     :claude - Anthropic Claude CLI (claude -p)"
+     :claude - Anthropic Claude CLI (claude -p)
+     :opencode - opencode CLI (opencode run)"
   (:require [agentnet.schema :as schema]
             [babashka.process :as process]
             [clojure.java.io :as io]
@@ -71,6 +72,22 @@
     model (into ["--model" model])
     true (conj "--dangerously-skip-permissions")))
 
+(defn- opencode-attach-url
+  "Optional opencode server URL for run --attach mode."
+  []
+  (let [url (or (System/getenv "OOMPA_OPENCODE_ATTACH")
+                (System/getenv "OPENCODE_ATTACH"))]
+    (when (and url (not (str/blank? url)))
+      url)))
+
+(defmethod build-command :opencode
+  [_ {:keys [model]} prompt cwd]
+  (let [attach (opencode-attach-url)]
+    (cond-> ["opencode" "run"]
+      model (into ["-m" model])
+      attach (into ["--attach" attach])
+      true (conj prompt))))
+
 (defmethod build-command :default
   [agent-type _ _ _]
   (throw (ex-info (str "Unknown agent type: " agent-type)
@@ -130,6 +147,11 @@
   [output]
   (boolean (re-find #"__DONE__" (or output ""))))
 
+(defn merge-signal?
+  "Check if output contains COMPLETE_AND_READY_FOR_MERGE signal"
+  [output]
+  (boolean (re-find #"COMPLETE_AND_READY_FOR_MERGE" (or output ""))))
+
 (defn- extract-comments
   "Extract bullet-point comments from output"
   [output]
@@ -264,6 +286,7 @@
   (let [cmd (case agent-type
               :codex ["codex" "--version"]
               :claude ["claude" "--version"]
+              :opencode ["opencode" "--version"]
               ["echo" "unknown"])]
     (try
       (let [{:keys [exit]} (process/sh cmd {:out :string :err :string})]

package/agentnet/src/agentnet/cli.clj

@@ -5,7 +5,7 @@
      ./swarm.bb run                                    # Run all tasks once
      ./swarm.bb run --workers 4                        # With 4 parallel workers
      ./swarm.bb loop 20 --harness claude               # 20 iterations with Claude
-     ./swarm.bb loop --workers claude:5 codex:4 --iterations 20  # Mixed harnesses
+     ./swarm.bb loop --workers claude:5 opencode:2 --iterations 20  # Mixed harnesses
      ./swarm.bb swarm oompa.json                       # Multi-model from config
      ./swarm.bb prompt \"...\"                          # Ad-hoc task
      ./swarm.bb status                                 # Show last run
@@ -16,6 +16,7 @@
             [agentnet.worker :as worker]
             [agentnet.tasks :as tasks]
             [agentnet.agent :as agent]
+            [agentnet.runs :as runs]
             [babashka.process :as process]
             [clojure.string :as str]
             [clojure.java.io :as io]
@@ -30,20 +31,22 @@
     (Integer/parseInt s)
     (catch Exception _ default)))
 
+(def ^:private harnesses #{:codex :claude :opencode})
+
 (defn- make-swarm-id
   "Generate a short run-level swarm ID."
   []
   (subs (str (java.util.UUID/randomUUID)) 0 8))
 
 (defn- parse-worker-spec
-  "Parse 'harness:count' into {:harness :claude, :count 5}.
+  "Parse 'harness:count' into {:harness :opencode, :count 5}.
    Throws on invalid format."
   [s]
   (let [[harness count-str] (str/split s #":" 2)
         h (keyword harness)
         cnt (parse-int count-str 0)]
-    (when-not (#{:codex :claude} h)
-      (throw (ex-info (str "Unknown harness in worker spec: " s ". Use 'codex:N' or 'claude:N'") {})))
+    (when-not (harnesses h)
+      (throw (ex-info (str "Unknown harness in worker spec: " s ". Use 'codex:N', 'claude:N', or 'opencode:N'") {})))
     (when (zero? cnt)
       (throw (ex-info (str "Invalid count in worker spec: " s ". Use format 'harness:count'") {})))
     {:harness h :count cnt}))
@@ -80,7 +83,7 @@
         (= arg "--workers")
         (let [next-arg (second remaining)]
           (if (worker-spec? next-arg)
-            ;; Collect all worker specs: --workers claude:5 codex:4
+            ;; Collect all worker specs: --workers claude:5 opencode:2
             (let [[specs rest] (collect-worker-specs (next remaining))]
               (recur (assoc opts :worker-specs specs) rest))
             ;; Simple count: --workers 4
@@ -93,8 +96,8 @@
 
         (= arg "--harness")
         (let [h (keyword (second remaining))]
-          (when-not (#{:codex :claude} h)
-            (throw (ex-info (str "Unknown harness: " (second remaining) ". Use 'codex' or 'claude'") {})))
+          (when-not (harnesses h)
+            (throw (ex-info (str "Unknown harness: " (second remaining) ". Use 'codex', 'claude', or 'opencode'") {})))
           (recur (assoc opts :harness h)
                  (nnext remaining)))
 
@@ -135,6 +138,21 @@
 
 (declare cmd-swarm parse-model-string)
 
+(defn- check-git-clean!
+  "Abort if git working tree is dirty. Dirty index causes merge conflicts
+   and wasted worker iterations."
+  []
+  (let [result (process/sh ["git" "status" "--porcelain"]
+                           {:out :string :err :string})
+        output (str/trim (:out result))]
+    (when (and (zero? (:exit result)) (not (str/blank? output)))
+      (println "ERROR: Git working tree is dirty. Resolve before running swarm.")
+      (println)
+      (println output)
+      (println)
+      (println "Run 'git stash' or 'git commit' first.")
+      (System/exit 1))))
+
 (defn- probe-model
   "Send 'say ok' to a model via its harness CLI. Returns true if model responds.
    Claude hangs without /dev/null stdin when spawned from bb."
@@ -142,7 +160,8 @@
   (try
     (let [cmd (case harness
                 :claude ["claude" "--model" model "-p" "[oompa:probe] say ok" "--max-turns" "1"]
-                :codex  ["codex" "exec" "--dangerously-bypass-approvals-and-sandbox" "--skip-git-repo-check" "--model" model "--" "[oompa:probe] say ok"])
+                :codex  ["codex" "exec" "--dangerously-bypass-approvals-and-sandbox" "--skip-git-repo-check" "--model" model "--" "[oompa:probe] say ok"]
+                :opencode ["opencode" "run" "-m" model "[oompa:probe] say ok"])
           null-in (io/input-stream (io/file "/dev/null"))
           proc (process/process cmd {:out :string :err :string :in null-in})
           result (deref proc 30000 :timeout)]
@@ -187,7 +206,7 @@
     (cmd-swarm opts (or (seq args) ["oompa.json"]))
     (let [swarm-id (make-swarm-id)]
       (if-let [specs (:worker-specs opts)]
-        ;; Mixed worker specs: --workers claude:5 codex:4
+        ;; Mixed worker specs: --workers claude:5 opencode:2
         (let [workers (mapcat
                         (fn [spec]
                           (let [{:keys [harness count]} spec]
@@ -219,7 +238,7 @@
                        (:iterations opts)
                        20)]
     (if-let [specs (:worker-specs opts)]
-      ;; Mixed worker specs: --workers claude:5 codex:4
+      ;; Mixed worker specs: --workers claude:5 opencode:2
       (let [workers (mapcat
                       (fn [spec]
                         (let [{:keys [harness count]} spec]
@@ -265,25 +284,65 @@
       (orchestrator/run-once! opts))))
 
 (defn cmd-status
-  "Show status of last run"
+  "Show status of last run — reads structured runs/{swarm-id}/ data."
   [opts args]
-  (let [runs-dir (io/file "runs")
-        files (when (.exists runs-dir)
-                (->> (.listFiles runs-dir)
-                     (filter #(.isFile %))
-                     (sort-by #(.lastModified %) >)))]
-    (if-let [latest (first files)]
-      (do
-        (println (format "Latest run: %s" (.getName latest)))
+  (let [run-ids (runs/list-runs)]
+    (if (seq run-ids)
+      (let [swarm-id (or (first args) (first run-ids))
+            run-log (runs/read-run-log swarm-id)
+            summary (runs/read-summary swarm-id)
+            reviews (runs/list-reviews swarm-id)]
+        (println (format "Swarm: %s" swarm-id))
+        (when run-log
+          (println (format "  Started: %s" (:started-at run-log)))
+          (println (format "  Config:  %s" (or (:config-file run-log) "N/A")))
+          (println (format "  Workers: %d" (count (:workers run-log)))))
         (println)
-        (with-open [r (io/reader latest)]
-          (let [entries (mapv #(json/parse-string % true) (line-seq r))
-                by-status (group-by :status entries)]
-            (doseq [[status tasks] (sort-by first by-status)]
-              (println (format "%s: %d" (name status) (count tasks))))
+        (if summary
+          (do
+            (println (format "Summary (finished %s):" (:finished-at summary)))
+            (println (format "  Total completed: %d/%d iterations"
+                             (:total-completed summary) (:total-iterations summary)))
+            (println (format "  Status counts: %s" (pr-str (:status-counts summary))))
             (println)
-            (println (format "Total: %d tasks" (count entries))))))
-      (println "No runs found."))))
+            (println "Per-worker:")
+            (doseq [w (:workers summary)]
+              (println (format "  [%s] %s:%s — %s, %d completed, %d merges, %d rejections, %d errors, %d review rounds"
+                               (:id w)
+                               (or (:harness w) "unknown")
+                               (or (:model w) "default")
+                               (or (:status w) "unknown")
+                               (or (:completed w) 0)
+                               (or (:merges w) 0)
+                               (or (:rejections w) 0)
+                               (or (:errors w) 0)
+                               (or (:review-rounds-total w) 0)))))
+          (println "  (still running — no summary yet)"))
+        (when (seq reviews)
+          (println)
+          (println (format "Reviews: %d total" (count reviews)))
+          (doseq [r reviews]
+            (println (format "  %s-i%d-r%d: %s"
+                             (:worker-id r) (:iteration r) (:round r)
+                             (:verdict r))))))
+      ;; Fall back to legacy JSONL format
+      (let [runs-dir (io/file "runs")
+            files (when (.exists runs-dir)
+                    (->> (.listFiles runs-dir)
+                         (filter #(.isFile %))
+                         (sort-by #(.lastModified %) >)))]
+        (if-let [latest (first files)]
+          (do
+            (println (format "Latest run (legacy): %s" (.getName latest)))
+            (println)
+            (with-open [r (io/reader latest)]
+              (let [entries (mapv #(json/parse-string % true) (line-seq r))
+                    by-status (group-by :status entries)]
+                (doseq [[status tasks] (sort-by first by-status)]
+                  (println (format "%s: %d" (name status) (count tasks))))
+                (println)
+                (println (format "Total: %d tasks" (count entries))))))
+          (println "No runs found."))))))
 
 (defn cmd-worktrees
   "List worktree status"
@@ -323,7 +382,7 @@
   "Check if agent backends are available"
   [opts args]
   (println "Checking agent backends...")
-  (doseq [agent-type [:codex :claude]]
+  (doseq [agent-type [:codex :claude :opencode]]
     (let [available? (agent/check-available agent-type)]
       (println (format "  %s: %s"
                        (name agent-type)
@@ -354,14 +413,48 @@
       (println "{")
       (println "  \"workers\": [")
       (println "    {\"model\": \"codex:gpt-5.3-codex:medium\", \"prompt\": \"prompts/executor.md\", \"iterations\": 10, \"count\": 3, \"can_plan\": false},")
-      (println "    {\"model\": \"claude:opus\", \"prompt\": [\"prompts/base.md\", \"prompts/planner.md\"], \"count\": 1}")
+      (println "    {\"model\": \"claude:opus\", \"prompt\": [\"prompts/base.md\", \"prompts/planner.md\"], \"count\": 1},")
+      (println "    {\"model\": \"opencode:openai/gpt-5\", \"prompt\": [\"prompts/executor.md\"], \"count\": 1}")
       (println "  ]")
       (println "}")
       (println)
       (println "prompt: string or array of paths — concatenated into one prompt.")
       (System/exit 1))
+    ;; Preflight: abort if git is dirty to prevent merge conflicts
+    (check-git-clean!)
+
     (let [config (json/parse-string (slurp f) true)
-          review-model (some-> (:review_model config) parse-model-string)
+          ;; Parse reviewer config — supports both formats:
+          ;; Legacy: {"review_model": "harness:model:reasoning"}
+          ;; New:    {"reviewer": {"model": "harness:model:reasoning", "prompt": ["path.md"]}}
+          reviewer-config (:reviewer config)
+          review-parsed (cond
+                          reviewer-config
+                          (let [parsed (parse-model-string (:model reviewer-config))
+                                prompts (let [p (:prompt reviewer-config)]
+                                          (cond (vector? p) p
+                                                (string? p) [p]
+                                                :else []))]
+                            (assoc parsed :prompts prompts))
+
+                          (:review_model config)
+                          (parse-model-string (:review_model config))
+
+                          :else nil)
+
+          ;; Parse planner config — optional dedicated planner
+          ;; Runs in project root, no worktree/review/merge, respects max_pending backpressure
+          planner-config (:planner config)
+          planner-parsed (when planner-config
+                           (let [parsed (parse-model-string (:model planner-config))
+                                 prompts (let [p (:prompt planner-config)]
+                                           (cond (vector? p) p
+                                                 (string? p) [p]
+                                                 :else []))]
+                             (assoc parsed
+                                    :prompts prompts
+                                    :max-pending (or (:max_pending planner-config) 10))))
+
           worker-configs (:workers config)
 
           ;; Expand worker configs by count
@@ -383,14 +476,28 @@
                            :iterations (or (:iterations wc) 10)
                            :prompts (:prompt wc)
                            :can-plan (:can_plan wc)
-                           :review-harness (:harness review-model)
-                           :review-model (:model review-model)})))
+                           :review-harness (:harness review-parsed)
+                           :review-model (:model review-parsed)
+                           :review-prompts (:prompts review-parsed)})))
                     expanded-workers)]
 
       (println (format "Swarm config from %s:" config-file))
       (println (format "  Swarm ID: %s" swarm-id))
-      (when review-model
-        (println (format "  Review: %s:%s" (name (:harness review-model)) (:model review-model))))
+      (when planner-parsed
+        (println (format "  Planner: %s:%s (max_pending: %d%s)"
+                         (name (:harness planner-parsed))
+                         (:model planner-parsed)
+                         (:max-pending planner-parsed)
+                         (if (seq (:prompts planner-parsed))
+                           (str ", prompts: " (str/join ", " (:prompts planner-parsed)))
+                           ""))))
+      (when review-parsed
+        (println (format "  Reviewer: %s:%s%s"
+                         (name (:harness review-parsed))
+                         (:model review-parsed)
+                         (if (seq (:prompts review-parsed))
+                           (str " (prompts: " (str/join ", " (:prompts review-parsed)) ")")
+                           ""))))
       (println (format "  Workers: %d total" (count workers)))
       (doseq [[idx wc] (map-indexed vector worker-configs)]
         (let [{:keys [harness model reasoning]} (parse-model-string (:model wc))]
@@ -404,7 +511,27 @@
       (println)
 
       ;; Preflight: probe each unique model before launching workers
-      (validate-models! worker-configs review-model)
+      ;; Include planner model in validation if configured
+      (validate-models! (cond-> worker-configs
+                          planner-config (conj planner-config))
+                        review-parsed)
+
+      ;; Write run log to runs/{swarm-id}/run.edn
+      (runs/write-run-log! swarm-id
+                           {:workers workers
+                            :planner-config planner-parsed
+                            :reviewer-config review-parsed
+                            :config-file config-file})
+      (println (format "\nRun log written to runs/%s/run.edn" swarm-id))
+
+      ;; Run planner if configured — synchronously before workers
+      (when planner-parsed
+        (println)
+        (println (format "  Planner: %s:%s (max_pending: %d)"
+                         (name (:harness planner-parsed))
+                         (:model planner-parsed)
+                         (:max-pending planner-parsed)))
+        (worker/run-planner! (assoc planner-parsed :swarm-id swarm-id)))
 
       ;; Run workers using new worker module
       (worker/run-workers! workers))))
@@ -450,16 +577,16 @@
   (println)
   (println "Options:")
   (println "  --workers N              Number of parallel workers (default: 2)")
-  (println "  --workers H:N [H:N ...]  Mixed workers by harness (e.g., claude:5 codex:4)")
+  (println "  --workers H:N [H:N ...]  Mixed workers by harness (e.g., claude:5 opencode:2)")
   (println "  --iterations N           Number of iterations per worker (default: 1)")
-  (println "  --harness {codex,claude} Agent harness to use (default: codex)")
-  (println "  --model MODEL            Model to use (e.g., codex-5.2, opus-4.5)")
+  (println "  --harness {codex,claude,opencode} Agent harness to use (default: codex)")
+  (println "  --model MODEL            Model to use (e.g., codex-5.2, opus-4.5, openai/gpt-5)")
   (println "  --dry-run                Skip actual merges")
   (println "  --keep-worktrees         Don't cleanup worktrees after run")
   (println)
   (println "Examples:")
   (println "  ./swarm.bb loop 10 --harness codex --model gpt-5.3-codex --workers 3")
-  (println "  ./swarm.bb loop --workers claude:5 codex:4 --iterations 20")
+  (println "  ./swarm.bb loop --workers claude:5 opencode:2 --iterations 20")
   (println "  ./swarm.bb swarm oompa.json  # Run multi-model config"))
 
 ;; =============================================================================

package/agentnet/src/agentnet/orchestrator.clj

@@ -325,7 +325,7 @@
   "Convenience: create orchestrator, run, save log, shutdown.
 
    Arguments:
-     opts - {:workers N, :harness :codex|:claude, :model string,
+     opts - {:workers N, :harness :codex|:claude|:opencode, :model string,
              :review-harness keyword, :review-model string,
              :custom-prompt string, :dry-run bool}
 

package/agentnet/src/agentnet/runs.clj

@@ -0,0 +1,165 @@
+(ns agentnet.runs
+  "Structured persistence for swarm runs.
+
+   Layout:
+     runs/{swarm-id}/
+       run.json          — start time, worker configs, planner output
+       summary.json      — final metrics per worker, aggregate stats
+       reviews/
+         {worker-id}-i{N}-r{round}.json  — per-iteration review log
+
+   Written as JSON for easy consumption by claude-web-view and CLI.
+   All writes are atomic (write to .tmp, rename) to avoid partial reads."
+  (:require [clojure.java.io :as io]
+            [clojure.string :as str]
+            [cheshire.core :as json]))
+
+;; =============================================================================
+;; Paths
+;; =============================================================================
+
+(def ^:const RUNS_ROOT "runs")
+
+(defn- run-dir [swarm-id]
+  (str RUNS_ROOT "/" swarm-id))
+
+(defn- reviews-dir [swarm-id]
+  (str (run-dir swarm-id) "/reviews"))
+
+(defn- ensure-run-dirs! [swarm-id]
+  (.mkdirs (io/file (reviews-dir swarm-id))))
+
+;; =============================================================================
+;; Atomic Write
+;; =============================================================================
+
+(defn- write-json!
+  "Write JSON data atomically: write to .tmp, rename to final path."
+  [path data]
+  (let [f (io/file path)
+        tmp (io/file (str path ".tmp"))]
+    (.mkdirs (.getParentFile f))
+    (spit tmp (json/generate-string data {:pretty true}))
+    (.renameTo tmp f)))
+
+;; =============================================================================
+;; Run Log — written at swarm start
+;; =============================================================================
+
+(defn write-run-log!
+  "Write the initial run log when a swarm starts.
+   Contains: start time, worker configs, planner output, swarm metadata."
+  [swarm-id {:keys [workers planner-config reviewer-config config-file]}]
+  (ensure-run-dirs! swarm-id)
+  (write-json! (str (run-dir swarm-id) "/run.json")
+               {:swarm-id swarm-id
+                :started-at (str (java.time.Instant/now))
+                :config-file config-file
+                :workers (mapv (fn [w]
+                                 {:id (:id w)
+                                  :harness (name (:harness w))
+                                  :model (:model w)
+                                  :reasoning (:reasoning w)
+                                  :iterations (:iterations w)
+                                  :can-plan (:can-plan w)
+                                  :prompts (:prompts w)})
+                               workers)
+                :planner (when planner-config
+                           {:harness (name (:harness planner-config))
+                            :model (:model planner-config)
+                            :prompts (:prompts planner-config)
+                            :max-pending (:max-pending planner-config)})
+                :reviewer (when reviewer-config
+                            {:harness (name (:harness reviewer-config))
+                             :model (:model reviewer-config)
+                             :prompts (:prompts reviewer-config)})}))
+
+;; =============================================================================
+;; Review Log — written after each review round
+;; =============================================================================
+
+(defn write-review-log!
+  "Write a review log for one iteration of a worker.
+   Contains: verdict, round number, full reviewer output, diff file list."
+  [swarm-id worker-id iteration round
+   {:keys [verdict output diff-files]}]
+  (ensure-run-dirs! swarm-id)
+  (let [filename (format "%s-i%d-r%d.json" worker-id iteration round)]
+    (write-json! (str (reviews-dir swarm-id) "/" filename)
+                 {:worker-id worker-id
+                  :iteration iteration
+                  :round round
+                  :verdict (name verdict)
+                  :timestamp (str (java.time.Instant/now))
+                  :output output
+                  :diff-files (vec diff-files)})))
+
+;; =============================================================================
+;; Swarm Summary — written at swarm end
+;; =============================================================================
+
+(defn write-summary!
+  "Write the final swarm summary after all workers complete.
+   Contains: per-worker stats and aggregate metrics."
+  [swarm-id worker-results]
+  (let [total-completed (reduce + 0 (map :completed worker-results))
+        total-iterations (reduce + 0 (map :iterations worker-results))
+        statuses (frequencies (map #(name (:status %)) worker-results))
+        per-worker (mapv (fn [w]
+                           {:id (:id w)
+                            :harness (name (:harness w))
+                            :model (:model w)
+                            :status (name (:status w))
+                            :completed (:completed w)
+                            :iterations (:iterations w)
+                            :merges (or (:merges w) 0)
+                            :rejections (or (:rejections w) 0)
+                            :errors (or (:errors w) 0)
+                            :review-rounds-total (or (:review-rounds-total w) 0)})
+                         worker-results)]
+    (write-json! (str (run-dir swarm-id) "/summary.json")
+                 {:swarm-id swarm-id
+                  :finished-at (str (java.time.Instant/now))
+                  :total-workers (count worker-results)
+                  :total-completed total-completed
+                  :total-iterations total-iterations
+                  :status-counts statuses
+                  :workers per-worker})))
+
+;; =============================================================================
+;; Read helpers (for cmd-status, dashboards)
+;; =============================================================================
+
+(defn list-runs
+  "List all swarm run directories, newest first."
+  []
+  (let [d (io/file RUNS_ROOT)]
+    (when (.exists d)
+      (->> (.listFiles d)
+           (filter #(.isDirectory %))
+           (sort-by #(.lastModified %) >)
+           (mapv #(.getName %))))))
+
+(defn read-run-log
+  "Read run.json for a swarm."
+  [swarm-id]
+  (let [f (io/file (str (run-dir swarm-id) "/run.json"))]
+    (when (.exists f)
+      (json/parse-string (slurp f) true))))
+
+(defn read-summary
+  "Read summary.json for a swarm."
+  [swarm-id]
+  (let [f (io/file (str (run-dir swarm-id) "/summary.json"))]
+    (when (.exists f)
+      (json/parse-string (slurp f) true))))
+
+(defn list-reviews
+  "List all review logs for a swarm, sorted by filename."
+  [swarm-id]
+  (let [d (io/file (reviews-dir swarm-id))]
+    (when (.exists d)
+      (->> (.listFiles d)
+           (filter #(str/ends-with? (.getName %) ".json"))
+           (sort-by #(.getName %))
+           (mapv (fn [f] (json/parse-string (slurp f) true)))))))