herdr-plugin-amq 0.1.6 → 0.1.8

package/README.md

@@ -33,7 +33,7 @@ The **Bridge Daemon** continuously inspects agent inboxes. When an agent is `idl
 flowchart TD
     subgraph Storage ["Persistent Transport Layer"]
         AMQ[".agent-mail/ (Maildir + RFC 5322)<br/>Decoupled Markdown Transmissions"]
-        BUS[".opencode/bus/ (Decentralized Task Cards)<br/>backlog/ → doing/ → blocked/ → done/"]
+        BUS[".agent-mail/bus/ (Decentralized Task Cards)<br/>backlog/ → doing/ → blocked/ → done/"]
         CAS[".agent-mail/blobs/ (CAS Blobstore)<br/>SHA-256 Render Strips & Proofs"]
     end
 
@@ -72,7 +72,8 @@ flowchart TD
 
 ### 1. The Autonomous Doorbell Bridge
 - **Lifecycle-Aware Wakeups**: Rings doorbells (`herdr agent prompt`) only when agents are `idle` or `done`, preventing command interleaving during active turns.
-- **De-duplication**: Tracks delivered message IDs in persistent state (`bridge-state.json`) so agents are never doorbelled twice for the same mail.
+- **Dual-Queue Wakeups (Mail & Tasks)**: Evaluates both unread Maildir messages and pending backlog tasks assigned to idle agents, prompting agents with specific drainage and claim actions.
+- **De-duplication**: Tracks delivered message and task IDs in persistent state (`bridge-state.json`) so agents are never doorbelled twice for the same event.
 - **Self-Healing Panes**: Automatically detects and renames desynced terminal titles back to their canonical agent handles (`herdr agent rename`).
 - **Blocked State Alerts**: When an agent with unread mail is blocked on external input, logs actionable alert directives for human intervention.
 
@@ -90,7 +91,7 @@ flowchart TD
 
 ### 4. Git Worktree Isolation & Task Bus
 - **Multi-Lane Isolation**: Automatically provisions and manages dedicated Git worktrees (`.worktrees/<agent>`) so parallel agents never step on each other's unstaged files.
-- **Decentralized File-Based Task Cards**: Directory-based task bus (`.opencode/bus/`) immune to concurrent merge conflicts.
+- **Decentralized File-Based Task Cards**: Directory-based task bus (`.agent-mail/bus/`) immune to concurrent merge conflicts.
 
 ---
 
@@ -195,6 +196,8 @@ herdr-amq drain --me coordinator
 
 # Decentralized Kanban Task Bus
 herdr-amq task list
+herdr-amq task drain --me range
+herdr-amq task next --me range
 herdr-amq task claim TSK-402 --me worker-alpha
 herdr-amq task done TSK-402 --proof "Proof of Sabotage: INV-29 passed with non-zero exit on mutation"
 herdr-amq task block TSK-402 --reason "Waiting on asset import lock"
@@ -238,7 +241,7 @@ Under the hood, this pipeline automatically:
 ### 2. Context Resilience (Do agents lose context on cold start?)
 **No.** Context is completely decoupled from the terminal scrollback:
 * **Persistent Transmissions**: All messages, decisions, reviews, and CAS/Git attachments live as RFC 5322 markdown files in `.agent-mail/`.
-* **Decentralized Task Bus**: Tasks live in `.opencode/bus/{backlog,doing,blocked,done}/`.
+* **Decentralized Task Bus**: Tasks live in `.agent-mail/bus/{backlog,doing,blocked,done}/`.
 * **Code Branch Isolation**: Staged and uncommitted edits remain intact in `.worktrees/<handle>` on the agent's branch.
 * **Turn-Based Epistolary Execution**: When an agent wakes up, it drains its inbox (`herdr-amq mail drain --me <handle>`), reads its assigned task card, inspects `git status`, and resumes work without relying on monolithic LLM chat memory.
 

package/bin/herdr-amq.mjs

@@ -53,6 +53,12 @@ switch (cmd) {
   case "board":
     handleTaskCommand(process.argv[3], process.argv.slice(4));
     break;
+  case "next":
+    handleTaskCommand("next", process.argv.slice(3));
+    break;
+  case "task-drain":
+    handleTaskCommand("drain", process.argv.slice(3));
+    break;
   case "mail":
     handleMailCommand(process.argv[3], process.argv.slice(4));
     break;

package/herdr-plugin.toml

@@ -1,6 +1,6 @@
 id = "cabra.amq"
 name = "Herdr AMQ"
-version = "0.1.6"
+version = "0.1.8"
 min_herdr_version = "0.7.0"
 description = "Agent Message Queue (AMQ) bridge daemon, mailbox monitor, and dashboard for Herdr"
 platforms = ["linux", "macos"]
@@ -62,6 +62,12 @@ title = "Open AGmail Webmail Dashboard"
 contexts = ["workspace"]
 command = ["node", "bin/herdr-amq.mjs", "dashboard"]
 
+[[actions]]
+id = "task-drain"
+title = "Drain Assigned Backlog Tasks"
+contexts = ["workspace", "pane"]
+command = ["node", "bin/herdr-amq.mjs", "task", "drain"]
+
 [[panes]]
 id = "dashboard"
 title = "AGmail Dashboard"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "herdr-plugin-amq",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Herdr plugin for AMQ (Agent Message Queue) autonomous bridge, status monitoring, and AGmail dashboard",
   "type": "module",
   "main": "src/index.mjs",

package/skills/herdr-amq/SKILL.md

@@ -12,9 +12,10 @@ metadata:
 
 ## Golden Rules for Agents
 
-1. **Drain First**: Whenever awakened by a doorbell notification or starting a turn, drain your inbox before taking action:
+1. **Drain First**: Whenever awakened by a doorbell notification or starting a turn, drain your inbox and check assigned backlog tasks:
    ```bash
    herdr-amq mail drain --me <handle> --include-body
+   herdr-amq task drain --me <handle>
    ```
 2. **Reply to the Sender**: Always reply to the sender on the same thread/ref chain. Never drop thread context:
    ```bash
@@ -22,8 +23,10 @@ metadata:
    ```
 3. **Atomic Task Claiming**: Claim cards from the directory bus before modifying shared code:
    ```bash
-   herdr-amq task list
+   herdr-amq task drain --me <handle>
    herdr-amq task claim <task-id> --me <handle>
+   # Or auto-claim next in a single command:
+   herdr-amq task next --me <handle>
    ```
    When finished, complete with proof:
    ```bash
@@ -50,11 +53,13 @@ metadata:
 
 ### Task Board & Bus (`herdr-amq task`)
 
-Operates against decentralized card files in `.opencode/bus/{backlog,doing,blocked,done}/`:
+Operates against decentralized card files in `.agent-mail/bus/{backlog,doing,blocked,done}/`:
 
 | Command | Usage | Description |
 |---|---|---|
 | `list` | `herdr-amq task list [--json]` | List cards grouped by column |
