@nbardy/oompa 0.7.0 → 0.7.2

package/agentnet/src/agentnet/cli.clj

@@ -2,8 +2,8 @@
   "Command-line interface for AgentNet orchestrator.
 
    Usage:
-     ./swarm.bb run                                    # Run all tasks once
-     ./swarm.bb run --workers 4                        # With 4 parallel workers
+     ./swarm.bb run                                    # Run swarm from config (oompa.json)
+     ./swarm.bb run --detach --config oompa.json       # Run in background with startup validation
      ./swarm.bb loop 20 --harness claude               # 20 iterations with Claude
      ./swarm.bb loop --workers claude:5 opencode:2 --iterations 20  # Mixed harnesses
      ./swarm.bb swarm oompa.json                       # Multi-model from config
@@ -16,6 +16,7 @@
             [agentnet.worker :as worker]
             [agentnet.tasks :as tasks]
             [agentnet.agent :as agent]
+            [agentnet.harness :as harness]
             [agentnet.runs :as runs]
             [babashka.process :as process]
             [clojure.string :as str]
@@ -31,7 +32,7 @@
     (Integer/parseInt s)
     (catch Exception _ default)))
 
-(def ^:private harnesses #{:codex :claude :opencode})
+(def ^:private harnesses (harness/known-harnesses))
 
 (defn- make-swarm-id
   "Generate a short run-level swarm ID."
@@ -45,8 +46,8 @@
   (let [[harness count-str] (str/split s #":" 2)
         h (keyword harness)
         cnt (parse-int count-str 0)]
-    (when-not (harnesses h)
-      (throw (ex-info (str "Unknown harness in worker spec: " s ". Use 'codex:N', 'claude:N', or 'opencode:N'") {})))
+    (when-not (harness/valid-harness? h)
+      (throw (ex-info (str "Unknown harness in worker spec: " s ". Known: " (str/join ", " (map name (sort harnesses)))) {})))
     (when (zero? cnt)
       (throw (ex-info (str "Invalid count in worker spec: " s ". Use format 'harness:count'") {})))
     {:harness h :count cnt}))
@@ -74,6 +75,10 @@
                :harness :codex
                :model nil
                :dry-run false
+               :detach false
+               :all false
+               :config-file nil
+               :startup-timeout nil
                :iterations 1
                :worker-specs nil}
          remaining args]
@@ -96,8 +101,8 @@
 
         (= arg "--harness")
         (let [h (keyword (second remaining))]
-          (when-not (harnesses h)
-            (throw (ex-info (str "Unknown harness: " (second remaining) ". Use 'codex', 'claude', or 'opencode'") {})))
+          (when-not (harness/valid-harness? h)
+            (throw (ex-info (str "Unknown harness: " (second remaining) ". Known: " (str/join ", " (map name (sort harnesses)))) {})))
           (recur (assoc opts :harness h)
                  (nnext remaining)))
 
@@ -105,6 +110,28 @@
         (recur (assoc opts :model (second remaining))
                (nnext remaining))
 
