@nbardy/oompa 0.7.0 → 0.7.1

package/README.md

@@ -85,7 +85,7 @@ This repo has a fleshed out version of the idea. The oompa loompas are organized
   "workers": [
     {"model": "claude:opus", "prompt": ["config/prompts/planner.md"], "iterations": 5, "count": 1},
     {"model": "codex:gpt-5.3-codex:medium", "prompt": ["config/prompts/executor.md"], "iterations": 10, "count": 2, "can_plan": false},
-    {"model": "opencode:openai/gpt-5", "prompt": ["config/prompts/executor.md"], "iterations": 10, "count": 1, "can_plan": false}
+    {"model": "opencode:opencode/kimi-k2.5-free", "prompt": ["config/prompts/executor.md"], "iterations": 10, "count": 1, "can_plan": false}
   ]
 }
 ```
@@ -93,13 +93,13 @@ This repo has a fleshed out version of the idea. The oompa loompas are organized
 This spawns:
 - **1 planner** (opus) — reads spec, explores codebase, creates/refines tasks
 - **2 codex executors** (gpt-5.3-codex, medium reasoning) — claims and executes tasks fast
-- **1 opencode executor** (openai/gpt-5) — same task loop via `opencode run`
+- **1 opencode executor** (opencode/kimi-k2.5-free) — same task loop via `opencode run`
 
 #### Worker fields
 
 | Field | Required | Description |
 |-------|----------|-------------|
-| `model` | yes | `harness:model` or `harness:model:reasoning` (e.g. `codex:gpt-5.3-codex:medium`, `claude:opus`, `opencode:openai/gpt-5`) |
+| `model` | yes | `harness:model` or `harness:model:reasoning` (e.g. `codex:gpt-5.3-codex:medium`, `claude:opus`, `opencode:opencode/kimi-k2.5-free`) |
 | `prompt` | no | String or array of paths — concatenated into one prompt |
 | `iterations` | no | Max iterations per worker (default: 10) |
 | `count` | no | Number of workers with this config (default: 1) |
@@ -113,7 +113,7 @@ This spawns:
 {
   "workers": [
     {"model": "claude:opus-4.5", "prompt": ["prompts/base.md", "prompts/architect.md"], "count": 1},
-    {"model": "opencode:openai/gpt-5-mini", "prompt": ["prompts/base.md", "prompts/frontend.md"], "count": 2},
+    {"model": "opencode:opencode/kimi-k2.5-free", "prompt": ["prompts/base.md", "prompts/frontend.md"], "count": 2},
     {"model": "codex:codex-5.2-mini", "prompt": ["prompts/base.md", "prompts/backend.md"], "count": 2}
   ]
 }
@@ -121,6 +121,23 @@ This spawns:
 
 Every worker automatically gets task management instructions injected above your prompts. Your prompts just say *what* the worker should do — the framework handles *how* tasks work.
 
+#### Prompt includes
+
+Prompts support `#oompa_directive:include_file "path/to/file.md"` lines.
+
+Use it to share common instructions across roles without copying content.  
+Paths are resolved relative to the prompt file containing the directive.
+
+Example:
+
+```md
+#oompa_directive:include_file "config/prompts/_agent_scope_rules.md"
+
+You are an executor. Focus on minimal changes and complete tasks.
+```
+
+The included file is inlined during prompt load, with a short header noting the injected source.
+
 ### Task System
 
 Workers self-organize via the filesystem. Tasks live at the project root and are shared across all worktrees:

package/agentnet/src/agentnet/agent.clj

@@ -88,6 +88,12 @@
       attach (into ["--attach" attach])
       true (conj prompt))))
 