+| `drain` | `herdr-amq task drain --me <handle> [--claim]` | Drain assigned backlog cards with full description bodies, optionally claiming |
+| `next` | `herdr-amq task next --me <handle>` | Shortcut to auto-claim and start next assigned backlog card |
 | `claim` | `herdr-amq task claim <task-id> --me <handle>` | Atomically moves card to `doing/<task-id>.md` and updates assignee |
 | `done` | `herdr-amq task done <task-id> --proof "<proof>"` | Moves card to `done/` with timestamp, proof, and duration |
 | `block` | `herdr-amq task block <task-id> --reason "<reason>"` | Moves card to `blocked/` with blocker reason |

package/src/actions.mjs

@@ -7,6 +7,7 @@ import {
   getStateDir,
   getConfigDir,
   getEventContext,
+  getPluginVersion,
 } from "./config.mjs";
 import {
   isDaemonRunning,
@@ -20,6 +21,7 @@ import {
   addBoardTask,
   updateBoardTask,
   deleteBoardTask,
+  drainTasks,
 } from "./board.mjs";
 import {
   sendMaildirMessage,
@@ -31,6 +33,7 @@ import {
   discoverFleetPersonas,
   prepopulateFleet,
   launchFleet,
+  stopFleet,
 } from "./fleet.mjs";
 import { getHerdrAgents } from "./herdr.mjs";
 
@@ -38,9 +41,11 @@ export function handleStatus() {
   const amqRoot = findAmqRoot();
   const pid = isDaemonRunning();
   const handles = amqRoot ? getAgentHandles(amqRoot) : [];
+  const version = getPluginVersion();
 
-  console.log("\n📦 \x1b[1mHerdr AMQ Bridge Status\x1b[0m");
+  console.log(`\n📦 \x1b[1mHerdr AMQ Bridge Status\x1b[0m \x1b[2m(v${version})\x1b[0m`);
   console.log("──────────────────────────────────────────────");
+  console.log(`Version:   v${version}`);
   console.log(`Daemon:    ${pid ? `\x1b[32m● Running\x1b[0m (PID ${pid})` : "\x1b[33m○ Stopped\x1b[0m"}`);
   console.log(`AMQ Root:  ${amqRoot ? `\x1b[36m${amqRoot}\x1b[0m` : "\x1b[31mNot found\x1b[0m"}`);
   console.log(`State Dir: ${getStateDir()}`);
@@ -109,17 +114,19 @@ export function handleDoorbell() {
     process.exit(1);
   }
 
-  console.log(`🔔 Checking AMQ inboxes at ${amqRoot}...`);
-  const res = runDoorbellPass({ amqRoot });
+  const force = process.argv.includes("--force") || process.argv.includes("-f");
+  console.log(`🔔 Checking AMQ inboxes at ${amqRoot}${force ? " (force=true)" : ""}...`);
+  const res = runDoorbellPass({ amqRoot, force });
 
   if (!res.ok) {
     console.error(`❌ Doorbell check failed: ${res.error}`);
     return;
   }
 
-  console.log(`Checked ${res.agentsChecked} agents. Doorbelled: ${res.doorbelled} message(s).`);
+  console.log(`Checked ${res.agentsChecked} agents. Doorbelled: ${res.doorbelled} message(s), ${res.doorbelledTasks || 0} task(s).`);
   for (const r of res.results || []) {
-    console.log(`  - ${r.handle} (${r.status}): ${r.count} msg(s) -> ${r.action}`);
+    const taskInfo = r.tasksCount ? `, ${r.tasksCount} task(s)` : "";
+    console.log(`  - ${r.handle} (${r.status}): ${r.count} msg(s)${taskInfo} -> ${r.action}`);
   }
 }
 
@@ -380,12 +387,75 @@ export function handleTaskCommand(subcommand = "list", rawArgs = []) {
       break;
     }
 
+    case "drain": {
+      const claim = Boolean(flags.claim || flags.autoClaim);
+      const res = drainTasks(repoRoot, amqRoot, {
+        me,
+        claim,
+        notify: flags.notify !== "false",
+      });
+
+      if (flags.json) {
+        console.log(JSON.stringify(res, null, 2));
+        return;
+      }
+
+      console.log(`\n📋 \x1b[1mTask Drain for ${me}\x1b[0m (${res.count} pending backlog task(s))`);
+      console.log("────────────────────────────────────────────────────────────────────────────");
+
+      if (res.activeTasks && res.activeTasks.length > 0) {
+        for (const at of res.activeTasks) {
+          console.log(`⚡ \x1b[33mActive task in progress (doing):\x1b[0m \x1b[1m${at.title}\x1b[0m (ID: ${at.id})`);
+        }
+        console.log("────────────────────────────────────────────────────────────────────────────");
+      }
+
+      if (res.tasks.length === 0) {
+        console.log(`  (no pending backlog tasks assigned to ${me})`);
+      } else {
+        for (const t of res.tasks) {
+          const isClaimed = res.claimedTask && res.claimedTask.id === t.id;
+          const statusStr = isClaimed
+            ? `\x1b[32m[CLAIMED -> in_progress]\x1b[0m`
+            : `\x1b[34m[backlog]\x1b[0m`;
+
+          console.log(`\n${statusStr} \x1b[1m${t.title}\x1b[0m (ID: \x1b[36m${t.id}\x1b[0m)`);
+          if (t.created) console.log(`  Created: ${t.created}`);
+          if (t.description) {
+            console.log(`  Details:`);
+            for (const line of t.description.split("\n")) {
+              console.log(`    ${line}`);
+            }
+          }
+        }
+
+        console.log("\n────────────────────────────────────────────────────────────────────────────");
+        if (res.claimedTask) {
+          console.log(`🚀 \x1b[32mAuto-claimed task ${res.claimedTask.id} into doing/\x1b[0m (status: in_progress)`);
+          console.log(`✉️ Notification dispatched to coordinator via AMQ.`);
+        } else {
+          console.log(`👉 \x1b[1mTo claim a task:\x1b[0m`);
+          console.log(`   herdr-amq task claim ${res.tasks[0].id} --me ${me}`);
+          console.log(`   or auto-claim next: herdr-amq task next --me ${me}`);
+        }
+      }
+      console.log("────────────────────────────────────────────────────────────────────────────\n");
+      break;
+    }
+
+    case "next": {
+      handleTaskCommand("drain", [...rawArgs, "--claim"]);
+      break;
+    }
+
     default:
       console.log(`\n📋 \x1b[1mAGboard Task Coordination CLI\x1b[0m`);
       console.log("────────────────────────────────────────────────────────────────────────────");
       console.log("Usage: herdr-amq task <subcommand> [options]");
       console.log("\nCommands:");
       console.log("  list [--owner <h>] [--status <s>] [--json]   List all tasks");
+      console.log("  drain [--me <h>] [--claim] [--json]           Drain backlog tasks with full descriptions");
+      console.log("  next [--me <h>]                               Auto-claim and start next backlog task");
       console.log("  assign --to <h> --title <t> [--desc <d>]      Assign a new task to an agent");
       console.log("  claim <id> [--me <h>]                         Claim an existing task");
       console.log("  done <id> [--me <h>] [--proof <evidence>]     Complete a task with proof");
@@ -567,8 +637,15 @@ export function handleSkillCommand(args = []) {
       destDir = path.resolve(process.cwd(), destDir);
     }
 
+    let targetFile;
+    if (destDir.endsWith(".md")) {
+      targetFile = destDir;
+      destDir = path.dirname(destDir);
+    } else {
+      targetFile = path.join(destDir, "SKILL.md");
+    }
+
     fs.mkdirSync(destDir, { recursive: true });
-    const targetFile = path.join(destDir, "SKILL.md");
     fs.writeFileSync(targetFile, content, "utf-8");
     console.log(`✅ Successfully installed herdr-amq skill to ${targetFile}`);
     return targetFile;
@@ -654,12 +731,14 @@ Usage: herdr-amq fleet <command> [options]
 Commands:
   status, list     Show discovered fleet personas, worktrees, and Herdr status
   prepopulate      Create AMQ maildirs and worktrees for all fleet personas
-  up               Launch missing fleet agents into Herdr terminal tabs
+  up               Launch missing agents and replace mismatched kinds
+  down             Close fleet agent panes without removing worktrees
 
 Options:
-  --kind <kind>    Agent kind to launch (default: agy, options: agy, opencode, pi)
+  --kind <kind>    Agent kind (default: agy for up, required for down)
   --agents <list>  Comma-separated handles to target (default: all)
-  --dry-run        Preview actions without creating tabs or starting agents
+  --no-replace     Refuse to replace agents running as another kind
+  --dry-run        Preview actions without changing panes
   --help, -h       Show this help message
 `);
     return;
@@ -675,7 +754,7 @@ Options:
     for (const [handle, p] of personas.entries()) {
       const live = liveMap.get(handle);
       const liveBadge = live
-        ? `\x1b[32m● ${live.agent_status} (${live.pane_id})\x1b[0m`
+        ? `\x1b[32m● ${live.agent || "unknown"} ${live.agent_status} (${live.pane_id})\x1b[0m`
         : `\x1b[90m○ offline\x1b[0m`;
       const wtExists = fs.existsSync(path.join(repoRoot, ".worktrees", handle));
       const wtBadge = wtExists ? "worktree: ok" : "\x1b[33mno worktree\x1b[0m";
@@ -696,24 +775,82 @@ Options:
     return;
   }
 
+  if (subcommand === "down") {
+    const kindIdx = rawArgs.indexOf("--kind");
+    const kind = kindIdx !== -1 && rawArgs[kindIdx + 1] ? rawArgs[kindIdx + 1] : null;
+    const agentsIdx = rawArgs.indexOf("--agents");
+    const agents = agentsIdx !== -1 && rawArgs[agentsIdx + 1] ? rawArgs[agentsIdx + 1] : null;
+    const dryRun = rawArgs.includes("--dry-run");
+    if (!kind) {
+      console.error("❌ fleet down requires --kind <agy|opencode|pi>");
+      process.exitCode = 1;
+      return;
+    }
+
+    console.log(`\n🛑 \x1b[1mStopping Fleet via Herdr (kind: ${kind})\x1b[0m`);
+    console.log("──────────────────────────────────────────────");
+    if (dryRun) console.log("Mode: \x1b[33mDry Run (preview only)\x1b[0m\n");
+
+    const res = await stopFleet(amqRoot, repoRoot, { kind, agents, dryRun });
+    if (dryRun && res.wouldStop.length > 0) {
+      console.log(`\x1b[33m⚡ Would stop (${res.wouldStop.length}):\x1b[0m ${[...new Set(res.wouldStop.map((entry) => entry.handle))].join(", ")}`);
+    }
+    if (res.stopped.length > 0) {
+      console.log(`\x1b[32m✔ Stopped agents (${res.stopped.length}):\x1b[0m`);
+      for (const entry of res.stopped) {
+        console.log(`   • ${entry.handle} -> pane ${entry.paneId} (${entry.kind})`);
+      }
+    }
+    if (res.skipped.length > 0) {
+      console.log(`\x1b[33m↷ Skipped mismatched agents (${res.skipped.length}):\x1b[0m`);
+      for (const entry of res.skipped) {
+        console.log(`   • ${entry.handle}: ${entry.reason}`);
+      }
+    }
+    if (res.failed.length > 0) {
+      console.log(`\x1b[31m✖ Failed to stop:\x1b[0m`);
+      for (const entry of res.failed) {
+        console.log(`   • ${entry.handle} (${entry.paneId}): ${entry.error}`);
+      }
+    }
+    console.log("\n✅ Fleet stop pass complete. Worktrees and maildirs were preserved.\n");
+    return res;
+  }
+
   if (subcommand === "up") {
     const kindIdx = rawArgs.indexOf("--kind");
     const kind = kindIdx !== -1 && rawArgs[kindIdx + 1] ? rawArgs[kindIdx + 1] : "agy";
     const agentsIdx = rawArgs.indexOf("--agents");
     const agents = agentsIdx !== -1 && rawArgs[agentsIdx + 1] ? rawArgs[agentsIdx + 1] : null;
     const dryRun = rawArgs.includes("--dry-run");
+    const replace = !rawArgs.includes("--no-replace");
 
     console.log(`\n🚀 \x1b[1mLaunching Fleet via Herdr (kind: ${kind})\x1b[0m`);
     console.log("──────────────────────────────────────────────");
     if (dryRun) console.log("Mode: \x1b[33mDry Run (preview only)\x1b[0m\n");
 
-    const res = await launchFleet(amqRoot, repoRoot, { kind, agents, dryRun });
+    const res = await launchFleet(amqRoot, repoRoot, { kind, agents, dryRun, replace });
     if (res.alreadyRunning.length > 0) {
       console.log(`\x1b[36m● Already running (${res.alreadyRunning.length}):\x1b[0m ${res.alreadyRunning.join(", ")}`);
     }
+    if (res.replaced.length > 0) {
+      console.log(`\x1b[33m↻ Replaced mismatched agents (${res.replaced.length}):\x1b[0m`);
+      for (const entry of res.replaced) {
+        console.log(`   • ${entry.handle}: ${entry.fromKinds.join(", ")} -> ${kind}`);
+      }
+    }
+    if (dryRun && res.wouldReplace.length > 0) {
+      console.log(`\x1b[33m⚡ Would replace (${res.wouldReplace.length}):\x1b[0m ${res.wouldReplace.join(", ")}`);
+    }
     if (dryRun && res.wouldLaunch.length > 0) {
       console.log(`\x1b[33m⚡ Would launch into Herdr (${res.wouldLaunch.length}):\x1b[0m ${res.wouldLaunch.join(", ")}`);
     }
+    if (res.blocked.length > 0) {
+      console.log(`\x1b[33m↷ Blocked mismatched agents (${res.blocked.length}):\x1b[0m`);
+      for (const entry of res.blocked) {
+        console.log(`   • ${entry.handle}: ${entry.reason}`);
+      }
+    }
     if (res.launched.length > 0) {
       console.log(`\x1b[32m✔ Launched agents (${res.launched.length}):\x1b[0m`);
       for (const l of res.launched) {

package/src/board.mjs

@@ -29,22 +29,34 @@ export function findStatusFile(repoRoot) {
 
 /**
  * Locate the global bus directory for tasks.
- * Defaults to .opencode/bus (or .agent-mail/bus).
+ * Defaults to .agent-mail/bus (lives alongside agent mailboxes and blobs).
+ * Falls back to legacy .opencode/bus if present.
  */
 export function getBusDirectory(repoRoot, amqRoot) {
+  if (process.env.AMQ_BUS_DIR) {
+    return path.resolve(process.env.AMQ_BUS_DIR);
+  }
+  // 1. Primary: .agent-mail/bus if amqRoot is provided
+  if (amqRoot) {
+    const amqBus = path.join(amqRoot, "bus");
+    if (fs.existsSync(amqBus)) return amqBus;
+  }
+  // 2. Check repoRoot/.agent-mail/bus
   if (repoRoot) {
+    const repoAmqBus = path.join(repoRoot, ".agent-mail", "bus");
+    if (fs.existsSync(repoAmqBus)) return repoAmqBus;
+    // 3. Fallback to legacy .opencode/bus if it exists
     const opencodeBus = path.join(repoRoot, ".opencode", "bus");
-    if (fs.existsSync(opencodeBus)) {
-      return opencodeBus;
-    }
+    if (fs.existsSync(opencodeBus)) return opencodeBus;
   }
+  // Default new creation target: .agent-mail/bus
   if (amqRoot) {
     return path.join(amqRoot, "bus");
   }
   if (repoRoot) {
-    return path.join(repoRoot, ".opencode", "bus");
+    return path.join(repoRoot, ".agent-mail", "bus");
   }
-  return path.join(process.cwd(), ".opencode", "bus");
+  return path.join(process.cwd(), ".agent-mail", "bus");
 }
 
 export const STAGE_DIRS = {
@@ -758,3 +770,129 @@ export function deleteBoardTask(repoRoot, amqRoot, taskId) {
 
   return { ok: true, taskId, deleted };
 }
+
+/**
+ * List pending backlog tasks assigned to a specific handle (or all backlog tasks if null/all).
+ */
+export function listBacklogTasks(repoRoot, amqRoot, handle = null) {
+  const busDir = getBusDirectory(repoRoot, amqRoot);
+  const backlogDir = path.join(busDir, "backlog");
+  if (!fs.existsSync(backlogDir)) return [];
+
+  try {
+    const files = fs.readdirSync(backlogDir).filter((f) => f.endsWith(".md") && !f.startsWith("."));
+    const tasks = [];
+    const target = handle && handle !== "all" ? canonicalizeOwner(handle) : null;
+
+    for (const f of files) {
+      const fullPath = path.join(backlogDir, f);
+      const parsed = parseTaskFile(fullPath, "backlog");
+      if (parsed) {
+        if (!target || parsed.owner === target) {
+          tasks.push(parsed);
+        }
+      }
+    }
+    tasks.sort((a, b) => (a.created || "").localeCompare(b.created || ""));
+    return tasks;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Drain tasks for an agent: returns all pending backlog tasks with full descriptions,
+ * optionally auto-claiming the first available task if claim: true.
+ */
+export function drainTasks(repoRoot, amqRoot, { me, claim = false, notify = true } = {}) {
+  const target = me ? canonicalizeOwner(me) : "coordinator";
+  const tasks = listBacklogTasks(repoRoot, amqRoot, target);
+
+  let claimedTask = null;
+  if (claim && tasks.length > 0) {
+    const toClaim = tasks[0];
+    const res = updateBoardTask(
+      repoRoot,
+      amqRoot,
+      toClaim.id,
+      { status: "in_progress", owner: target },
+      { from: target, notify }
+    );
+    if (res.ok) {
+      claimedTask = res.task;
+    }
+  }
+
+  // Also discover any active tasks currently in doing/in_progress
+  const busDir = getBusDirectory(repoRoot, amqRoot);
+  const doingDir = path.join(busDir, resolveStageDir(busDir, "doing"));
+  const activeTasks = [];
+  if (fs.existsSync(doingDir)) {
+    try {
+      const files = fs.readdirSync(doingDir).filter((f) => f.endsWith(".md") && !f.startsWith("."));
+      for (const f of files) {
+        const fullPath = path.join(doingDir, f);
+        const parsed = parseTaskFile(fullPath, "in_progress");
+        if (parsed && parsed.owner === target) {
+          activeTasks.push(parsed);
+        }
+      }
+    } catch {}
+  }
+
+  return {
+    ok: true,
+    owner: target,
+    count: tasks.length,
+    tasks,
+    activeTasks,
+    claimedTask,
+  };
+}
+
+/**
+ * Fast query of task numbers/statistics for an agent across stages:
+ * { backlog, doing, blocked, done, total }
+ */
+export function getAgentTaskStats(repoRoot, amqRoot, handle) {
+  const target = handle ? canonicalizeOwner(handle) : null;
+  const busDir = getBusDirectory(repoRoot, amqRoot);
+  const stages = [
+    { dir: "backlog", key: "backlog" },
+    { dir: "doing", key: "doing" },
+    { dir: "in_progress", key: "doing" },
+    { dir: "blocked", key: "blocked" },
+    { dir: "done", key: "done" },
+  ];
+
+  const stats = {
+    backlog: 0,
+    doing: 0,
+    blocked: 0,
+    done: 0,
+    total: 0,
+  };
+
+  const seenIds = new Set();
+
+  for (const { dir, key } of stages) {
+    const fullDir = path.join(busDir, dir);
+    if (!fs.existsSync(fullDir)) continue;
+    try {
+      const files = fs.readdirSync(fullDir).filter((f) => f.endsWith(".md") && !f.startsWith("."));
+      for (const f of files) {
+        const fullPath = path.join(fullDir, f);
+        const parsed = parseTaskFile(fullPath, key);
+        if (parsed && (!target || parsed.owner === target)) {
+          if (!seenIds.has(parsed.id)) {
+            seenIds.add(parsed.id);
+            stats[key]++;
+            stats.total++;
+          }
+        }
+      }
+    } catch {}
+  }
+
+  return stats;
+}

package/src/bridge.mjs

@@ -6,9 +6,11 @@ import {
   getStateDir,
   getConfigDir,
   findAmqRoot,
+  getRepoRootFromAmq,
   getAgentHandles,
   execCmd,
 } from "./config.mjs";
+import { listBacklogTasks, getAgentTaskStats } from "./board.mjs";
 
 function getPidFile() {
   return path.join(getStateDir(), "bridge.pid");
@@ -120,7 +122,7 @@ function healAgentName(handle, dryRun = false) {
 }
 
 function promptAgent(handle, text, dryRun = false) {
-  if (dryRun) {
+  if (dryRun || process.env.HERDR_DISABLE_PROMPT === "1" || process.env.NODE_ENV === "test") {
     console.log(`[bridge] DRY: would prompt ${handle}: ${text.slice(0, 60)}...`);
     return true;
   }
@@ -152,9 +154,12 @@ function recordAlert(handle, count, from, dryRun = false) {
 function loadDeliveredState() {
   const stateFile = getStateFile();
   try {
-    return JSON.parse(fs.readFileSync(stateFile, "utf8"));
+    const s = JSON.parse(fs.readFileSync(stateFile, "utf8"));
+    s.delivered = s.delivered || {};
+    s.deliveredTasks = s.deliveredTasks || {};
+    return s;
   } catch {
-    return { delivered: {} };
+    return { delivered: {}, deliveredTasks: {} };
   }
 }
 
@@ -167,6 +172,13 @@ function saveDeliveredState(state) {
       delete state.delivered[id];
     }
   }
+  const taskIds = Object.keys(state.deliveredTasks || {});
+  if (taskIds.length > 2000) {
+    taskIds.sort();
+    for (const id of taskIds.slice(0, taskIds.length - 1500)) {
+      delete state.deliveredTasks[id];
+    }
+  }
   fs.writeFileSync(stateFile, JSON.stringify(state, null, 1), "utf8");
 }
 
@@ -239,16 +251,64 @@ export function listInbox(amqRoot, handle) {
   }
 }
 
-const buildDoorbellPrompt = (handle, msgs) => {
+export const buildDoorbellPrompt = (handle, msgs = [], taskStatsOrBacklog = null) => {
   const senders = [...new Set(msgs.map((m) => m.from))].join(", ");
-  const n = msgs.length;
+  const mCount = msgs.length;
+
+  let stats;
+  if (Array.isArray(taskStatsOrBacklog)) {
+    stats = { backlog: taskStatsOrBacklog.length, blocked: 0, doing: 0, done: 0 };
+  } else if (taskStatsOrBacklog && typeof taskStatsOrBacklog === "object") {
+    stats = taskStatsOrBacklog;
+  } else {
+    stats = { backlog: 0, blocked: 0, doing: 0, done: 0 };
+  }
+
+  const bCount = stats.backlog || 0;
+
+  // Build task numbers breakdown string: e.g. " (1 blocked, 2 in progress, 3 done)"
+  const taskDetails = [];
+  if (stats.blocked > 0) taskDetails.push(`${stats.blocked} blocked`);
+  if (stats.doing > 0) taskDetails.push(`${stats.doing} in progress`);
+  if (stats.done > 0) taskDetails.push(`${stats.done} done`);
+  const detailsStr = taskDetails.length > 0 ? ` (${taskDetails.join(", ")})` : "";
+
+  if (mCount > 0 && bCount > 0) {
+    return (
+      `AMQ & Task doorbell: ${mCount} new message(s) from ${senders}. You have ${bCount} task(s) in backlog${detailsStr}. ` +
+      `Run: herdr-amq mail drain --me ${handle} --include-body && herdr-amq task drain --me ${handle}. ` +
+      `Claim next task via: herdr-amq task next --me ${handle}, then reply on-thread with herdr-amq mail reply --id <msg_id>.`
+    );
+  }
+
+  if (bCount > 0) {
+    return (
+      `Task doorbell: You have ${bCount} task(s) in backlog${detailsStr}. ` +
+      `Run: herdr-amq task drain --me ${handle} and claim via: herdr-amq task next --me ${handle}.`
+    );
+  }
+
   return (
-    `AMQ doorbell: ${n} new message(s) in your inbox (from ${senders}). ` +
-    `Run: amq drain --me ${handle} --include-body, then reply to the sender on the same ` +
-    `thread with amq reply --id <msg_id>. After replying, resume your work.`
+    `AMQ doorbell: ${mCount} new message(s) in your inbox from ${senders}${detailsStr}. ` +
+    `Run: herdr-amq mail drain --me ${handle} --include-body, then reply on-thread with herdr-amq mail reply --id <msg_id>. After replying, resume your work.`
   );
 };
 
+export const DEFAULT_DOORBELL_COOLDOWN_MS = 45000; // 45s cooldown window
+
+/**
+ * Determines whether an item was recently doorbelled and is still in-flight.
+ * If the item has not been drained after the cooldown window, it no longer
+ * counts as delivered and will be re-doorbelled.
+ */
+export function isItemPendingDrain(deliveryEntry, cooldownMs = DEFAULT_DOORBELL_COOLDOWN_MS, force = false) {
+  if (force) return false;
+  if (!deliveryEntry || !deliveryEntry.at) return false;
+  const deliveredAt = new Date(deliveryEntry.at).getTime();
+  if (isNaN(deliveredAt)) return false;
+  return Date.now() - deliveredAt < cooldownMs;
+}
+
 // ─── Doorbell Pass ────────────────────────────────────────────────────────────
 
 export function runDoorbellPass({
@@ -256,6 +316,8 @@ export function runDoorbellPass({
   handles = null,
   targetHandle = null,
   dryRun = false,
+  force = false,
+  cooldownMs = parseInt(process.env.HERDR_DOORBELL_COOLDOWN_MS || String(DEFAULT_DOORBELL_COOLDOWN_MS), 10),
 } = {}) {
   if (!amqRoot) {
     return { ok: false, error: "No .agent-mail queue found." };
@@ -266,25 +328,30 @@ export function runDoorbellPass({
     : (handles && handles.length > 0 ? handles : getAgentHandles(amqRoot));
 
   if (!agentList.length) {
-    return { ok: true, checked: 0, doorbelled: 0, message: "No registered agents found." };
+    return { ok: true, checked: 0, doorbelled: 0, doorbelledTasks: 0, message: "No registered agents found." };
   }
 
+  const repoRoot = getRepoRootFromAmq(amqRoot);
   const state = loadDeliveredState();
   state.delivered = state.delivered || {};
+  state.deliveredTasks = state.deliveredTasks || {};
 
   let doorbelledCount = 0;
+  let doorbelledTasksCount = 0;
   const results = [];
 
   for (const handle of agentList) {
     const rawMsgs = listInbox(amqRoot, handle);
     // Ignore self-messages
     const msgs = rawMsgs.filter((m) => m.from !== handle);
+    // If message is still in inbox/new after cooldown, the agent did NOT drain it!
+    const undeliveredMsgs = msgs.filter((m) => !isItemPendingDrain(state.delivered[m.id], cooldownMs, force));
 
-    if (!msgs.length) continue;
+    const backlogTasks = listBacklogTasks(repoRoot, amqRoot, handle);
+    // If task is still in backlog after cooldown, the agent did NOT claim/drain it!
+    const undeliveredTasks = backlogTasks.filter((t) => !isItemPendingDrain(state.deliveredTasks?.[t.id], cooldownMs, force));
 
-    // Filter messages not yet delivered
-    const undelivered = msgs.filter((m) => !state.delivered[m.id]);
-    if (!undelivered.length) continue;
+    if (!undeliveredMsgs.length && !undeliveredTasks.length) continue;
 
     let status = getAgentStatus(handle);
     if (status === "missing") {
@@ -292,33 +359,74 @@ export function runDoorbellPass({
       if (healed) status = getAgentStatus(handle);
     }
 
+    const taskStats = getAgentTaskStats(repoRoot, amqRoot, handle);
+    taskStats.backlog = undeliveredTasks.length > 0 ? undeliveredTasks.length : backlogTasks.length;
+
     if (status === "idle" || status === "done") {
-      const text = buildDoorbellPrompt(handle, undelivered);
+      const text = buildDoorbellPrompt(handle, undeliveredMsgs, taskStats);
       const ok = promptAgent(handle, text, dryRun);
       if (ok) {
-        doorbelledCount += undelivered.length;
+        doorbelledCount += undeliveredMsgs.length;
+        doorbelledTasksCount += undeliveredTasks.length;
         if (!dryRun) {
-          for (const m of undelivered) {
+          for (const m of undeliveredMsgs) {
+            const prev = state.delivered[m.id];
             state.delivered[m.id] = {
               at: new Date().toISOString(),
               to: handle,
               from: m.from,
+              attempts: (prev?.attempts || 0) + 1,
+            };
+          }
+          for (const t of undeliveredTasks) {
+            const prev = state.deliveredTasks[t.id];
+            state.deliveredTasks[t.id] = {
+              at: new Date().toISOString(),
+              to: handle,
+              title: t.title,
+              attempts: (prev?.attempts || 0) + 1,
             };
           }
         }
-        results.push({ handle, status, count: undelivered.length, action: "prompted" });
+        results.push({
+          handle,
+          status,
+          count: undeliveredMsgs.length,
+          tasksCount: undeliveredTasks.length,
+          action: "prompted",
+        });
       }
     } else if (status === "working") {
-      results.push({ handle, status, count: undelivered.length, action: "working_wait" });
+      results.push({
+        handle,
+        status,
+        count: undeliveredMsgs.length,
+        tasksCount: undeliveredTasks.length,
+        action: "working_wait",
+      });
     } else if (status === "blocked") {
-      recordAlert(handle, undelivered.length, undelivered[0]?.from, dryRun);
-      results.push({ handle, status, count: undelivered.length, action: "alert_blocked" });
+      if (undeliveredMsgs.length) {
+        recordAlert(handle, undeliveredMsgs.length, undeliveredMsgs[0]?.from, dryRun);
+      }
+      results.push({
+        handle,
+        status,
+        count: undeliveredMsgs.length,
+        tasksCount: undeliveredTasks.length,
+        action: "alert_blocked",
+      });
     } else {
-      results.push({ handle, status, count: undelivered.length, action: "unknown_state" });
+      results.push({
+        handle,
+        status,
+        count: undeliveredMsgs.length,
+        tasksCount: undeliveredTasks.length,
+        action: "unknown_state",
+      });
     }
   }
 
-  if (!dryRun && doorbelledCount > 0) {
+  if (!dryRun && (doorbelledCount > 0 || doorbelledTasksCount > 0)) {
     saveDeliveredState(state);
   }
 
@@ -327,6 +435,7 @@ export function runDoorbellPass({
     amqRoot,
     agentsChecked: agentList.length,
     doorbelled: doorbelledCount,
+    doorbelledTasks: doorbelledTasksCount,
     results,
   };
 }

package/src/config.mjs

@@ -1,13 +1,37 @@
 import fs from "node:fs";
 import path from "node:path";
 import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export function getPluginVersion() {
+  try {
+    const pkgPath = path.resolve(__dirname, "../package.json");
+    if (fs.existsSync(pkgPath)) {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+      return pkg.version || "unknown";
+    }
+  } catch {}
+  return "unknown";
+}
 
 export function getHerdrBin() {
   return process.env.HERDR_BIN_PATH || "herdr";
 }
 
 export function getStateDir() {
-  const dir = process.env.HERDR_PLUGIN_STATE_DIR || path.join(process.env.HOME || "/tmp", ".herdr-amq-state");
+  if (process.env.HERDR_PLUGIN_STATE_DIR) {
+    const dir = process.env.HERDR_PLUGIN_STATE_DIR;
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    return dir;
+  }
+  const legacyDir = path.join(process.env.HOME || "/tmp", ".herdr-amq-state");
+  if (fs.existsSync(legacyDir)) {
+    return legacyDir;
+  }
+  const base = process.env.XDG_STATE_HOME || path.join(process.env.HOME || "/tmp", ".local", "state");
+  const dir = path.join(base, "herdr-amq");
   if (!fs.existsSync(dir)) {
     fs.mkdirSync(dir, { recursive: true });
   }
@@ -22,7 +46,17 @@ export function getRepoRootFromAmq(amqRoot) {
 }
 
 export function getConfigDir() {
-  const dir = process.env.HERDR_PLUGIN_CONFIG_DIR || path.join(process.env.HOME || "/tmp", ".herdr-amq-config");
+  if (process.env.HERDR_PLUGIN_CONFIG_DIR) {
+    const dir = process.env.HERDR_PLUGIN_CONFIG_DIR;
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    return dir;
+  }
+  const legacyDir = path.join(process.env.HOME || "/tmp", ".herdr-amq-config");
+  if (fs.existsSync(legacyDir)) {
+    return legacyDir;
+  }
+  const base = process.env.XDG_CONFIG_HOME || path.join(process.env.HOME || "/tmp", ".config");
+  const dir = path.join(base, "herdr-amq");
   if (!fs.existsSync(dir)) {
     fs.mkdirSync(dir, { recursive: true });
   }

package/src/fleet.mjs

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
-import { execFileSync, execSync } from "node:child_process";
+import { execFileSync } from "node:child_process";
 import { scanAgentBriefs } from "./briefs.mjs";
 import { ensureAgentWorktree } from "./worktrees.mjs";
 import { registerAgent, formatAgentTitle } from "./store.mjs";
@@ -173,7 +173,143 @@ export function buildFleetEnvPath() {
     process.env.PATH || "",
   ];
 
-  return Array.from(new Set(paths.filter(Boolean))).join(":");
+  return Array.from(new Set(paths.filter(Boolean))).join(path.delimiter);
+}
+
+function filterPersonas(fleet, filter) {
+  if (!filter) return fleet;
+  const selected = new Set(
+    (Array.isArray(filter) ? filter : filter.split(","))
+      .map((value) => value.trim().toLowerCase())
+      .filter(Boolean),
+  );
+  return fleet.filter((agent) => selected.has(agent.handle.toLowerCase()));
+}
+
+function pathsMatch(left, right) {
+  if (!left || !right) return false;
+  try {
+    return fs.realpathSync(left) === fs.realpathSync(right);
+  } catch {
+    return path.resolve(left) === path.resolve(right);
+  }
+}
+
+function matchingFleetPanes(agent, liveAgents) {
+  return liveAgents.filter((live) => (
+    live.name === agent.handle && pathsMatch(live.cwd, agent.worktree)
+  ));
+}
+
+function runHerdr(args, execHerdr) {
+  if (execHerdr) return execHerdr(args);
+  return execFileSync("herdr", args, { encoding: "utf8" });
+}
+
+function waitFor(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export function defaultLaunchArgs(kind, handle) {
+  if (kind === "agy") return ["--dangerously-skip-permissions"];
+  if (kind === "opencode") return ["--agent", handle, "--auto"];
+  return [];
+}
+
+export function resolveExecutable(name, envPath = buildFleetEnvPath()) {
+  for (const dir of envPath.split(path.delimiter)) {
+    if (!dir) continue;
+    const candidate = path.join(dir, name);
+    try {
+      fs.accessSync(candidate, fs.constants.X_OK);
+      if (fs.statSync(candidate).isFile()) return fs.realpathSync(candidate);
+    } catch {}
+  }
+  return null;
+}
+
+function validModel(model) {
+  return typeof model === "string" && /^[^\s/]+\/[^\s/]+/.test(model) ? model : null;
+}
+
+export function readOpencodeModel(worktree) {
+  for (const relativePath of ["opencode.json", path.join(".opencode", "opencode.json")]) {
+    const configPath = path.join(worktree, relativePath);
+    try {
+      const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+      const model = validModel(config.model);
+      if (model) return model;
+    } catch {}
+  }
+  return null;
+}
+
+function shellQuote(value) {
+  return `'${String(value).replaceAll("'", "'\"'\"'")}'`;
+}
+
+export function createOpencodeLauncher(handle, model, executable) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "herdr-amq-opencode-"));
+  const binDir = path.join(root, handle.replace(/[^a-zA-Z0-9._-]/g, "_"));
+  fs.mkdirSync(binDir, { recursive: true });
+  const agentConfig = { mode: "all" };
+  const selectedModel = validModel(model);
+  if (selectedModel) agentConfig.model = selectedModel;
+  const config = JSON.stringify({ agent: { [handle]: agentConfig } });
+  const launcher = path.join(binDir, "opencode");
+  fs.writeFileSync(
+    launcher,
+    `#!/bin/sh\nexport OPENCODE_CONFIG_CONTENT=${shellQuote(config)}\nexec ${shellQuote(executable)} "$@"\n`,
+    { mode: 0o700 },
+  );
+  return { root, binDir, launcher, config };
+}
+
+export async function stopFleet(amqRoot, repoRoot, options = {}) {
+  const personas = discoverFleetPersonas(repoRoot);
+  const fleet = [...personas.values()].map((agent) => ({
+    ...agent,
+    worktree: path.join(repoRoot, ".worktrees", agent.handle),
+  }));
+  const targetFleet = filterPersonas(fleet, options.agents);
+  const kind = options.kind || null;
+  const dryRun = Boolean(options.dryRun);
+  const getLiveAgents = options.getLiveAgents || getHerdrAgents;
+  const execHerdr = options.execHerdr || null;
+  const liveAgents = await getLiveAgents();
+  const result = {
+    total: targetFleet.length,
+    stopped: [],
+    wouldStop: [],
+    skipped: [],
+    failed: [],
+    dryRun,
+  };
+
+  for (const agent of targetFleet) {
+    const panes = matchingFleetPanes(agent, liveAgents);
+    const selected = kind ? panes.filter((pane) => pane.agent === kind) : panes;
+    if (selected.length === 0) {
+      if (panes.length > 0) {
+        result.skipped.push({ handle: agent.handle, reason: `kind is ${panes.map((pane) => pane.agent).join(", ")}` });
+      }
+      continue;
+    }
+    if (dryRun) {
+      result.wouldStop.push(...selected.map((pane) => ({ handle: agent.handle, paneId: pane.pane_id, kind: pane.agent })));
+      continue;
+    }
+    for (const pane of selected) {
+      try {
+        runHerdr(["pane", "close", pane.pane_id], execHerdr);
+        result.stopped.push({ handle: agent.handle, paneId: pane.pane_id, kind: pane.agent });
+      } catch (error) {
+        result.failed.push({ handle: agent.handle, paneId: pane.pane_id, error: error.message });
+      }
+    }
+  }
+
+  return result;
 }
 
 /**
@@ -183,135 +319,168 @@ export async function launchFleet(amqRoot, repoRoot, options = {}) {
   const kind = options.kind || "agy";
   const dryRun = Boolean(options.dryRun);
   const timeoutMs = options.timeout || 25000;
-  const customArgs = options.args || (kind === "agy" ? ["--dangerously-skip-permissions"] : []);
-  const filterList = options.agents
-    ? (Array.isArray(options.agents) ? options.agents : options.agents.split(",")).map((s) => s.trim().toLowerCase())
-    : null;
-
-  // 1. Prepopulate maildirs and worktrees
-  const fleet = prepopulateFleet(amqRoot, repoRoot);
-  const targetFleet = filterList ? fleet.filter((f) => filterList.includes(f.handle)) : fleet;
-
+  const replace = options.replace !== false;
+  const prepopulate = options.prepopulate || prepopulateFleet;
+  const getLiveAgents = options.getLiveAgents || getHerdrAgents;
+  const execHerdr = options.execHerdr || null;
+  const sleep = options.sleep || waitFor;
+  const safePath = options.envPath || buildFleetEnvPath();
+  const configuredArgs = options.args == null
+    ? defaultLaunchArgs(kind, "")
+    : Array.isArray(options.args) ? options.args : [String(options.args)];
+  const fleet = prepopulate(amqRoot, repoRoot);
+  const targetFleet = filterPersonas(fleet, options.agents);
   const result = {
     total: targetFleet.length,
-    prepopulated: targetFleet.map((t) => t.handle),
+    prepopulated: targetFleet.map((agent) => agent.handle),
     alreadyRunning: [],
+    replaced: [],
+    wouldReplace: [],
     wouldLaunch: [],
+    blocked: [],
     launched: [],
     failed: [],
     dryRun,
   };
-
-  // 2. Check Herdr connectivity and live agents
-  let activeHandles = new Set();
-  try {
-    const liveAgents = await getHerdrAgents();
-    activeHandles = new Set(liveAgents.map((a) => a.name).filter(Boolean));
-  } catch {}
-
-  for (const agent of targetFleet) {
-    if (activeHandles.has(agent.handle)) {
-      result.alreadyRunning.push(agent.handle);
-    } else {
-      result.wouldLaunch.push(agent.handle);
-    }
-  }
-
-  if (dryRun) {
-    return result;
-  }
-
-  // Determine Herdr workspace
+  const liveAgents = await getLiveAgents();
+  const launcherRoots = new Set();
   let workspaceId = process.env.HERDR_WORKSPACE_ID || null;
-  if (!workspaceId) {
-    try {
-      const wsRaw = execFileSync("herdr", ["workspace", "list"], { encoding: "utf8" });
-      const wsJson = JSON.parse(wsRaw);
-      const workspaces = wsJson?.result?.workspaces || [];
-      const matched = workspaces.find((w) => w.cwd === repoRoot || w.label === path.basename(repoRoot));
-      workspaceId = matched ? matched.workspace_id : (workspaces[0]?.workspace_id || null);
-    } catch {}
-  }
-
-  const safePath = buildFleetEnvPath();
 
-  // 4. Launch each non-active agent into a tab
-  for (const agent of targetFleet) {
-    const handle = agent.handle;
-    if (activeHandles.has(handle)) {
-      result.alreadyRunning.push(handle);
-      continue;
+  try {
+    if (!dryRun && !workspaceId) {
+      try {
+        const workspaceOutput = runHerdr(["workspace", "list"], execHerdr);
+        const workspaceJson = JSON.parse(workspaceOutput);
+        const workspaces = workspaceJson?.result?.workspaces || [];
+        const matched = workspaces.find((workspace) => workspace.cwd === repoRoot || workspace.label === path.basename(repoRoot));
+        workspaceId = matched ? matched.workspace_id : (workspaces[0]?.workspace_id || null);
+      } catch {}
     }
 
-    try {
-      // Create tab in Herdr targeting worktree
-      const tabArgs = [
-        "tab",
-        "create",
-        "--cwd",
-        agent.worktree,
-        "--label",
-        handle,
-        "--env",
-        `PATH=${safePath}`,
-        "--no-focus",
-      ];
-      if (workspaceId) {
-        tabArgs.push("--workspace", workspaceId);
+    for (const agent of targetFleet) {
+      const handle = agent.handle;
+      const panes = matchingFleetPanes(agent, liveAgents);
+      const matchingKind = panes.filter((pane) => pane.agent === kind);
+
+      if (matchingKind.length > 0) {
+        result.alreadyRunning.push(handle);
+        for (const duplicate of matchingKind.slice(1)) {
+          try {
+            runHerdr(["pane", "close", duplicate.pane_id], execHerdr);
+          } catch (error) {
+            result.failed.push({ handle, error: error.message });
+          }
+        }
+        continue;
       }
 
-      const tabOut = execFileSync("herdr", tabArgs, { encoding: "utf8" });
-      const tabJson = JSON.parse(tabOut);
-      const paneId = tabJson?.result?.root_pane?.pane_id;
-
-      if (!paneId) {
-        throw new Error(`Failed to acquire pane_id from herdr tab create: ${tabOut}`);
+      if (panes.length > 0) {
+        if (dryRun) {
+          result.wouldReplace.push(handle);
+          continue;
+        }
+        if (!replace) {
+          result.blocked.push({ handle, reason: `already running as ${panes.map((pane) => pane.agent).join(", ")}` });
+          continue;
+        }
+        try {
+          for (const pane of panes) {
+            runHerdr(["pane", "close", pane.pane_id], execHerdr);
+          }
+          await sleep(300);
+          result.replaced.push({
+            handle,
+            fromKinds: panes.map((pane) => pane.agent),
+            paneIds: panes.map((pane) => pane.pane_id),
+          });
+        } catch (error) {
+          result.failed.push({ handle, error: error.message });
+          continue;
+        }
       }
 
-      // Start the agent in the new pane with retry if the shell is still booting
-      const startArgs = [
-        "agent",
-        "start",
-        handle,
-        "--kind",
-        kind,
-        "--pane",
-        paneId,
-        "--timeout",
-        String(timeoutMs),
-      ];
-
-      if (customArgs.length > 0) {
-        startArgs.push("--", ...customArgs);
+      if (dryRun) {
+        result.wouldLaunch.push(handle);
+        continue;
       }
 
-      let started = false;
-      let lastErr = null;
-      for (let attempt = 0; attempt < 5; attempt++) {
-        try {
-          if (attempt === 0) {
-            await new Promise((r) => setTimeout(r, 800));
-          } else {
-            await new Promise((r) => setTimeout(r, 1200));
-          }
-          execFileSync("herdr", startArgs, { encoding: "utf8" });
-          started = true;
-          result.launched.push({ handle, paneId, kind });
-          break;
-        } catch (err) {
-          lastErr = err;
-          if (err.message && err.message.includes("agent_pane_busy")) {
-            continue;
-          }
-          break;
+      let paneId;
+      try {
+        let launchPath = safePath;
+        if (kind === "opencode") {
+          const executable = options.opencodeExecutable || resolveExecutable("opencode", safePath);
+          if (!executable) throw new Error("OpenCode executable not found in fleet PATH");
+          const createLauncher = options.createOpencodeLauncher || createOpencodeLauncher;
+          const launcher = createLauncher(handle, readOpencodeModel(agent.worktree), executable);
+          launcherRoots.add(launcher.root);
+          launchPath = `${launcher.binDir}${path.delimiter}${safePath}`;
         }
-      }
 
-      if (!started) {
-        result.failed.push({ handle, error: lastErr?.message || "Failed to start agent" });
+        const tabArgs = [
+          "tab",
+          "create",
+          "--cwd",
+          agent.worktree,
+          "--label",
+          handle,
+          "--env",
+          `PATH=${launchPath}`,
+          "--no-focus",
+        ];
+        if (workspaceId) tabArgs.push("--workspace", workspaceId);
+        const tabOutput = runHerdr(tabArgs, execHerdr);
+        const tabJson = JSON.parse(tabOutput);
+        paneId = tabJson?.result?.root_pane?.pane_id;
+        if (!paneId) throw new Error(`Failed to acquire pane_id from herdr tab create: ${tabOutput}`);
+
+        const startArgs = [
+          "agent",
+          "start",
+          handle,
+          "--kind",
+          kind,
+          "--pane",
+          paneId,
+          "--timeout",
+          String(timeoutMs),
+        ];
+        const launchArgs = kind === "opencode" && options.args == null
+          ? defaultLaunchArgs(kind, handle)
+          : configuredArgs;
+        if (launchArgs.length > 0) startArgs.push("--", ...launchArgs);
+
+        let started = false;
+        let lastError = null;
+        for (let attempt = 0; attempt < 5; attempt++) {
+          try {
+            await sleep(attempt === 0 ? 800 : 1200);
+            runHerdr(startArgs, execHerdr);
+            started = true;
+            result.launched.push({ handle, paneId, kind });
+            break;
+          } catch (error) {
+            lastError = error;
+            if (error.message && error.message.includes("agent_pane_busy")) continue;
+            break;
+          }
+        }
+        if (!started) {
+          throw lastError || new Error("Failed to start agent");
+        }
+      } catch (error) {
+        result.failed.push({ handle, error: error.message || String(error) });
+        if (paneId) {
+          try {
+            runHerdr(["pane", "close", paneId], execHerdr);
+          } catch {}
+        }
       }
-    } catch (err) {
-      result.failed.push({ handle, error: err.message });
+    }
+  } finally {
+    for (const root of launcherRoots) {
+      try {
+        fs.rmSync(root, { recursive: true, force: true });
+      } catch {}
     }
   }