+        (= arg "--config")
+        (let [config-file (second remaining)]
+          (when (str/blank? config-file)
+            (throw (ex-info "--config requires a path" {:arg arg})))
+          (recur (assoc opts :config-file config-file)
+                 (nnext remaining)))
+
+        (or (= arg "--detach") (= arg "--dettach"))
+        (recur (assoc opts :detach true)
+               (next remaining))
+
+        (= arg "--all")
+        (recur (assoc opts :all true)
+               (next remaining))
+
+        (= arg "--startup-timeout")
+        (let [seconds (parse-int (second remaining) nil)]
+          (when-not (and (number? seconds) (pos? seconds))
+            (throw (ex-info "--startup-timeout requires a positive integer (seconds)" {:arg arg})))
+          (recur (assoc opts :startup-timeout seconds)
+                 (nnext remaining)))
+
         ;; Legacy flags (still supported)
         (= arg "--claude")
         (recur (assoc opts :harness :claude)
@@ -136,34 +163,69 @@
 ;; Commands
 ;; =============================================================================
 
-(declare cmd-swarm parse-model-string)
+(declare cmd-swarm parse-model-string pid-alive?)
 
 (defn- check-git-clean!
-  "Abort if git working tree is dirty. Dirty index causes merge conflicts
-   and wasted worker iterations."
+  "Warn if git working tree is dirty. Dirty index may cause merge conflicts."
   []
   (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 "WARNING: Git working tree is dirty. You may experience merge conflicts.")
+      (println output))))
+
+(defn- check-stale-worktrees!
+  "Abort if stale oompa worktrees or branches exist from a prior run.
+   Corrupted .git/worktrees/ entries poison git worktree add for ALL workers,
+   not just the worker whose entry is stale. (See swarm af32b180 — kimi-k2.5
+   w9 went 20/20 doing nothing because w10's corrupt commondir blocked it.)"
+  []
+  ;; Prune orphaned metadata first — cleans entries whose directories are gone
+  (let [prune-result (process/sh ["git" "worktree" "prune"] {:out :string :err :string})]
+    (when-not (zero? (:exit prune-result))
+      (println "WARNING: git worktree prune failed:")
+      (println (:err prune-result))))
+  (let [;; Find .ww* directories (oompa per-iteration worktree naming convention)
+        ls-result (process/sh ["find" "." "-maxdepth" "1" "-type" "d" "-name" ".ww*"]
+                              {:out :string})
+        stale-dirs (when (zero? (:exit ls-result))
+                     (->> (str/split-lines (:out ls-result))
+                          (remove str/blank?)))
+        ;; Find oompa/* branches
+        br-result (process/sh ["git" "branch" "--list" "oompa/*"]
+                              {:out :string})
+        stale-branches (when (zero? (:exit br-result))
+                         (->> (str/split-lines (:out br-result))
+                              (map str/trim)
+                              (remove str/blank?)))]
+    (when (or (seq stale-dirs) (seq stale-branches))
+      (println "ERROR: Stale oompa worktrees detected from a prior run.")
+      (println "       Corrupt worktree metadata will cause worker failures.")
       (println)
-      (println output)
+      (when (seq stale-dirs)
+        (println (format "  Stale directories (%d):" (count stale-dirs)))
+        (doseq [d stale-dirs] (println (str "    " d))))
+      (when (seq stale-branches)
+        (println (format "  Stale branches (%d):" (count stale-branches)))
+        (doseq [b stale-branches] (println (str "    " b))))
+      (println)
+      (println "Clean up with:")
+      (println "  git worktree prune; for d in .ww*/; do git worktree remove --force \"$d\" 2>/dev/null; done; git branch --list 'oompa/*' | xargs git branch -D 2>/dev/null; rm -rf .ww*")
       (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."
-  [harness model]
+   Uses harness/build-probe-cmd for the command.
+   For stdin-based harnesses (e.g. claude), delivers the probe prompt via stdin.
+   For close-stdin harnesses, uses /dev/null to prevent hang."
+  [harness-kw model]
   (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"]
-                :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})
+    (let [cmd (harness/build-probe-cmd harness-kw model)
+          probe-prompt "[_HIDE_TEST_] say ok"
+          stdin-val (harness/process-stdin harness-kw probe-prompt)
+          proc (process/process cmd {:out :string :err :string :in stdin-val})
           result (deref proc 30000 :timeout)]
       (if (= result :timeout)
         (do (.destroyForcibly (:proc proc)) false)
@@ -172,14 +234,14 @@
 
 (defn- validate-models!
   "Probe each unique harness:model pair. Prints results and exits if any fail."
-  [worker-configs review-model]
+  [worker-configs review-models]
   (let [;; Deduplicate by harness:model only (ignore reasoning level)
-        models (cond-> (->> worker-configs
+        models (into (->> worker-configs
                             (map (fn [wc]
                                    (let [{:keys [harness model]} (parse-model-string (:model wc))]
                                      {:harness harness :model model})))
                             set)
-                 review-model (conj (select-keys review-model [:harness :model])))
+                     (map #(select-keys % [:harness :model]) review-models))
         _ (println "Validating models...")
         results (pmap (fn [{:keys [harness model]}]
                         (let [ok (probe-model harness model)]
@@ -199,36 +261,257 @@
       (System/exit 1))
     (println)))
 
-(defn cmd-run
-  "Run orchestrator — uses oompa.json if present, otherwise simple mode"
+(def ^:private default-detach-startup-timeout 20)
+
+(defn- run-id []
+  (subs (str (java.util.UUID/randomUUID)) 0 8))
+
+(defn- run-ts []
+  (.format (java.time.format.DateTimeFormatter/ofPattern "yyyyMMdd-HHmmss")
+           (java.time.LocalDateTime/now)))
+
+(defn- default-config-file
+  []
+  (cond
+    (.exists (io/file "oompa.json")) "oompa.json"
+    (.exists (io/file "oompa/oompa.json")) "oompa/oompa.json"
+    :else nil))
+
+(defn- resolve-config-file
   [opts args]
-  (if (.exists (io/file "oompa.json"))
-    (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 opencode:2
-        (let [workers (mapcat
-                        (fn [spec]
-                          (let [{:keys [harness count]} spec]
-                            (map-indexed
-                              (fn [idx _]
-                                (worker/create-worker
-                                  {:id (format "%s-%d" (name harness) idx)
-                                   :swarm-id swarm-id
-                                   :harness harness
-                                   :model (:model opts)
-                                   :iterations 1}))
-                              (range count))))
-                        specs)]
-          (println (format "Running once with mixed workers (swarm %s):" swarm-id))
-          (doseq [spec specs]
-            (println (format "  %dx %s" (:count spec) (name (:harness spec)))))
+  (let [candidate (or (:config-file opts)
+                      (first args)
+                      (default-config-file))]
+    (when candidate
+      (.getCanonicalPath (io/file candidate)))))
+
+(defn- prepare-log-file!
+  "Create oompa/logs and return absolute log path."
+  [rid]
+  (let [dir (if (.exists (io/file "oompa"))
+              (io/file "oompa" "logs")
+              (io/file "runs" "logs"))]
+    (.mkdirs dir)
+    (.getCanonicalPath (io/file dir (str (run-ts) "_" rid ".log")))))
+
+(defn- read-file-safe
+  [path]
+  (try
+    (if (.exists (io/file path))
+      (slurp path)
+      "")
+    (catch Exception _
+      "")))
+
+(defn- tail-lines
+  [text n]
+  (->> (str/split-lines (or text ""))
+       (take-last n)
+       (str/join "\n")))
+
+(defn- extract-swarm-id
+  [text]
+  (some->> text
+           (re-find #"Swarm ID:\s*([0-9a-f]{8})")
+           second))
+
+(defn- startup-diagnostic-lines
+  [text]
+  (->> (str/split-lines (or text ""))
+       (filter #(re-find #"ERROR:|FAIL|WARNING:" %))
+       (take-last 20)))
+
+(defn- print-preflight-warnings!
+  []
+  (let [agent-cli? (zero? (:exit (process/sh ["which" "agent-cli"]
+                                              {:out :string :err :string})))]
+    (when-not agent-cli?
+      (println "WARNING: 'agent-cli' is not on PATH.")
+      (println "         Model validation may report false model-access failures.")))
+  (let [dirty (process/sh ["git" "status" "--porcelain"]
+                          {:out :string :err :string})
+        lines (->> (:out dirty)
+                   str/split-lines
+                   (remove str/blank?))]
+    (when (seq lines)
+      (println (format "WARNING: Git working tree is dirty (%d changed paths)." (count lines)))
+      (println "         Swarm startup may fail until changes are committed/stashed.")
+      (doseq [line (take 20 lines)]
+        (println line))
+      (when (> (count lines) 20)
+        (println (format "... (%d total changed paths)" (count lines)))))))
+
+(defn- runtime-classpath-entry
+  "Best-effort classpath root for agentnet sources."
+  []
+  (or
+    (some-> (System/getenv "OOMPA_PACKAGE_ROOT")
+            (io/file "agentnet" "src")
+            .getCanonicalPath)
+    (->> (str/split (or (System/getProperty "java.class.path") "")
+                    (re-pattern (java.io.File/pathSeparator)))
+         (map str/trim)
+         (remove str/blank?)
+         (map io/file)
+         (filter #(.exists %))
+         (map #(.getCanonicalPath %))
+         (some #(when (str/ends-with? % (str "agentnet" java.io.File/separator "src"))
+                  %)))
+    (.getCanonicalPath (io/file "agentnet" "src"))))
+
+(defn- run-classpath
+  []
+  (runtime-classpath-entry))
+
+(defn- run-script-path
+  []
+  (if-let [pkg-root (System/getenv "OOMPA_PACKAGE_ROOT")]
+    (.getCanonicalPath (io/file pkg-root "swarm.bb"))
+    (let [cp (io/file (runtime-classpath-entry))
+          ;; cp = <repo>/agentnet/src -> <repo>/swarm.bb
+          repo-root (some-> cp .getParentFile .getParentFile)
+          candidate (when repo-root (io/file repo-root "swarm.bb"))]
+      (if (and candidate (.exists candidate))
+        (.getCanonicalPath candidate)
+        (.getCanonicalPath (io/file "swarm.bb"))))))
+
+(defn- detached-cmd
+  [opts config-file]
+  (cond-> ["nohup" "bb" "--classpath" (run-classpath) (run-script-path) "swarm"]
+    (:dry-run opts) (conj "--dry-run")
+    true (conj config-file)))
+
+(defn- spawn-detached!
+  [cmd log-file]
+  (let [log (io/file log-file)
+        pb (doto (ProcessBuilder. ^java.util.List cmd)
+             (.directory (io/file "."))
+             (.redirectInput (java.lang.ProcessBuilder$Redirect/from (io/file "/dev/null")))
+             (.redirectOutput (java.lang.ProcessBuilder$Redirect/appendTo log))
+             (.redirectError (java.lang.ProcessBuilder$Redirect/appendTo log)))
+        proc (.start pb)
+        pid (.pid proc)]
+    ;; Give spawn a short window before validation checks liveness.
+    (Thread/sleep 100)
+    pid))
+
+(defn- pid-alive?
+  [pid]
+  (zero? (:exit (process/sh ["kill" "-0" (str pid)]
+                            {:out :string :err :string}))))
+
+(defn- wait-for-startup!
+  [pid log-file timeout-sec]
+  (loop [waited 0]
+    (let [content (read-file-safe log-file)
+          started? (str/includes? content "Started event written to runs/")
+          alive? (pid-alive? pid)]
+      (cond
+        started?
+        {:status :started
+         :content content
+         :swarm-id (extract-swarm-id content)}
+
+        (not alive?)
+        {:status :failed
+         :content content}
+
+        (>= waited timeout-sec)
+        {:status :timeout
+         :content content}
+
+        :else
+        (do
+          (Thread/sleep 1000)
+          (recur (inc waited)))))))
+
+(defn- cmd-run-detached
+  [opts config-file]
+  (print-preflight-warnings!)
+  (when-not (.exists (io/file config-file))
+    (println (format "Config not found: %s" config-file))
+    (System/exit 1))
+  (let [timeout-sec (or (:startup-timeout opts)
+                        (parse-int (System/getenv "OOMPA_DETACH_STARTUP_TIMEOUT")
+                                   default-detach-startup-timeout))
+        rid (run-id)
+        log-file (prepare-log-file! rid)
+        cmd (detached-cmd opts config-file)
+        pid (spawn-detached! cmd log-file)]
+    (println (format "Config:      %s" config-file))
+    (when (:dry-run opts)
+      (println "Merge mode:  dry-run"))
+    (let [{:keys [status content swarm-id]} (wait-for-startup! pid log-file timeout-sec)]
+      (case status
+        :failed
+        (do
           (println)
-          (worker/run-workers! workers))
-        ;; Simple mode
+          (println "ERROR: Detached swarm exited during startup validation.")
+          (println "Startup log excerpt:")
+          (println (tail-lines content 120))
+          (System/exit 1))
+
+        :timeout
         (do
-          (println (format "Swarm ID: %s" swarm-id))
-          (orchestrator/run-once! (assoc opts :swarm-id swarm-id)))))))
+          (println)
+          (println (format "WARNING: Detached swarm still initializing after %ss." timeout-sec))
+          (println "Recent startup log lines:")
+          (println (tail-lines content 40)))
+
+        nil)
+      (let [diag (startup-diagnostic-lines content)]
+        (when (seq diag)
+          (println)
+          (println "Startup diagnostics:")
+          (doseq [line diag]
+            (println line))))
+      (println)
+      (println "  ┌──────────────────────────────────────────────────────────────┐")
+      (println "  │  OOMPA SWARM RUN (DETACHED)                               │")
+      (println (format "  │  Run id:   %-46s│" rid))
+      (println (format "  │  PID:      %-46s│" pid))
+      (println (format "  │  Log file: %-46s│" log-file))
+      (println (format "  │  Swarm ID: %-46s│" (or swarm-id "(pending)")))
+      (println "  └──────────────────────────────────────────────────────────────┘")
+      (println))))
+
+(defn- cmd-run-legacy
+  "Run orchestrator once from worker specs (legacy mode)."
+  [opts args]
+  (let [swarm-id (make-swarm-id)]
+    (if-let [specs (:worker-specs opts)]
+      ;; Mixed worker specs: --workers claude:5 opencode:2
+      (let [workers (mapcat
+                      (fn [spec]
+                        (let [{:keys [harness count]} spec]
+                          (map-indexed
+                            (fn [idx _]
+                              (worker/create-worker
+                                {:id (format "%s-%d" (name harness) idx)
+                                 :swarm-id swarm-id
+                                 :harness harness
+                                 :model (:model opts)
+                                 :iterations 1}))
+                            (range count))))
+                      specs)]
+        (println (format "Running once with mixed workers (swarm %s):" swarm-id))
+        (doseq [spec specs]
+          (println (format "  %dx %s" (:count spec) (name (:harness spec)))))
+        (println)
+        (worker/run-workers! workers))
+      ;; Simple mode retired — use oompa.json or --workers harness:count
+      (do
+        (println "Simple mode is no longer supported. Use oompa.json or --workers harness:count.")
+        (System/exit 1)))))
+
+(defn cmd-run
+  "Run swarm from config. Use --detach for background mode."
+  [opts args]
+  (if-let [config-file (resolve-config-file opts args)]
+    (if (:detach opts)
+      (cmd-run-detached opts config-file)
+      (cmd-swarm opts [config-file]))
+    (cmd-run-legacy opts args)))
 
 (defn cmd-loop
   "Run orchestrator N times"
@@ -257,14 +540,10 @@
           (println (format "  %dx %s" (:count spec) (name (:harness spec)))))
         (println)
         (worker/run-workers! workers))
-      ;; Simple mode: --workers N --harness X
-      (let [model-str (if (:model opts)
-                        (format " (model: %s)" (:model opts))
-                        "")]
-        (println (format "Starting %d iterations with %s harness%s..."
-                         iterations (name (:harness opts)) model-str))
-        (println (format "Swarm ID: %s" swarm-id))
-        (orchestrator/run-loop! iterations (assoc opts :swarm-id swarm-id))))))
+      ;; Simple mode retired — use oompa.json or --workers harness:count
+      (do
+        (println "Simple mode is no longer supported. Use oompa.json or --workers harness:count.")
+        (System/exit 1)))))
 
 (defn cmd-prompt
   "Run ad-hoc prompt as single task"
@@ -284,47 +563,72 @@
       (orchestrator/run-once! opts))))
 
 (defn cmd-status
-  "Show status of last run — reads structured runs/{swarm-id}/ data."
+  "Show running swarms."
   [opts args]
   (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)
-        (if summary
+      (let [running (for [id run-ids
+                          :let [started (runs/read-started id)
+                                stopped (runs/read-stopped id)
+                                pid (:pid started)]
+                          :when (and started (not stopped) pid (pid-alive? pid))]
+                      {:id id 
+                       :pid pid 
+                       :workers (count (:workers started))
+                       :work-count (count (runs/list-cycles id))})]
+        (if (seq running)
           (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 (format "Running Swarms: %d" (count running)))
+            (doseq [r running]
+              (println (format "  Swarm: %s | PID: %s | Workers: %d | Work Count: %d" 
+                               (:id r) (:pid r) (:workers r) (:work-count r)))))
+          (println "No running swarms.")))
+      (println "No swarms found."))))
+
+(defn cmd-info
+  "Show detailed information of a swarm run — reads event-sourced runs/{swarm-id}/ data."
+  [opts args]
+  (let [run-ids (runs/list-runs)]
+    (if (seq run-ids)
+      (let [target-ids (if (seq args) [(first args)] run-ids)]
+        (doseq [swarm-id target-ids]
+          (let [started (runs/read-started swarm-id)
+                stopped (runs/read-stopped swarm-id)
+                cycles (runs/list-cycles swarm-id)
+                reviews (runs/list-reviews swarm-id)]
+            (println "--------------------------------------------------")
+            (println (format "Swarm: %s" swarm-id))
+            (when started
+              (println (format "  Started: %s" (:started-at started)))
+              (println (format "  PID:     %s" (or (:pid started) "N/A")))
+              (println (format "  Config:  %s" (or (:config-file started) "N/A")))
+              (println (format "  Workers: %d" (count (:workers started)))))
             (println)
-            (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))))))
+            (if stopped
+              (println (format "Stopped: %s (reason: %s%s)"
+                               (:stopped-at stopped)
+                               (:reason stopped)
+                               (if (:error stopped)
+                                 (str ", error: " (:error stopped))
+                                 "")))
+              (println "  (still running — no stopped event yet)"))
+            (when (seq cycles)
+              (println)
+              (println (format "Cycles: %d total" (count cycles)))
+              (doseq [c cycles]
+                (println (format "  %s-c%d: %s (%dms, claimed: %s)"
+                                 (:worker-id c) (:cycle c)
+                                 (:outcome c)
+                                 (or (:duration-ms c) 0)
+                                 (str/join ", " (or (:claimed-task-ids c) []))))))
+            (when (seq reviews)
+              (println)
+              (println (format "Reviews: %d total" (count reviews)))
+              (doseq [r reviews]
+                (println (format "  %s-c%d-r%d: %s"
+                                 (:worker-id r) (:cycle r) (:round r)
+                                 (:verdict r)))))
+            (println))))
       ;; Fall back to legacy JSONL format
       (let [runs-dir (io/file "runs")
             files (when (.exists runs-dir)
@@ -344,6 +648,166 @@
                 (println (format "Total: %d tasks" (count entries))))))
           (println "No runs found."))))))
 