+(defmethod build-command :gemini
+  [_ {:keys [model]} prompt cwd]
+  (cond-> ["gemini" "--yolo"]
+    model (into ["-m" model])
+    true (into ["-p" prompt])))
+
 (defmethod build-command :default
   [agent-type _ _ _]
   (throw (ex-info (str "Unknown agent type: " agent-type)
@@ -125,7 +131,102 @@
      :stdout (truncate (:out result) 10000)
      :stderr (truncate (:err result) 5000)
      :duration-ms (- (now-ms) start)
-     :timed-out? (boolean (:timed-out result))}))
+              :timed-out? (boolean (:timed-out result))}))
+
+;; =============================================================================
+;; Prompt Loading Helpers
+;; =============================================================================
+
+(defn- file-canonical-path
+  "Resolve a path for cache keys and cycle detection."
+  [path]
+  (try
+    (.getCanonicalPath (io/file path))
+    (catch Exception _
+      path)))
+
+(def ^:private prompt-file-cache
+  "Cache for prompt include expansion."
+  (atom {}))
+
+(def ^:private include-directive-pattern
+  #"(?m)^\s*#oompa_directive:include_file\s+\"([^\"]+)\"\s*$")
+
+(defn- read-file-cached
+  "Read a prompt file once and cache by canonical path."
+  [path]
+  (when path
+    (if-let [cached (get @prompt-file-cache path)]
+      cached
+      (let [f (io/file path)]
+        (when (.exists f)
+          (let [content (slurp f)]
+            (swap! prompt-file-cache assoc path content)
+            content))))))
+
+(defn- resolve-include-path
+  "Resolve an include path relative to the file that declares it."
+  [source-path include-path]
+  (let [source-file (io/file source-path)
+        base-dir (.getParentFile source-file)]
+    (if (or (str/starts-with? include-path "/")
+            (and (> (count include-path) 1)
+                 (= (nth include-path 1) \:)) ; Windows drive letter
+            (str/starts-with? include-path "~"))
+      include-path
+      (if base-dir
+        (str (io/file base-dir include-path))
+        include-path))))
+
+(defn- expand-includes
+  "Expand #oompa_directive:include_file directives recursively.
+
+   Directive syntax:
+   #oompa_directive:include_file \"relative/or/absolute/path.md\"
+
+   Includes are resolved relative to the prompt file containing the directive.
+   Cycles are guarded by a simple visited-set."
+  ([raw source-path]
+   (expand-includes raw source-path #{}))
+  ([raw source-path visited]
+   (let [source-canonical (file-canonical-path source-path)
+         lines (str/split-lines (or raw ""))
+         visited' (conj visited source-canonical)]
+     (str/join
+      "\n"
+      (mapcat
+       (fn [line]
+         (if-let [match (re-matches include-directive-pattern line)]
+           (let [include-target (second match)
+                 include-path (resolve-include-path source-canonical include-target)
+                 include-canonical (file-canonical-path include-path)
+                 included (and (not (str/blank? include-path))
+                               (read-file-cached include-canonical))]
+             (cond
+               (str/blank? include-target)
+               ["[oompa] Empty include target in prompt directive"]
+
+               (contains? visited' include-canonical)
+               [(format "[oompa] Skipping already-included file: \"%s\"" include-target)]
+
+               (not included)
+               [(format "[oompa] Could not include \"%s\"" include-target)]
+
+               :else
+               (cons (format "We have included the content of file: \"%s\" below"
+                             include-target)
+                     (str/split-lines
+                      (expand-includes included include-canonical visited')))))
+           [line]))
+       lines)))))
+
+(defn- load-prompt-file
+  "Load a prompt file and expand include directives."
+  [path]
+  (when path
+    (when-let [f (io/file path)]
+      (when (.exists f)
+        (expand-includes (slurp f) (file-canonical-path path))))))
 
 ;; =============================================================================
 ;; Output Parsing
@@ -152,6 +253,17 @@
   [output]
   (boolean (re-find #"COMPLETE_AND_READY_FOR_MERGE" (or output ""))))
 
+(defn parse-claim-signal
+  "Extract task IDs from CLAIM(...) signal in output.
+   Returns vector of task ID strings, or nil if no CLAIM signal found.
+   Format: CLAIM(task-001, task-003, task-005)"
+  [output]
+  (when-let [match (re-find #"CLAIM\(([^)]+)\)" (or output ""))]
+    (->> (str/split (second match) #",")
+         (map str/trim)
+         (remove str/blank?)
+         vec)))
+
 (defn- extract-comments
   "Extract bullet-point comments from output"
   [output]
@@ -228,7 +340,7 @@
   (let [filename (str "config/prompts/" (name role) ".md")
         f (io/file filename)]
     (when (.exists f)
-      (slurp f))))
+      (load-prompt-file filename))))
 
 (defn load-custom-prompt
   "Load a custom prompt file. Returns content or nil."
@@ -236,10 +348,11 @@
   (when path
     (let [f (io/file path)]
       (when (.exists f)
-        (slurp f)))))
+        (load-prompt-file path)))))
 
-(defn- tokenize
-  "Replace {tokens} in template with values from context map"
+(defn tokenize
+  "Replace {tokens} in template with values from context map.
+   Keys can be keywords or strings; values are stringified."
   [template tokens]
   (reduce (fn [acc [k v]]
             (str/replace acc
@@ -287,12 +400,18 @@
               :codex ["codex" "--version"]
               :claude ["claude" "--version"]
               :opencode ["opencode" "--version"]
+              :gemini ["gemini" "--version"]
               ["echo" "unknown"])]
     (try
       (let [{:keys [exit]} (process/sh cmd {:out :string :err :string})]
         (zero? exit))
       (catch Exception _
-        false))))
+        ;; Some CLIs (like gemini) may error on --version due to config issues
+        ;; but still exist on PATH. Fall back to `which`.
+        (try
+          (let [{:keys [exit]} (process/sh ["which" (first cmd)] {:out :string :err :string})]
+            (zero? exit))
+          (catch Exception _ false))))))
 
 (defn select-backend
   "Select first available backend from preference list"

package/agentnet/src/agentnet/cli.clj

@@ -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."
@@ -46,7 +47,7 @@
         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'") {})))
+      (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}))
@@ -97,7 +98,7 @@
         (= arg "--harness")
         (let [h (keyword (second remaining))]
           (when-not (harnesses h)
-            (throw (ex-info (str "Unknown harness: " (second remaining) ". Use 'codex', 'claude', or 'opencode'") {})))
+            (throw (ex-info (str "Unknown harness: " (second remaining) ". Known: " (str/join ", " (map name (sort harnesses)))) {})))
           (recur (assoc opts :harness h)
                  (nnext remaining)))
 
@@ -153,15 +154,52 @@
       (println "Run 'git stash' or 'git commit' first.")
       (System/exit 1))))
 
