herdr-plugin-amq 0.1.7 → 0.1.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "herdr-plugin-amq",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Herdr plugin for AMQ (Agent Message Queue) autonomous bridge, status monitoring, and AGmail dashboard",
   "type": "module",
   "main": "src/index.mjs",
@@ -11,6 +11,7 @@
     "bin/",
     "src/",
     "skills/",
+    "docs/",
     "herdr-plugin.toml",
     "README.md",
     "LICENSE"
@@ -19,9 +20,11 @@
     "node": ">=18.0.0"
   },
   "scripts": {
-    "test": "node --test test/*.test.mjs",
-    "test:coverage": "mkdir -p coverage && node --test --experimental-test-coverage --test-reporter=spec --test-reporter=lcov --test-reporter-destination=stdout --test-reporter-destination=coverage/lcov.info test/*.test.mjs",
-    "check": "node --check bin/herdr-amq.mjs src/*.mjs test/*.test.mjs",
+    "test": "HERDR_DISABLE_PROMPT=1 node --test test/*.test.mjs",
+    "test:coverage": "mkdir -p coverage && HERDR_DISABLE_PROMPT=1 node --test --experimental-test-coverage --test-reporter=spec --test-reporter=lcov --test-reporter-destination=stdout --test-reporter-destination=coverage/lcov.info test/*.test.mjs",
+    "test:e2e": "HERDR_DISABLE_PROMPT=1 node --test test/e2e/*.test.mjs",
+    "test:visual": "npm run test:e2e",
+    "check": "node --check bin/herdr-amq.mjs src/*.mjs src/web/app.js test/*.test.mjs test/e2e/*.mjs",
     "test:security": "node --test test/security.test.mjs",
     "coverage:summary": "node tools/coverage-summary.mjs",
     "status": "node bin/herdr-amq.mjs status",
@@ -46,5 +49,8 @@
     "agmail"
   ],
   "author": "cabra.lat",
-  "license": "MIT"
+  "license": "MIT",
+  "devDependencies": {
+    "playwright-core": "1.48.2"
+  }
 }

package/skills/herdr-amq/SKILL.md

@@ -12,18 +12,22 @@ 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:
+   Registration welcomes are status messages. Drain them, but do not reply unless the welcome explicitly requests action.
+2. **Reply Only When Action Is Requested**: Reply on the same thread/ref chain when a message asks a question, requests action, or reports a blocker. Do not reply to terminal ACKs or informational status messages, which prevents ACK loops:
    ```bash
    herdr-amq mail reply --me <handle> --id <msg_id> --body "..."
    ```
 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 +54,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 |
@@ -66,7 +72,7 @@ Unifies external tool agent briefs (`.opencode/agents`, `.agents`, `.pi/agents`,
 | Command | Usage | Description |
 |---|---|---|
 | `fleet status` | `herdr-amq fleet status` | Discover personas across external tools and show live Herdr pane states |
-| `fleet prepopulate` | `herdr-amq fleet prepopulate` | Ensure Maildirs, Git worktrees, and workspace trust exist for all personas |
+| `fleet prepopulate` | `herdr-amq fleet prepopulate` | Ensure Maildirs, Git worktrees, and workspace trust exist; welcome each newly registered agent once |
 | `fleet up` | `herdr-amq fleet up [--kind agy\|opencode\|pi]` | Launch missing fleet agents into isolated Herdr tabs with auto-trust & clean PATH |
 | `bootstrap` | `herdr-amq bootstrap [--kind agy]` | Instant cold-start: prepopulate + launch fleet + start bridge daemon + doorbell pass |
 | `migrate` | `herdr-amq migrate [--dry-run]` | Migrate historical attachments into CAS blobs or pinned Git commits |
@@ -76,6 +82,6 @@ Unifies external tool agent briefs (`.opencode/agents`, `.agents`, `.pi/agents`,
 | Command | Usage | Description |
 |---|---|---|
 | `status` | `herdr-amq status` | Show bridge daemon status, unread counts per handle, and paths |
-| `doorbell` | `herdr-amq doorbell` | Run a single doorbell pass alerting idle/blocked agents |
+| `doorbell` | `herdr-amq doorbell` | Run a single doorbell pass; operators may customize `.agent-mail/templates/doorbell.md` with scalar substitutions |
 | `dashboard` | `herdr-amq dashboard [--port 8505]` | Launch web AGmail UI & REST API |
 | `--skill` | `herdr-amq --skill [--install [dir]]` | Print or install this agentic skill definition |

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, allowPrompt: true, persistState: true });
 
   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}`);
   }
 }
 
@@ -140,7 +147,7 @@ export function handleAgentStatusChanged() {
   if (status === "idle" || status === "done") {
     const amqRoot = findAmqRoot();
     if (amqRoot && handle) {
-      runDoorbellPass({ amqRoot, targetHandle: handle });
+      runDoorbellPass({ amqRoot, targetHandle: handle, allowPrompt: true, persistState: true });
     }
   }
 }
@@ -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;
+}