+(def ^:private error-outcomes
+  #{"error" "merge-failed" "rejected" "stuck"})
+
+(def ^:private terminal-run-outcomes
+  #{"merged" "rejected" "error" "merge-failed" "sync-failed" "stuck" "no-changes"})
+
+(defn- run-state
+  "Derive run lifecycle state from started/stopped events + PID liveness."
+  [started stopped]
+  (cond
+    (nil? started) "missing-started"
+    stopped (str "stopped/" (:reason stopped))
+    (pid-alive? (:pid started)) "running"
+    :else "stale"))
+
+(defn- latest-cycles-by-worker
+  "Return map of worker-id -> latest cycle entry."
+  [cycles]
+  (reduce (fn [acc c]
+            (let [wid (:worker-id c)
+                  prev (get acc wid)]
+              (if (or (nil? prev)
+                      (> (or (:cycle c) 0) (or (:cycle prev) 0)))
+                (assoc acc wid c)
+                acc)))
+          {}
+          cycles))
+
+(defn- worker-runtime
+  "Best-effort worker runtime classification for view output."
+  [worker latest-cycle worker-cycles run-state*]
+  (let [run-max (or (:runs worker) (:iterations worker) 0)
+        runs-done (count (filter #(terminal-run-outcomes (:outcome %)) worker-cycles))
+        outcome (or (:outcome latest-cycle) "-")]
+    (cond
+      (>= runs-done run-max) "completed"
+      (str/starts-with? run-state* "stopped/") "stopped"
+      (= run-state* "stale") "stale"
+      (nil? latest-cycle) "starting"
+      (= outcome "working") "working"
+      (= outcome "executor-done") "idle"
+      :else outcome)))
+
+(defn- model-label
+  [{:keys [harness model reasoning]}]
+  (str harness ":" model (when reasoning (str ":" reasoning))))
+
+(defn- run-metrics
+  "Summarize cycle metrics for a run."
+  [cycles]
+  (let [merged (count (filter #(= "merged" (:outcome %)) cycles))
+        failed (count (filter #(error-outcomes (:outcome %)) cycles))
+        claimed-all (->> cycles
+                         (mapcat #(or (:claimed-task-ids %) []))
+                         (remove str/blank?))
+        completed-ids (->> cycles
+                           (filter #(= "merged" (:outcome %)))
+                           (mapcat #(or (:claimed-task-ids %) []))
+                           (remove str/blank?)
+                           set)]
+    {:merged merged
+     :failed failed
+     :claimed (count (set claimed-all))
+     :completed (count completed-ids)}))
+
+(defn- cmd-view-one
+  [swarm-id]
+  (if-let [started (runs/read-started swarm-id)]
+    (let [stopped (runs/read-stopped swarm-id)
+          cycles (or (runs/list-cycles swarm-id) [])
+          reviews (or (runs/list-reviews swarm-id) [])
+          workers (or (:workers started) [])
+          run-state* (run-state started stopped)
+          metrics (run-metrics cycles)
+          latest-by-worker (latest-cycles-by-worker cycles)
+          cycles-by-worker (group-by :worker-id cycles)]
+      (println (format "Swarm:   %s" swarm-id))
+      (println (format "State:   %s" run-state*))
+      (println (format "Started: %s" (:started-at started)))
+      (println (format "PID:     %s" (or (:pid started) "N/A")))
+      (println (format "Config:  %s" (or (:config-file started) "N/A")))
+      (when stopped
+        (println (format "Stopped: %s" (:stopped-at stopped))))
+      (println (format "Cycles:  %d" (count cycles)))
+      (println (format "PRs:     merged=%d failed=%d" (:merged metrics) (:failed metrics)))
+      (println (format "Tasks:   claimed=%d completed=%d created=n/a"
+                       (:claimed metrics) (:completed metrics)))
+      (println (format "Reviews: %d" (count reviews)))
+      (println)
+      (println "Workers:")
+      (println "ID  | Runtime   | Runs   | Cycles  | Last Outcome   | Claimed | Model")
+      (println "----+-----------+--------+---------+----------------+---------+------------------------------")
+      (doseq [w (sort-by :id workers)]
+        (let [wid (:id w)
+              latest (get latest-by-worker wid)
+              worker-cycles (or (get cycles-by-worker wid) [])
+              run-max (or (:runs w) (:iterations w) 0)
+              runs-done (count (filter #(terminal-run-outcomes (:outcome %)) worker-cycles))
+              cycles-done (or (:cycle latest) 0)
+              runtime (worker-runtime w latest worker-cycles run-state*)
+              outcome (or (:outcome latest) "-")
+              claimed (count (or (:claimed-task-ids latest) []))]
+          (println (format "%-3s | %-9s | %4d/%-3d | %7d | %-14s | %-7d | %s"
+                           wid runtime runs-done run-max cycles-done outcome claimed (model-label w))))))
+    (do
+      (println (format "Swarm not found: %s" swarm-id))
+      (System/exit 1))))
+
+(defn cmd-list
+  "List recent swarms with liveness + activity metrics.
+   Default: 20 most recent. Use --all for full history."
+  [opts args]
+  (let [run-ids (or (runs/list-runs) [])]
+    (if-not (seq run-ids)
+      (println "No swarm runs found.")
+      (let [shown (if (:all opts) run-ids (take 20 run-ids))]
+        (println "Swarm Runs:")
+        (println "ID       | State            | PID    | Workers | Active | Cycles | Merged | Failed | Done | Started")
+        (println "---------+------------------+--------+---------+--------+--------+--------+--------+------+-------------------------")
+        (doseq [rid shown]
+          (let [started (runs/read-started rid)
+                stopped (runs/read-stopped rid)
+                cycles (or (runs/list-cycles rid) [])
+                workers (or (:workers started) [])
+                metrics (run-metrics cycles)
+                latest-by-worker (latest-cycles-by-worker cycles)
+                cycles-by-worker (group-by :worker-id cycles)
+                state* (run-state started stopped)
+                active-count (if (= state* "running")
+                               (count (filter (fn [w]
+                                                (let [wid (:id w)
+                                                      run-max (or (:runs w) (:iterations w) 0)
+                                                      runs-done (count (filter #(terminal-run-outcomes (:outcome %))
+                                                                               (or (get cycles-by-worker wid) [])))]
+                                                  (< runs-done run-max)))
+                                              workers))
+                               0)]
+            (println (format "%-8s | %-16s | %-6s | %7d | %6d | %6d | %6d | %6d | %4d | %s"
+                             rid
+                             state*
+                             (or (:pid started) "-")
+                             (count workers)
+                             active-count
+                             (count cycles)
+                             (:merged metrics)
+                             (:failed metrics)
+                             (:completed metrics)
+                             (or (:started-at started) "-")))))
+        (when (and (not (:all opts)) (> (count run-ids) 20))
+          (println (format "\nShowing 20 of %d runs. Use --all for full history." (count run-ids))))
+        (println)
+        (println "Use `oompa view <swarm-id>` for detailed single-swarm info.")))))
+
+(defn cmd-view
+  "Show detailed runtime for one swarm (default: latest run)."
+  [opts args]
+  (if-let [swarm-id (or (first args) (first (runs/list-runs)))]
+    (cmd-view-one swarm-id)
+    (println "No swarm runs found.")))
+
 (defn cmd-worktrees
   "List worktree status"
   [opts args]
@@ -382,21 +846,39 @@
   "Check if agent backends are available"
   [opts args]
   (println "Checking agent backends...")
-  (doseq [agent-type [:codex :claude :opencode]]
-    (let [available? (agent/check-available agent-type)]
+  (doseq [harness-kw (sort (harness/known-harnesses))]
+    (let [available? (harness/check-available harness-kw)]
       (println (format "  %s: %s"
-                       (name agent-type)
+                       (name harness-kw)
                        (if available? "✓ available" "✗ not found"))))))
 
+(def ^:private reasoning-variants
+  #{"minimal" "low" "medium" "high" "max" "xhigh"})
+
 (defn- parse-model-string
   "Parse model string into {:harness :model :reasoning}.
-   Formats: 'harness:model', 'harness:model:reasoning', or just 'model'."
+
+   Supported formats:
+   - harness:model
+   - harness:model:reasoning (if reasoning is in reasoning-variants)
+   - model (defaults harness to :codex)
+
+   Note: model identifiers may contain ':' (for example openrouter/...:free).
+   Those suffixes are preserved in :model if not a known reasoning variant."
   [s]
   (if (and s (str/includes? s ":"))
-    (let [parts (str/split s #":" 3)]
-      (case (count parts)
-        2 {:harness (keyword (first parts)) :model (second parts)}
-        3 {:harness (keyword (first parts)) :model (second parts) :reasoning (nth parts 2)}
+    (let [[harness-str rest*] (str/split s #":" 2)
+          harness (keyword harness-str)]
+      (if (harness/valid-harness? harness)
+        ;; Check for reasoning suffix for any valid harness
+        (if-let [idx (str/last-index-of rest* ":")]
+          (let [model* (subs rest* 0 idx)
+                reasoning* (subs rest* (inc idx))]
+            (if (contains? reasoning-variants reasoning*)
+              {:harness harness :model model* :reasoning reasoning*}
+              {:harness harness :model rest*}))
+          {:harness harness :model rest*})
+        ;; Not a known harness prefix, treat as raw model on default harness.
         {:harness :codex :model s}))
     {:harness :codex :model s}))
 
@@ -414,7 +896,7 @@
       (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\": \"opencode:openai/gpt-5\", \"prompt\": [\"prompts/executor.md\"], \"count\": 1}")
+      (println "    {\"model\": \"gemini:gemini-3-pro-preview\", \"prompt\": [\"prompts/executor.md\"], \"count\": 1}")
       (println "  ]")
       (println "}")
       (println)
@@ -422,25 +904,21 @@
       (System/exit 1))
     ;; Preflight: abort if git is dirty to prevent merge conflicts
     (check-git-clean!)
+    ;; Preflight: abort if stale worktrees from prior runs would poison git
+    (check-stale-worktrees!)
 
     (let [config (json/parse-string (slurp f) true)
           ;; 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)
+          generic-reviewers (cond
+                              (:review_models config)
+                              (mapv parse-model-string (:review_models config))
+                              
+                              (:review_model config)
+                              [(parse-model-string (:review_model config))]
+                              
+                              :else [])
 
           ;; Parse planner config — optional dedicated planner
           ;; Runs in project root, no worktree/review/merge, respects max_pending backpressure
@@ -466,19 +944,35 @@
           ;; Convert to worker format
           workers (map-indexed
                     (fn [idx wc]
-                      (let [{:keys [harness model reasoning]} (parse-model-string (:model wc))]
+                      (let [{:keys [harness model reasoning]} (parse-model-string (:model wc))
+                            ;; Support per-worker reviewer override
+                            worker-reviewer-config (:reviewer wc)
+                            specific-reviewer (when worker-reviewer-config
+                                                (let [parsed (parse-model-string (:model worker-reviewer-config))
+                                                      prompts (let [p (:prompt worker-reviewer-config)]
+                                                                (cond (vector? p) p
+                                                                      (string? p) [p]
+                                                                      :else []))]
+                                                  (assoc parsed :prompts prompts)))
+                            all-reviewers (->> (concat (if specific-reviewer [specific-reviewer] []) generic-reviewers)
+                                               (map #(select-keys % [:harness :model :reasoning :prompts]))
+                                               (distinct)
+                                               (vec))]
                         (worker/create-worker
                           {:id (str "w" idx)
                            :swarm-id swarm-id
                            :harness harness
                            :model model
                            :reasoning reasoning
+                           :runs (or (:runs wc) (:iterations wc) 10)
+                           :max-cycles (or (:max_cycles wc) (:iterations wc) (:runs wc) 10)
                            :iterations (or (:iterations wc) 10)
                            :prompts (:prompt wc)
                            :can-plan (:can_plan wc)
-                           :review-harness (:harness review-parsed)
-                           :review-model (:model review-parsed)
-                           :review-prompts (:prompts review-parsed)})))
+                           :wait-between (:wait_between wc)
+                           :max-wait-for-tasks (:max_wait_for_tasks wc)
+                           :max-working-resumes (:max_working_resumes wc)
+                           :reviewers all-reviewers})))
                     expanded-workers)]
 
       (println (format "Swarm config from %s:" config-file))
@@ -491,22 +985,19 @@
                          (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)) ")")
-                           ""))))
+      (when (seq generic-reviewers)
+        (println (format "  Generic Reviewers: %s"
+                         (str/join ", " (map #(str (name (:harness %)) ":" (:model %)) generic-reviewers)))))
       (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))]
-          (println (format "    - %dx %s:%s%s (%d iters%s)"
+          (println (format "    - %dx %s:%s%s (%d runs, %d cycle cap%s)"
                            (or (:count wc) 1)
                            (name harness)
                            model
                            (if reasoning (str ":" reasoning) "")
-                           (or (:iterations wc) 10)
+                           (or (:runs wc) (:iterations wc) 10)
+                           (or (:max_cycles wc) (:iterations wc) (:runs wc) 10)
                            (if (:prompt wc) (str ", " (:prompt wc)) "")))))
       (println)
 
@@ -514,15 +1005,15 @@
       ;; Include planner model in validation if configured
       (validate-models! (cond-> worker-configs
                           planner-config (conj planner-config))
-                        review-parsed)
+                        generic-reviewers)
 
-      ;; Write run log to runs/{swarm-id}/run.edn
-      (runs/write-run-log! swarm-id
+      ;; Write started event to runs/{swarm-id}/started.json
+      (runs/write-started! swarm-id
                            {:workers workers
                             :planner-config planner-parsed
-                            :reviewer-config review-parsed
+                            :reviewer-configs generic-reviewers
                             :config-file config-file})
-      (println (format "\nRun log written to runs/%s/run.edn" swarm-id))
+      (println (format "\nStarted event written to runs/%s/started.json" swarm-id))
 
       ;; Run planner if configured — synchronously before workers
       (when planner-parsed
@@ -555,6 +1046,69 @@
       (doseq [t (tasks/list-current)]
         (println (format "  - %s: %s" (:id t) (:summary t)))))))
 
+(defn- find-latest-swarm-id
+  "Find the most recent swarm ID from runs/ directory."
+  []
+  (first (runs/list-runs)))
+
+(defn- read-swarm-pid
+  "Read PID from started.json for a swarm. Returns nil if not found."
+  [swarm-id]
+  (when-let [started (runs/read-started swarm-id)]
+    (:pid started)))
+
+(defn- pid-alive?
+  "Check if a process is alive via kill -0."
+  [pid]
+  (try
+    (zero? (:exit (process/sh ["kill" "-0" (str pid)]
+                              {:out :string :err :string})))
+    (catch Exception _ false)))
+
+(defn cmd-stop
+  "Send SIGTERM to running swarm — workers finish current cycle then exit"
+  [opts args]
+  (let [swarm-id (or (first args) (find-latest-swarm-id))]
+    (if-not swarm-id
+      (println "No swarm runs found.")
+      (let [stopped (runs/read-stopped swarm-id)]
+        (if stopped
+          (println (format "Swarm %s already stopped (reason: %s)" swarm-id (:reason stopped)))
+          (let [pid (read-swarm-pid swarm-id)]
+            (if-not pid
+              (println (format "No PID found for swarm %s" swarm-id))
+              (if-not (pid-alive? pid)
+                (do
+                  (println (format "Swarm %s PID %s is not running (stale). Writing stopped event." swarm-id pid))
+                  (runs/write-stopped! swarm-id :interrupted))
+                (do
+                  (println (format "Sending SIGTERM to swarm %s (PID %s)..." swarm-id pid))
+                  (println "Workers will finish their current cycle and exit.")
+                  (process/sh ["kill" (str pid)]))))))))))
+
+(defn cmd-kill
+  "Send SIGKILL to running swarm — immediate termination"
+  [opts args]
+  (let [swarm-id (or (first args) (find-latest-swarm-id))]
+    (if-not swarm-id
+      (println "No swarm runs found.")
+      (let [stopped (runs/read-stopped swarm-id)]
+        (if stopped
+          (println (format "Swarm %s already stopped (reason: %s)" swarm-id (:reason stopped)))
+          (let [pid (read-swarm-pid swarm-id)]
+            (if-not pid
+              (println (format "No PID found for swarm %s" swarm-id))
+              (if-not (pid-alive? pid)
+                (do
+                  (println (format "Swarm %s PID %s is not running (stale). Writing stopped event." swarm-id pid))
+                  (runs/write-stopped! swarm-id :interrupted))
+                (do
+                  (println (format "Sending SIGKILL to swarm %s (PID %s)..." swarm-id pid))
+                  ;; SIGKILL bypasses JVM shutdown hooks, so write stopped.json here
+                  (process/sh ["kill" "-9" (str pid)])
+                  (runs/write-stopped! swarm-id :interrupted)
+                  (println "Swarm killed."))))))))))
+
 (defn cmd-help
   "Print usage information"
   [opts args]
@@ -563,32 +1117,66 @@
   (println "Usage: ./swarm.bb <command> [options]")
   (println)
   (println "Commands:")
-  (println "  run              Run all tasks once")
+  (println "  run [file]       Run swarm from config (default: oompa.json, oompa/oompa.json)")
   (println "  loop N           Run N iterations")
   (println "  swarm [file]     Run multiple worker configs from oompa.json (parallel)")
   (println "  tasks            Show task status (pending/current/complete)")
   (println "  prompt \"...\"     Run ad-hoc prompt")
-  (println "  status           Show last run summary")
+  (println "  status           Show running swarms")
+  (println "  info             Show detailed summary of the last run")
+  (println "  list             List recent swarms (default: 20, --all for full history)")
+  (println "  view [swarm-id]  Show detailed single-swarm runtime (default: latest)")
   (println "  worktrees        List worktree status")
+  (println "  stop [swarm-id]  Stop swarm gracefully (finish current cycle)")
+  (println "  kill [swarm-id]  Kill swarm immediately (SIGKILL)")
   (println "  cleanup          Remove all worktrees")
   (println "  context          Print context block")
   (println "  check            Check agent backends")
   (println "  help             Show this help")
+  (println "  docs             Dump all core architecture and swarm design docs")
   (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 opencode:2)")
+  (println "  --all                    Show full history for list command")
+  (println "  --config PATH            Config file for run/swarm")
+  (println "  --detach                 Run in background (run command)")
+  (println "  --startup-timeout N      Detached startup validation window in seconds")
   (println "  --iterations N           Number of iterations per worker (default: 1)")
-  (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 (str "  --harness {" (str/join "," (map name (sort harnesses))) "} Agent harness to use (default: codex)"))
+  (println "  --model MODEL            Model to use (e.g., codex:gpt-5.3-codex:medium, claude:opus, gemini:gemini-3-pro-preview)")
   (println "  --dry-run                Skip actual merges")
   (println "  --keep-worktrees         Don't cleanup worktrees after run")
   (println)
   (println "Examples:")
+  (println "  ./swarm.bb list")
+  (println "  ./swarm.bb list --all")
+  (println "  ./swarm.bb view 6cd50f5a")
+  (println "  ./swarm.bb run --detach --config oompa/oompa_overnight_self_healing.json")
   (println "  ./swarm.bb loop 10 --harness codex --model gpt-5.3-codex --workers 3")
   (println "  ./swarm.bb loop --workers claude:5 opencode:2 --iterations 20")
   (println "  ./swarm.bb swarm oompa.json  # Run multi-model config"))
 
+(defn cmd-docs
+  "Dump core architecture and design documents"
+  [opts args]
+  (let [docs-dir "docs"
+        core-docs ["SWARM_PHILOSOPHY.md" "SWARM_GUIDE.md" "EDN_TICKETS.md" "SYSTEMS_DESIGN.md" "OOMPA.md"]
+        package-dir (or (System/getenv "OOMPA_PACKAGE_ROOT") ".")
+        doc-paths (map #(str package-dir "/" docs-dir "/" %) core-docs)]
+    (println "# Oompa Loompas Core Documentation")
+    (println)
+    (doseq [path doc-paths]
+      (try
+        (let [content (slurp path)]
+          (println (str "## " path))
+          (println "```markdown")
+          (println content)
+          (println "```")
+          (println))
+        (catch Exception e
+          (println (str "Could not read " path ": " (.getMessage e))))))))
+
 ;; =============================================================================
 ;; Main Entry Point
 ;; =============================================================================
@@ -600,22 +1188,28 @@
    "tasks" cmd-tasks
    "prompt" cmd-prompt
    "status" cmd-status
+   "info" cmd-info
+   "list" cmd-list
+   "view" cmd-view
+   "stop" cmd-stop
+   "kill" cmd-kill
    "worktrees" cmd-worktrees
    "cleanup" cmd-cleanup
    "context" cmd-context
    "check" cmd-check
-   "help" cmd-help})
+   "help" cmd-help
+   "docs" cmd-docs})
 
 (defn -main [& args]
   (let [[cmd & rest-args] args]
     (if-let [handler (get commands cmd)]
-      (let [{:keys [opts args]} (parse-args rest-args)]
-        (try
-          (handler opts args)
-          (catch Exception e
-            (binding [*out* *err*]
-              (println (format "Error: %s" (.getMessage e))))
-            (System/exit 1))))
+      (try
+        (let [{:keys [opts args]} (parse-args rest-args)]
+          (handler opts args))
+        (catch Exception e
+          (binding [*out* *err*]
+            (println (format "Error: %s" (.getMessage e))))
+          (System/exit 1)))
       (do
         (cmd-help {} [])
         (when cmd