+(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)
+      (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))))
+
 (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, /dev/null stdin 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"])
+    (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})
           result (deref proc 30000 :timeout)]
@@ -225,10 +263,10 @@
             (println (format "  %dx %s" (:count spec) (name (:harness spec)))))
           (println)
           (worker/run-workers! workers))
-        ;; Simple mode
+        ;; Simple mode retired — use oompa.json or --workers harness:count
         (do
-          (println (format "Swarm ID: %s" swarm-id))
-          (orchestrator/run-once! (assoc opts :swarm-id swarm-id)))))))
+          (println "Simple mode is no longer supported. Use oompa.json or --workers harness:count.")
+          (System/exit 1))))))
 
 (defn cmd-loop
   "Run orchestrator N times"
@@ -257,14 +295,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,46 +318,45 @@
       (orchestrator/run-once! opts))))
 
 (defn cmd-status
-  "Show status of last run — reads structured runs/{swarm-id}/ data."
+  "Show status of last run — reads event-sourced runs/{swarm-id}/ data."
   [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)
+            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 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)))))
+        (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 summary
-          (do
-            (println (format "Summary (finished %s):" (:finished-at summary)))
-            (println (format "  Total completed: %d/%d iterations"
-                             (:total-completed summary) (:total-iterations summary)))
-            (println (format "  Status counts: %s" (pr-str (:status-counts summary))))
-            (println)
-            (println "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)"))
+        (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-i%d-r%d: %s"
-                             (:worker-id r) (:iteration r) (:round r)
+            (println (format "  %s-c%d-r%d: %s"
+                             (:worker-id r) (:cycle r) (:round r)
                              (:verdict r))))))
       ;; Fall back to legacy JSONL format
       (let [runs-dir (io/file "runs")
@@ -382,21 +415,43 @@
   "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 (codex only)
+   - model (defaults harness to :codex)
+
+   Note: non-codex model identifiers may contain ':' (for example
+   openrouter/...:free). Those suffixes are preserved in :model."
   [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 (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').
+          {: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 +469,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,6 +477,8 @@
       (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:
@@ -476,6 +533,8 @@
                            :iterations (or (:iterations wc) 10)
                            :prompts (:prompt wc)
                            :can-plan (:can_plan wc)
+                           :wait-between (:wait_between wc)
+                           :max-working-resumes (:max_working_resumes wc)
                            :review-harness (:harness review-parsed)
                            :review-model (:model review-parsed)
                            :review-prompts (:prompts review-parsed)})))
@@ -516,13 +575,13 @@
                           planner-config (conj planner-config))
                         review-parsed)
 
-      ;; 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
                             :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 +614,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]
@@ -570,6 +692,8 @@
   (println "  prompt \"...\"     Run ad-hoc prompt")
   (println "  status           Show last run summary")
   (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")
@@ -579,8 +703,8 @@
   (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 "  --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)
@@ -600,6 +724,8 @@
    "tasks" cmd-tasks
    "prompt" cmd-prompt
    "status" cmd-status
+   "stop" cmd-stop
+   "kill" cmd-kill
    "worktrees" cmd-worktrees
    "cleanup" cmd-cleanup
    "context" cmd-context