@nbardy/oompa 0.7.1 → 0.7.3

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
@@ -46,7 +46,7 @@
   (let [[harness count-str] (str/split s #":" 2)
         h (keyword harness)
         cnt (parse-int count-str 0)]
-    (when-not (harnesses h)
+    (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'") {})))
@@ -75,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]
@@ -97,7 +101,7 @@
 
         (= arg "--harness")
         (let [h (keyword (second remaining))]
-          (when-not (harnesses h)
+          (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)))
@@ -106,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)
@@ -137,71 +163,169 @@
 ;; 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)
-      (println output)
-      (println)
-      (println "Run 'git stash' or 'git commit' first.")
-      (System/exit 1))))
+      (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
+(defn- dirty-worktree?
+  "Returns true if the git worktree at path has uncommitted changes."
+  [path]
+  (let [{:keys [exit out]} (process/sh ["git" "-C" path "status" "--porcelain"]
+                                       {:out :string :err :string})]
+    (and (zero? exit) (not (str/blank? out)))))
+
+(defn- worktree-branch-name
+  "Returns the current branch name for the worktree at path, or nil on failure."
+  [path]
+  (let [{:keys [exit out]} (process/sh ["git" "-C" path "rev-parse" "--abbrev-ref" "HEAD"]
+                                       {:out :string :err :string})]
+    (when (zero? exit) (str/trim out))))
+
+(defn- remove-stale-worktree!
+  "Remove a stale worktree directory and delete its branch."
+  [path branch]
+  (process/sh ["git" "worktree" "remove" "--force" path] {:out :string :err :string})
+  (when (and branch (not (str/blank? branch)) (not= branch "HEAD"))
+    (process/sh ["git" "branch" "-D" branch] {:out :string :err :string})))
+
+(defn- run-stale-review!
+  "Invoke the reviewer model on partial worktree changes.
+   Tries each reviewer in the fallback chain until one returns a verdict.
+   Returns :merge to merge the branch into main, :discard to throw it away."
+  [reviewer-configs worktree-path branch]
+  (let [diff-out (:out (process/sh ["git" "-C" worktree-path "diff" "HEAD"]
+                                   {:out :string :err :string}))
+        diff     (if (> (count diff-out) 8000)
+                   (str (subs diff-out 0 8000) "\n...[diff truncated at 8000 chars]")
+                   diff-out)
+        status-out (:out (process/sh ["git" "-C" worktree-path "status" "--short"]
+                                     {:out :string}))
+        prompt   (str "You are reviewing partial/incomplete changes from an interrupted swarm run.\n\n"
+                      "Branch: " branch "\n"
+                      "Status:\n" status-out "\n\n"
+                      "Diff:\n```\n" diff "\n```\n\n"
+                      "Should these changes be merged into main or discarded?\n"
+                      "MERGE if: changes are correct, complete, or valuable enough to keep.\n"
+                      "DISCARD if: changes are broken, trivial, or not worth merging.\n\n"
+                      "Your verdict MUST appear on its own line, exactly one of:\n"
+                      "VERDICT: MERGE\n"
+                      "VERDICT: DISCARD\n\n"
+                      "Then briefly explain why.\n")
+        result   (reduce (fn [_ {:keys [harness model]}]
+                           (try
+                             (let [cmd (harness/build-cmd harness {:model model :prompt prompt})
+                                   res (process/sh cmd
+                                                   {:in  (harness/process-stdin harness prompt)
+                                                    :out :string :err :string})
+                                   output       (:out res)
+                                   has-verdict? (or (re-find #"VERDICT:\s*MERGE" output)
+                                                    (re-find #"VERDICT:\s*DISCARD" output))]
+                               (if (and (zero? (:exit res)) has-verdict?)
+                                 (reduced res)
+                                 res))
+                             (catch Exception e
+                               {:exit -1 :out "" :err (.getMessage e)})))
+                         {:exit -1 :out ""}
+                         reviewer-configs)
+        output   (:out result)]
+    (cond
+      (re-find #"VERDICT:\s*MERGE"   output) :merge
+      (re-find #"VERDICT:\s*DISCARD" output) :discard
+      :else                                   :discard)))
+
+(defn- handle-stale-worktrees!
+  "Non-destructive startup check for existing oompa worktrees.
+
+   - Always runs `git worktree prune` to clear orphaned metadata.
+   - Never auto-removes/merges/discards worktrees at startup.
+   - Prints a warning summary so concurrent swarms are not disrupted.
+
+   This avoids clobbering active work from another swarm in the same repo."
+  [_reviewer-configs]
+  ;; Step 1: prune orphaned git metadata first
   (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/*"]
+
+  ;; Step 2: discover existing oompa worktree dirs and oompa/* branches
+  (let [ls-result          (process/sh ["find" "." "-maxdepth" "1" "-type" "d" "-name" ".w*-i*"]
+                                       {:out :string})
+        stale-dirs         (when (zero? (:exit ls-result))
+                             (->> (str/split-lines (:out ls-result))
+                                  (remove str/blank?)))
+        br-result          (process/sh ["git" "branch" "--list" "oompa/*"] {:out :string})
+        all-oompa-branches (when (zero? (:exit br-result))
+                             (->> (str/split-lines (:out br-result))
+                                  (map str/trim)
+                                  (remove str/blank?)))]
+
+    (when (or (seq stale-dirs) (seq all-oompa-branches))
+      ;; Step 3: classify for warning output only (no mutation)
+      (let [classified      (mapv (fn [dir]
+                                    {:dir    dir
+                                     :branch (worktree-branch-name dir)
+                                     :dirty? (dirty-worktree? dir)})
+                                  stale-dirs)
+            clean           (filter (complement :dirty?) classified)
+            dirty           (filter :dirty? classified)
+            dir-branches    (set (keep :branch classified))
+            orphan-branches (remove #(contains? dir-branches %) all-oompa-branches)]
+        (println)
+        (println "WARNING: Existing oompa worktrees/branches detected; leaving them untouched.")
+        (println (format "  Worktrees: %d (%d dirty, %d clean)"
+                         (count classified) (count dirty) (count clean)))
+        (println (format "  Orphan branches: %d" (count orphan-branches)))
+        (when (seq dirty)
+          (println "  Dirty worktrees:")
+          (doseq [{:keys [dir branch]} dirty]
+            (println (format "    %s (branch: %s)" dir (or branch "unknown")))))
+        (println "  Run `oompa cleanup` manually when you want to reclaim them.")))))
+
+(defn- cleanup-iteration-worktrees!
+  "Remove swarm iteration worktree dirs (.w*-i*) and oompa/* branches.
+   Returns {:dirs-removed n :branches-removed n}."
+  []
+  (let [ls-result (process/sh ["find" "." "-maxdepth" "1" "-type" "d" "-name" ".w*-i*"]
                               {: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)
-      (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)
-      (System/exit 1))))
+        dirs (if (zero? (:exit ls-result))
+               (->> (str/split-lines (:out ls-result))
+                    (remove str/blank?))
+               [])
+        _ (doseq [dir dirs]
+            (remove-stale-worktree! dir (worktree-branch-name dir)))
+        br-result (process/sh ["git" "branch" "--list" "oompa/*"] {:out :string})
+        branches (if (zero? (:exit br-result))
+                   (->> (str/split-lines (:out br-result))
+                        (map str/trim)
+                        (remove str/blank?))
+                   [])
+        ;; Branches may already be deleted by remove-stale-worktree!, so ignore failures.
+        _ (doseq [b branches]
+            (process/sh ["git" "branch" "-D" b] {:out :string :err :string}))]
+    {:dirs-removed (count dirs)
+     :branches-removed (count branches)}))
+
 
 (defn- probe-model
   "Send 'say ok' to a model via its harness CLI. Returns true if model responds.
-   Uses harness/build-probe-cmd for the command, /dev/null stdin to prevent hang."
+   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 (harness/build-probe-cmd harness-kw model)
-          null-in (io/input-stream (io/file "/dev/null"))
-          proc (process/process cmd {:out :string :err :string :in null-in})
+          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)
@@ -210,14 +334,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)]
@@ -237,36 +361,261 @@
       (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 "ERROR: Config file not found: %s" (.getCanonicalPath (io/file config-file))))
+    (println (format "       Working directory: %s" (.getCanonicalPath (io/file "."))))
+    (println)
+    (println "Tip: paths are relative to the working directory. Did you mean:")
+    (println (format "       oompa run --config oompa/%s" (.getName (io/file 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 retired — use oompa.json or --workers harness:count
+          (println "ERROR: Detached swarm exited during startup validation.")
+          (println "Startup log excerpt:")
+          (println (tail-lines content 120))
+          (System/exit 1))
+
+        :timeout
         (do
-          (println "Simple mode is no longer supported. Use oompa.json or --workers harness:count.")
-          (System/exit 1))))))
+          (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"
@@ -318,46 +667,72 @@
       (orchestrator/run-once! opts))))
 
 (defn cmd-status
-  "Show status of last run — reads event-sourced 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))
-            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 (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)
-        (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))))))
+      (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 "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)
+            (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)
@@ -377,6 +752,166 @@
                 (println (format "Total: %d tasks" (count entries))))))
           (println "No runs found."))))))
 
+(def ^:private error-outcomes
+  #{"error" "merge-failed" "rejected" "stuck" "needs-followup"})
+
+(def ^:private terminal-run-outcomes
+  #{"merged" "rejected" "error" "merge-failed" "sync-failed" "stuck" "no-changes" "needs-followup"})
+
+(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]
@@ -395,15 +930,18 @@
       (println "No worktrees initialized."))))
 
 (defn cmd-cleanup
-  "Remove all worktrees"
+  "Remove all worktrees (legacy pool + swarm iteration worktrees)."
   [opts args]
   (let [state-file (io/file ".workers/state.edn")]
+    (println "Removing worktrees...")
     (if (.exists state-file)
       (let [pool (read-string (slurp state-file))]
-        (println "Removing worktrees...")
-        (worktree/cleanup-pool! pool)
-        (println "Done."))
-      (println "No worktrees to clean up."))))
+        (worktree/cleanup-pool! pool))
+      (println "No legacy pool worktrees to clean up."))
+    (let [{:keys [dirs-removed branches-removed]} (cleanup-iteration-worktrees!)]
+      (println (format "Removed %d swarm worktree dir(s) and %d oompa branch(es)."
+                       dirs-removed branches-removed)))
+    (println "Done.")))
 
 (defn cmd-context
   "Print current context (for debugging prompts)"
@@ -429,32 +967,52 @@
 
    Supported formats:
    - harness:model
-   - harness:model:reasoning (codex only)
+   - harness:model:reasoning (if reasoning is in reasoning-variants)
    - model (defaults harness to :codex)
 
-   Note: non-codex model identifiers may contain ':' (for example
-   openrouter/...:free). Those suffixes are preserved in :model."
+   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 [[harness-str rest*] (str/split s #":" 2)
           harness (keyword harness-str)]
-      (if (contains? harnesses harness)
-        (if (= harness :codex)
-          ;; Codex may include a reasoning suffix at the end. Only treat the
-          ;; last segment as reasoning if it matches a known variant.
-          (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*})
-          ;; Non-codex: preserve full model string (including any ':suffix').
+      (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}))
 
+(defn- parse-reviewer-entry
+  "Parse reviewer config entry from either:
+   1) string model spec: \"harness:model[:reasoning]\"
+   2) map: {:model \"...\" :prompt \"path\"|[...]}.
+   Returns nil for invalid entries."
+  [entry]
+  (cond
+    (string? entry)
+    (parse-model-string entry)
+
+    (map? entry)
+    (let [model (:model entry)]
+      (when (string? model)
+        (let [parsed (parse-model-string model)
+              prompts (let [p (:prompt entry)]
+                        (cond
+                          (vector? p) p
+                          (string? p) [p]
+                          :else []))]
+          (assoc parsed :prompts prompts))))
+
+    :else
+    nil))
+
 (defn cmd-swarm
   "Run multiple worker configs from oompa.json in parallel"
   [opts args]
@@ -462,42 +1020,37 @@
         f (io/file config-file)
         swarm-id (make-swarm-id)]
     (when-not (.exists f)
-      (println (format "Config file not found: %s" config-file))
-      (println)
-      (println "Create oompa.json with format:")
-      (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\": \"gemini:gemini-3-pro-preview\", \"prompt\": [\"prompts/executor.md\"], \"count\": 1}")
-      (println "  ]")
-      (println "}")
+      (println (format "ERROR: Config file not found: %s" (.getCanonicalPath f)))
+      (println (format "       Working directory: %s" (.getCanonicalPath (io/file "."))))
       (println)
-      (println "prompt: string or array of paths — concatenated into one prompt.")
+      (println "Tip: paths are relative to the working directory. Did you mean:")
+      (println (format "       oompa run --config oompa/%s" (.getName f)))
       (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)
+          ;; Parse reviewer config — supports legacy + new formats.
+          generic-reviewers (cond
+                              (:review_models config)
+                              (->> (:review_models config)
+                                   (map parse-reviewer-entry)
+                                   (remove nil?)
+                                   vec)
+
+                              (:review_model config)
+                              (->> [(:review_model config)]
+                                   (map parse-reviewer-entry)
+                                   (remove nil?)
+                                   vec)
+
+                              (:reviewer config)
+                              (->> [(:reviewer config)]
+                                   (map parse-reviewer-entry)
+                                   (remove nil?)
+                                   vec)
+
+                              :else [])
 
           ;; Parse planner config — optional dedicated planner
           ;; Runs in project root, no worktree/review/merge, respects max_pending backpressure
@@ -512,8 +1065,19 @@
                                     :prompts prompts
                                     :max-pending (or (:max_pending planner-config) 10))))
 
+
           worker-configs (:workers config)
 
+          ;; Require max_cycle to be present on all workers
+          _ (doseq [[idx wc] (map-indexed vector worker-configs)]
+              (when (or (:iterations wc) (:max_cycles wc))
+                (println (format "ERROR: Worker %d uses deprecated 'iterations' or 'max_cycles'. Consolidate strictly on 'max_cycle'." idx))
+                (System/exit 1))
+              (when-not (:max_cycle wc)
+                (println (format "ERROR: Worker %d missing 'max_cycle' in config." idx))
+                (System/exit 1)))
+
+
           ;; Expand worker configs by count
           expanded-workers (mapcat (fn [wc]
                                      (let [cnt (or (:count wc) 1)]
@@ -523,23 +1087,63 @@
           ;; 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 (legacy + new):
+                            ;; - review_model: "harness:model"
+                            ;; - review_models: ["harness:model", ...]
+                            ;; - reviewer: {model, prompt}
+                            ;; - reviewers: [string|map, ...]
+                            worker-reviewers (cond
+                                               (:reviewers wc)
+                                               (->> (:reviewers wc)
+                                                    (map parse-reviewer-entry)
+                                                    (remove nil?)
+                                                    vec)
+
+                                               (:review_models wc)
+                                               (->> (:review_models wc)
+                                                    (map parse-reviewer-entry)
+                                                    (remove nil?)
+                                                    vec)
+
+                                               (:reviewer wc)
+                                               (->> [(:reviewer wc)]
+                                                    (map parse-reviewer-entry)
+                                                    (remove nil?)
+                                                    vec)
+
+                                               (:review_model wc)
+                                               (->> [(:review_model wc)]
+                                                    (map parse-reviewer-entry)
+                                                    (remove nil?)
+                                                    vec)
+
+                                               :else [])
+                            all-reviewers (->> (concat worker-reviewers 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
-                           :iterations (or (:iterations wc) 10)
+                           :runs (or (:runs wc) 10)
+                           :max-cycles (:max_cycle wc)
+                           :iterations (:max_cycle wc)
                            :prompts (:prompt wc)
                            :can-plan (:can_plan wc)
                            :wait-between (:wait_between wc)
+                           :max-wait-for-tasks (:max_wait_for_tasks wc)
                            :max-working-resumes (:max_working_resumes wc)
-                           :review-harness (:harness review-parsed)
-                           :review-model (:model review-parsed)
-                           :review-prompts (:prompts review-parsed)})))
+                           :reviewers all-reviewers})))
                     expanded-workers)]
 
+      ;; Preflight: handle stale worktrees from prior runs before launching workers.
+      ;; Empty ones are auto-cleaned silently; dirty ones trigger an interactive review.
+      (handle-stale-worktrees! generic-reviewers)
+
       (println (format "Swarm config from %s:" config-file))
       (println (format "  Swarm ID: %s" swarm-id))
       (when planner-parsed
@@ -550,22 +1154,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) 10)
+                           (:max_cycle wc)
                            (if (:prompt wc) (str ", " (:prompt wc)) "")))))
       (println)
 
@@ -573,13 +1174,13 @@
       ;; Include planner model in validation if configured
       (validate-models! (cond-> worker-configs
                           planner-config (conj planner-config))
-                        review-parsed)
+                        generic-reviewers)
 
       ;; 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 "\nStarted event written to runs/%s/started.json" swarm-id))
 
@@ -614,6 +1215,26 @@
       (doseq [t (tasks/list-current)]
         (println (format "  - %s: %s" (:id t) (:summary t)))))))
 
+(defn cmd-requeue
+  "Move current/ tasks back to pending/.
+   With args, only requeue those task IDs. Without args, requeue all current tasks."
+  [opts args]
+  (tasks/ensure-dirs!)
+  (let [current-ids (->> (tasks/list-current) (map :id) set)
+        requested-ids (if (seq args) (set args) current-ids)
+        recyclable-ids (set (filter current-ids requested-ids))
+        recycled (if (seq args)
+                   (tasks/recycle-tasks! recyclable-ids)
+                   (tasks/recycle-all-current!))
+        missing (sort (remove recyclable-ids requested-ids))]
+    (if (seq recycled)
+      (println (format "Requeued %d task(s): %s"
+                       (count recycled)
+                       (str/join ", " recycled)))
+      (println "No current tasks were requeued."))
+    (when (seq missing)
+      (println (format "Not in current/: %s" (str/join ", " missing))))))
+
 (defn- find-latest-swarm-id
   "Find the most recent swarm ID from runs/ directory."
   []
@@ -685,12 +1306,16 @@
   (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 "  requeue [ids..]  Move current tasks back to pending")
   (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)")
@@ -698,10 +1323,15 @@
   (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 (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)")
@@ -709,10 +1339,34 @@
   (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
 ;; =============================================================================
@@ -722,26 +1376,31 @@
    "loop" cmd-loop
    "swarm" cmd-swarm
    "tasks" cmd-tasks
+   "requeue" cmd-requeue
    "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