herdr-plugin-amq 0.1.5 → 0.1.7

package/README.md

@@ -158,6 +158,9 @@ herdr plugin action invoke cabra.amq.doorbell-check
 
 # Launch the AGmail webmail dashboard
 herdr plugin action invoke cabra.amq.open-dashboard
+
+# Migrate legacy message attachments into immutable CAS blobs or pinned Git commits
+herdr plugin action invoke cabra.amq.migrate
 ```
 
 ### Herdr Terminal Panes
@@ -196,6 +199,17 @@ 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"
 
+# Attachment Migration (historical CAS blob / Git pinning)
+herdr-amq migrate [--dry-run] [--verbose]
+
+# Fleet Discovery & Cold Start (unions .opencode, .agents, .pi, AGENTS.md)
+herdr-amq fleet status
+herdr-amq fleet prepopulate
+herdr-amq fleet up [--kind agy|opencode|pi] [--agents a,b,c] [--dry-run]
+
+# Instant One-Shot Swarm Cold-Start (prepopulate + launch + daemon + doorbell)
+herdr-amq bootstrap [--kind agy]
+
 # Print or install the agentic skill
 herdr-amq --skill
 herdr-amq --skill --install .opencode/skills/herdr-amq
@@ -203,6 +217,33 @@ herdr-amq --skill --install .opencode/skills/herdr-amq
 
 ---
 
+## Onboarding & Swarm Cold Start
+
+When onboarding a new repository or recovering after all Herdr panes were lost (e.g. machine reboot or closed panes):
+
+### 1. Instant Automated Bootstrap
+Run a single command to discover external tool personas, provision isolated worktrees, and launch interactive agent sessions:
+
+```bash
+herdr-amq bootstrap [--kind agy|opencode|pi]
+```
+
+Under the hood, this pipeline automatically:
+1. **Unifies Personas**: Scans `.opencode/agents/`, `.agents/`, `.pi/agents/`, `.claude/agents/`, rule declarations in `AGENTS.md` (e.g. `Handles: coordinator, ...`), and established `.worktrees/`.
+2. **Prepopulates Storage & Worktrees**: Generates clean Maildir queues (`.agent-mail/agents/<handle>/`) and dedicated Git worktrees (`.worktrees/<handle>`) on `agent/<handle>`.
+3. **Pre-authorizes Workspace Trust**: Injects worktree paths into `trustedWorkspaces` in `~/.gemini/antigravity-cli/settings.json` so `agy` bypasses interactive TUI trust confirmation dialogs.
+4. **Environment Sanitation**: Seeds child PTYs with robust PATH resolution (`~/.local/bin`, Nix profiles) so agent CLIs and local binaries are found unconditionally.
+5. **Supervised Lifecycle**: Launches Herdr terminal tabs with shell-boot backoff, starts the Doorbell Bridge daemon, and executes an initial doorbell pass.
+
+### 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}/`.
+* **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.
+
+---
+
 ## Agentic Skill Integration
 
 AI coding agents (Antigravity, Claude Code, OpenCode, Aider) can consume the skill definition directly to learn the protocol without human instruction:

package/bin/herdr-amq.mjs

@@ -9,6 +9,9 @@ import {
   handleTaskCommand,
   handleMailCommand,
   handleSkillCommand,
+  handleMigrateCommand,
+  handleFleetCommand,
+  handleBootstrapCommand,
 } from "../src/actions.mjs";
 import { startDaemonLoop } from "../src/bridge.mjs";
 import { launchDashboardPane, launchInboxPeekPane } from "../src/panes.mjs";
@@ -67,8 +70,18 @@ switch (cmd) {
   case "skill":
     handleSkillCommand(process.argv.slice(3));
     break;
+  case "migrate":
+    handleMigrateCommand(process.argv.slice(3));
+    break;
+  case "fleet":
+    await handleFleetCommand(process.argv[3], process.argv.slice(4));
+    break;
+  case "bootstrap":
+  case "cold-start":
+    await handleBootstrapCommand(process.argv.slice(3));
+    break;
   default:
     console.error(`Unknown command: ${cmd}`);
-    console.log("Available commands: status, start, stop, doorbell, startup, pane-dashboard, pane-inbox, task, mail, send, reply, drain, --skill");
+    console.log("Available commands: status, start, stop, doorbell, startup, pane-dashboard, pane-inbox, task, mail, send, reply, drain, migrate, fleet, bootstrap, --skill");
     process.exit(1);
 }

package/herdr-plugin.toml

@@ -1,6 +1,6 @@
 id = "cabra.amq"
 name = "Herdr AMQ"
-version = "0.1.5"
+version = "0.1.7"
 min_herdr_version = "0.7.0"
 description = "Agent Message Queue (AMQ) bridge daemon, mailbox monitor, and dashboard for Herdr"
 platforms = ["linux", "macos"]
@@ -32,6 +32,30 @@ title = "Check AMQ Unread Mail and Ring Doorbells"
 contexts = ["workspace"]
 command = ["node", "bin/herdr-amq.mjs", "doorbell"]
 
+[[actions]]
+id = "migrate"
+title = "Migrate AMQ Attachments to CAS/Git"
+contexts = ["workspace"]
+command = ["node", "bin/herdr-amq.mjs", "migrate"]
+
+[[actions]]
+id = "fleet-status"
+title = "Fleet Status & Discovered Personas"
+contexts = ["workspace"]
+command = ["node", "bin/herdr-amq.mjs", "fleet", "status"]
+
+[[actions]]
+id = "fleet-up"
+title = "Launch Agent Fleet into Herdr"
+contexts = ["workspace"]
+command = ["node", "bin/herdr-amq.mjs", "fleet", "up"]
+
+[[actions]]
+id = "bootstrap"
+title = "Cold Start & Bootstrap Swarm"
+contexts = ["workspace"]
+command = ["node", "bin/herdr-amq.mjs", "bootstrap"]
+
 [[actions]]
 id = "open-dashboard"
 title = "Open AGmail Webmail Dashboard"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "herdr-plugin-amq",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "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

@@ -59,6 +59,18 @@ Operates against decentralized card files in `.opencode/bus/{backlog,doing,block
 | `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 |
 
+### Fleet Management & Cold-Start (`herdr-amq fleet` / `bootstrap`)
+
+Unifies external tool agent briefs (`.opencode/agents`, `.agents`, `.pi/agents`, `.claude/agents`, `AGENTS.md`) and automates swarm provisioning:
+
+| 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 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 |
+
 ### Bridge, Dashboard & Status
 
 | Command | Usage | Description |

package/src/actions.mjs

@@ -26,6 +26,13 @@ import {
   replyMaildirMessage,
   drainMaildir,
 } from "./protocol.mjs";
+import { migrateMessageAttachments } from "./migration.mjs";
+import {
+  discoverFleetPersonas,
+  prepopulateFleet,
+  launchFleet,
+} from "./fleet.mjs";
+import { getHerdrAgents } from "./herdr.mjs";
 
 export function handleStatus() {
   const amqRoot = findAmqRoot();
@@ -570,4 +577,186 @@ export function handleSkillCommand(args = []) {
   process.stdout.write(content + (content.endsWith("\n") ? "" : "\n"));
 }
 
+export function handleMigrateCommand(args = []) {
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log(`
+📦 AMQ Attachment Migration
+──────────────────────────────────────────────
+Usage: herdr-amq migrate [options]
+
+Scan messages across all agent mailboxes and migrate legacy attachments into
+immutable Content-Addressed Storage (CAS) blobs or pinned Git commits.
+
+Options:
+  --dry-run      Preview changes without modifying message files
+  --verbose, -v  Log individual errors or details during processing
+  --help, -h     Show this help message
+`);
+    return;
+  }
+
+  const amqRoot = findAmqRoot();
+  if (!amqRoot) {
+    console.error("❌ No active .agent-mail directory found.");
+    process.exit(1);
+  }
+
+  const dryRun = args.includes("--dry-run");
+  const verbose = args.includes("--verbose") || args.includes("-v");
+
+  console.log("\n📦 \x1b[1mAMQ Attachment Migration\x1b[0m");
+  console.log("──────────────────────────────────────────────");
+  console.log(`AMQ Root: \x1b[36m${amqRoot}\x1b[0m`);
+  console.log(`Mode:     ${dryRun ? "\x1b[33mDry Run (no changes written)\x1b[0m" : "\x1b[32mActive (in-place frontmatter migration)\x1b[0m"}`);
+  console.log("──────────────────────────────────────────────\n");
+  console.log("🔍 Scanning messages across all agent mailboxes...");
+
+  const startTime = Date.now();
+  const stats = migrateMessageAttachments(amqRoot, {
+    dryRun,
+    verbose,
+    onProgress: (p) => {
+      process.stdout.write(`\rProgress: ${p.current}/${p.totalScanned} messages processed...`);
+    },
+  });
+
+  const durationSec = ((Date.now() - startTime) / 1000).toFixed(1);
+  process.stdout.write("\r" + " ".repeat(60) + "\r");
+
+  console.log("✨ \x1b[1mMigration Summary:\x1b[0m");
+  console.log(`   Total messages scanned:    ${stats.totalScanned.toLocaleString()}`);
+  console.log(`   Already migrated:          ${stats.alreadyMigrated.toLocaleString()}`);
+  console.log(`   Messages updated:          \x1b[32m${stats.migrated.toLocaleString()}\x1b[0m`);
+  console.log(`   Git objects pinned:        \x1b[36m${stats.gitPinned.toLocaleString()}\x1b[0m`);
+  console.log(`   CAS blobs stored:          \x1b[35m${stats.blobsStored.toLocaleString()}\x1b[0m`);
+  if (stats.errors > 0) {
+    console.log(`   Errors encountered:        \x1b[31m${stats.errors}\x1b[0m`);
+  }
+  console.log(`   Duration:                  ${durationSec}s`);
+  console.log("\n✅ All messages are now self-contained with frozen/pinned attachments.\n");
+  return stats;
+}
+
+export async function handleFleetCommand(subcommand = "status", rawArgs = []) {
+  const amqRoot = findAmqRoot();
+  if (!amqRoot) {
+    console.error("❌ No active .agent-mail directory found.");
+    process.exit(1);
+  }
+  const repoRoot = path.resolve(path.dirname(amqRoot));
+
+  if (subcommand === "help" || subcommand === "--help" || subcommand === "-h") {
+    console.log(`
+🚀 Herdr AMQ Fleet Management
+──────────────────────────────────────────────
+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
+
+Options:
+  --kind <kind>    Agent kind to launch (default: agy, options: agy, opencode, pi)
+  --agents <list>  Comma-separated handles to target (default: all)
+  --dry-run        Preview actions without creating tabs or starting agents
+  --help, -h       Show this help message
+`);
+    return;
+  }
+
+  if (subcommand === "status" || subcommand === "list") {
+    const personas = discoverFleetPersonas(repoRoot);
+    const herdrAgents = await getHerdrAgents();
+    const liveMap = new Map(herdrAgents.map((a) => [a.name, a]));
+
+    console.log(`\n🚀 \x1b[1mFleet Status & Personas (${personas.size} discovered)\x1b[0m`);
+    console.log("────────────────────────────────────────────────────────────────────────────");
+    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[90m○ offline\x1b[0m`;
+      const wtExists = fs.existsSync(path.join(repoRoot, ".worktrees", handle));
+      const wtBadge = wtExists ? "worktree: ok" : "\x1b[33mno worktree\x1b[0m";
+      console.log(` • \x1b[1m${handle.padEnd(16)}\x1b[0m [${p.sourceType}] ${liveBadge.padEnd(30)} ${wtBadge}`);
+      if (p.role) console.log(`   \x1b[90m↳ ${p.role.slice(0, 70)}\x1b[0m`);
+    }
+    console.log("────────────────────────────────────────────────────────────────────────────\n");
+    return;
+  }
+
+  if (subcommand === "prepopulate") {
+    console.log("\n📦 Prepopulating fleet personas and worktrees...");
+    const results = prepopulateFleet(amqRoot, repoRoot);
+    for (const r of results) {
+      console.log(` • \x1b[1m${r.handle.padEnd(16)}\x1b[0m maildir: ${r.maildirOk ? "✓" : "✗"}  worktree: ${r.worktreeExisted ? "exists" : "created"}`);
+    }
+    console.log(`\n✅ Prepopulated ${results.length} fleet agents.\n`);
+    return;
+  }
+
+  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");
+
+    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 });
+    if (res.alreadyRunning.length > 0) {
+      console.log(`\x1b[36m● Already running (${res.alreadyRunning.length}):\x1b[0m ${res.alreadyRunning.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.launched.length > 0) {
+      console.log(`\x1b[32m✔ Launched agents (${res.launched.length}):\x1b[0m`);
+      for (const l of res.launched) {
+        console.log(`   • ${l.handle} -> pane ${l.paneId} (${l.kind})`);
+      }
+    }
+    if (res.failed.length > 0) {
+      console.log(`\x1b[31m✖ Failed to launch:\x1b[0m`);
+      for (const f of res.failed) {
+        console.log(`   • ${f.handle}: ${f.error}`);
+      }
+    }
+    console.log("\n✅ Fleet launch pass complete.\n");
+    return res;
+  }
+
+  console.error(`Unknown fleet command: ${subcommand}`);
+  console.log("Run 'herdr-amq fleet --help' for usage.");
+}
+
+export async function handleBootstrapCommand(args = []) {
+  const amqRoot = findAmqRoot();
+  if (!amqRoot) {
+    console.error("❌ No active .agent-mail directory found.");
+    process.exit(1);
+  }
+  const repoRoot = path.resolve(path.dirname(amqRoot));
+
+  console.log("\n🌟 \x1b[1mCold Start / Bootstrap Swarm\x1b[0m");
+  console.log("──────────────────────────────────────────────");
+  console.log("1. Prepopulating agent personas, maildirs & worktrees...");
+  prepopulateFleet(amqRoot, repoRoot);
+
+  console.log("2. Launching fleet into Herdr panes...");
+  await handleFleetCommand("up", args);
+
+  console.log("3. Ensuring AMQ Doorbell Bridge daemon is active...");
+  handleStart();
+
+  console.log("4. Performing initial doorbell sweep...");
+  handleDoorbell();
+
+  console.log("\n🚀 \x1b[32mSwarm is live and operational!\x1b[0m\n");
+}
+
 

package/src/blobs.mjs

@@ -242,6 +242,8 @@ export function pinGitRef(repoRoot, relativePath, commit = "HEAD") {
         }).trim();
         headCommitCache.set(repoRoot, { sha: commitSha, at: now });
       }
+    } else if (/^[a-f0-9]{40}$/i.test(commit)) {
+      commitSha = commit;
     } else {
       commitSha = execFileSync("git", ["rev-parse", commit], {
         cwd: repoRoot,

package/src/bridge.mjs

@@ -120,7 +120,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;
   }

package/src/fleet.mjs

@@ -0,0 +1,319 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { execFileSync, execSync } from "node:child_process";
+import { scanAgentBriefs } from "./briefs.mjs";
+import { ensureAgentWorktree } from "./worktrees.mjs";
+import { registerAgent, formatAgentTitle } from "./store.mjs";
+import { getHerdrAgents, isHerdrAvailable } from "./herdr.mjs";
+
+/**
+ * Parse agent handles from AGENTS.md, GEMINI.md, or CLAUDE.md
+ */
+export function parseAgentsMdHandles(repoRoot) {
+  if (!repoRoot || !fs.existsSync(repoRoot)) return [];
+  const candidateFiles = ["AGENTS.md", "GEMINI.md", "CLAUDE.md"];
+  const handles = new Set();
+
+  for (const f of candidateFiles) {
+    const fullPath = path.join(repoRoot, f);
+    if (!fs.existsSync(fullPath)) continue;
+
+    try {
+      const content = fs.readFileSync(fullPath, "utf8");
+      // Pattern 1: Handles: `coord`, `worker`, ...
+      const handleMatch = content.match(/Handles:\s*([^\n\r]+)/i);
+      if (handleMatch) {
+        const tokens = handleMatch[1].match(/`([^`]+)`/g) || handleMatch[1].split(/[\s,]+/);
+        for (let tok of tokens) {
+          tok = tok.replace(/[`'",:]/g, "").trim().toLowerCase();
+          if (tok && !["and", "or", "etc", "none"].includes(tok)) {
+            handles.add(tok);
+          }
+        }
+      }
+    } catch {}
+  }
+
+  return Array.from(handles);
+}
+
+/**
+ * Discover fleet personas across external tool directories (.opencode, .agents, .pi, .claude, AGENTS.md, .worktrees)
+ */
+export function discoverFleetPersonas(repoRoot) {
+  const personas = new Map();
+  if (!repoRoot || !fs.existsSync(repoRoot)) return personas;
+
+  // 1. Scan standard briefs (.opencode/agents, .agents, .pi/agents, etc.)
+  const briefs = scanAgentBriefs(repoRoot);
+  for (const [handle, brief] of briefs.entries()) {
+    personas.set(handle, {
+      ...brief,
+      sourceType: "brief",
+    });
+  }
+
+  // 2. Parse handles declared in AGENTS.md
+  const declaredHandles = parseAgentsMdHandles(repoRoot);
+  for (const handle of declaredHandles) {
+    if (!personas.has(handle)) {
+      personas.set(handle, {
+        handle,
+        name: formatAgentTitle(handle),
+        role: `Declared agent for ${handle}`,
+        description: `Agent defined in AGENTS.md`,
+        prompt: `You are the ${handle} agent.`,
+        source: "AGENTS.md",
+        sourceType: "rule",
+        model: null,
+      });
+    }
+  }
+
+  // 3. Discover established worktrees (.worktrees/<handle>)
+  const worktreeDir = path.join(repoRoot, ".worktrees");
+  if (fs.existsSync(worktreeDir)) {
+    try {
+      const entries = fs.readdirSync(worktreeDir, { withFileTypes: true });
+      for (const ent of entries) {
+        if (!ent.isDirectory() || ent.name.startsWith(".")) continue;
+        const handle = ent.name;
+        if (!personas.has(handle)) {
+          personas.set(handle, {
+            handle,
+            name: formatAgentTitle(handle),
+            role: `Specialist agent for ${handle}`,
+            description: `Established worktree agent`,
+            prompt: `You are the ${handle} agent.`,
+            source: path.join(".worktrees", handle),
+            sourceType: "worktree",
+            model: null,
+          });
+        }
+      }
+    } catch {}
+  }
+
+  return personas;
+}
+
+/**
+ * Prepopulate all fleet agents into AMQ maildirs and ensure isolated Git worktrees exist
+ */
+export function prepopulateFleet(amqRoot, repoRoot) {
+  const personas = discoverFleetPersonas(repoRoot);
+  const results = [];
+
+  for (const [handle, persona] of personas.entries()) {
+    const worktreeResult = ensureAgentWorktree(repoRoot, handle);
+    const regResult = registerAgent(amqRoot, {
+      handle,
+      name: persona.name,
+      role: persona.role || persona.description,
+      description: persona.description,
+      prompt: persona.prompt,
+      model: persona.model || "Gemini 3.8 Flash (High)",
+      worktree: worktreeResult.ok ? worktreeResult.path : undefined,
+    });
+
+    results.push({
+      handle,
+      name: persona.name,
+      source: persona.source,
+      sourceType: persona.sourceType,
+      worktree: worktreeResult.path,
+      worktreeExisted: worktreeResult.existed || false,
+      maildirOk: regResult.ok,
+    });
+  }
+
+  trustFleetWorkspaces(repoRoot);
+  return results;
+}
+
+/**
+ * Pre-authorize worktree directories in Antigravity CLI's settings.json
+ * to bypass the interactive TUI trust dialog
+ */
+export function trustFleetWorkspaces(repoRoot) {
+  try {
+    const home = os.homedir();
+    const settingsPath = path.join(home, ".gemini", "antigravity-cli", "settings.json");
+    if (!fs.existsSync(settingsPath)) return;
+    const settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+    const set = new Set(settings.trustedWorkspaces || []);
+    set.add(repoRoot);
+    const wtDir = path.join(repoRoot, ".worktrees");
+    if (fs.existsSync(wtDir)) {
+      for (const f of fs.readdirSync(wtDir)) {
+        set.add(path.join(wtDir, f));
+      }
+    }
+    settings.trustedWorkspaces = Array.from(set);
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+  } catch {}
+}
+
+/**
+ * Resolve a robust PATH that guarantees local binaries (~/.local/bin, ~/.gemini/antigravity-cli/bin, nix profiles)
+ */
+export function buildFleetEnvPath() {
+  const home = os.homedir();
+  const userName = os.userInfo().username;
+  const paths = [
+    path.join(home, ".local", "bin"),
+    path.join(home, ".gemini", "antigravity-cli", "bin"),
+    path.join(home, ".nix-profile", "bin"),
+    path.join(home, ".cargo", "bin"),
+    "/run/wrappers/bin",
+    `/etc/profiles/per-user/${userName}/bin`,
+    "/nix/profile/bin",
+    "/run/current-system/sw/bin",
+    process.env.PATH || "",
+  ];
+
+  return Array.from(new Set(paths.filter(Boolean))).join(":");
+}
+
+/**
+ * Launch or recover the agent fleet inside Herdr
+ */
+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 result = {
+    total: targetFleet.length,
+    prepopulated: targetFleet.map((t) => t.handle),
+    alreadyRunning: [],
+    wouldLaunch: [],
+    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
+  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 {
+      // 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);
+      }
+
+      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}`);
+      }
+
+      // 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);
+      }
+
+      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;
+        }
+      }
+
+      if (!started) {
+        result.failed.push({ handle, error: lastErr?.message || "Failed to start agent" });
+      }
+    } catch (err) {
+      result.failed.push({ handle, error: err.message });
+    }
+  }
+
+  return result;
+}

package/src/index.mjs

@@ -2,3 +2,8 @@ export * from "./config.mjs";
 export * from "./bridge.mjs";
 export * from "./actions.mjs";
 export * from "./panes.mjs";
+export * from "./blobs.mjs";
+export * from "./migration.mjs";
+export * from "./briefs.mjs";
+export * from "./worktrees.mjs";
+export * from "./fleet.mjs";

package/src/migration.mjs

@@ -0,0 +1,154 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parseMessage, serializeMessage } from "./protocol.mjs";
+import { ingestAttachment } from "./blobs.mjs";
+
+/**
+ * Scan all messages across agent mailboxes in amqRoot and migrate attachments once.
+ * - Resolves ephemeral files (/tmp/...) into immutable CAS blobs.
+ * - Pins deleted or historical repository assets to their git commits.
+ * - Writes pinned/frozen attachments directly into the message frontmatter.
+ * - Once migrated, parseMessageFile reads attachments in 0ms without git execution.
+ */
+export function migrateMessageAttachments(amqRoot, { dryRun = false, verbose = false, onProgress = null } = {}) {
+  if (!amqRoot) throw new Error("amqRoot is required");
+  const repoRoot = path.resolve(path.dirname(amqRoot));
+
+  const stats = {
+    totalScanned: 0,
+    alreadyMigrated: 0,
+    migrated: 0,
+    blobsStored: 0,
+    gitPinned: 0,
+    errors: 0,
+  };
+
+  const agentsDir = path.join(amqRoot, "agents");
+  if (!fs.existsSync(agentsDir)) {
+    return stats;
+  }
+
+  // Find all message files across inbox/new, inbox/cur, and outbox/sent
+  const messageFiles = [];
+  const agentEntries = fs.readdirSync(agentsDir, { withFileTypes: true });
+  for (const agentEnt of agentEntries) {
+    if (!agentEnt.isDirectory()) continue;
+    const agentDir = path.join(agentsDir, agentEnt.name);
+    const subdirs = [
+      path.join(agentDir, "inbox", "new"),
+      path.join(agentDir, "inbox", "cur"),
+      path.join(agentDir, "outbox", "sent"),
+    ];
+
+    for (const subdir of subdirs) {
+      if (!fs.existsSync(subdir)) continue;
+      const files = fs.readdirSync(subdir);
+      for (const f of files) {
+        if (f.endsWith(".md")) {
+          messageFiles.push(path.join(subdir, f));
+        }
+      }
+    }
+  }
+
+  stats.totalScanned = messageFiles.length;
+
+  const candidateRegex = /(?:(?:(?:\/|\.\/|[a-zA-Z0-9_.-]+\/)[a-zA-Z0-9_./-]+\.(?:png|jpg|jpeg|gif|webp|svg|bmp|log|txt|csv|json|diff|patch|out))|(?:\b[a-zA-Z0-9_.-]+\.(?:png|jpg|jpeg|gif|webp|svg|bmp|log|diff|patch|out)\b))/gi;
+
+  for (let i = 0; i < messageFiles.length; i++) {
+    const filePath = messageFiles[i];
+    try {
+      const raw = fs.readFileSync(filePath, "utf8");
+      const { header, body } = parseMessage(raw);
+
+      if (!header || typeof header !== "object") {
+        continue;
+      }
+
+      // Check if already migrated
+      const existingAttachments = header.attachments;
+      const isAlreadyMigrated =
+        Array.isArray(existingAttachments) &&
+        existingAttachments.length > 0 &&
+        existingAttachments.every(
+          (a) => typeof a === "object" && a !== null && (a.type === "blob" || a.type === "git" || a.exists !== undefined)
+        );
+
+      if (isAlreadyMigrated) {
+        stats.alreadyMigrated++;
+        if (onProgress && i % 100 === 0) onProgress({ ...stats, current: i + 1 });
+        continue;
+      }
+
+      // Collect candidates: existing raw attachments + body regex matches
+      const seen = new Set();
+      const candidates = [];
+
+      function addCand(ref) {
+        if (!ref) return;
+        let clean = typeof ref === "string" ? ref.trim().replace(/^["'<(\[]+|[>"')\],;:]+$/g, "") : "";
+        if (typeof ref === "object") clean = ref.path || ref.sha256 || ref.name || "";
+        if (!clean || seen.has(clean) || clean.startsWith("http://") || clean.startsWith("https://")) return;
+        seen.add(clean);
+        const base = path.basename(clean);
+        if (["config.json", "package.json", "pyproject.toml", "Cargo.toml", "flake.lock"].includes(base)) return;
+        candidates.push(ref);
+      }
+
+      if (Array.isArray(existingAttachments)) {
+        for (const a of existingAttachments) addCand(a);
+      }
+
+      const matches = body.match(candidateRegex) || [];
+      for (const m of matches) addCand(m);
+
+      if (candidates.length === 0) {
+        if (onProgress && i % 100 === 0) onProgress({ ...stats, current: i + 1 });
+        continue;
+      }
+
+      // Ingest each candidate
+      const resolved = [];
+      for (const cand of candidates) {
+        try {
+          const ing = ingestAttachment(cand, amqRoot, repoRoot, {
+            timestamp: header.created || null,
+            text: body,
+          });
+          if (ing && ing.exists) {
+            resolved.push(ing);
+            if (ing.type === "blob") stats.blobsStored++;
+            if (ing.type === "git") stats.gitPinned++;
+          }
+        } catch {}
+      }
+
+      if (resolved.length > 0) {
+        header.attachments = resolved;
+        const serialized = serializeMessage({
+          ...header,
+          body,
+        });
+
+        if (!dryRun) {
+          const tmp = `${filePath}.mig.${Date.now()}`;
+          fs.writeFileSync(tmp, serialized, "utf8");
+          fs.renameSync(tmp, filePath);
+        }
+
+        stats.migrated++;
+      }
+
+      if (onProgress && (i % 50 === 0 || i === messageFiles.length - 1)) {
+        onProgress({ ...stats, current: i + 1 });
+      }
+    } catch (err) {
+      stats.errors++;
+      if (verbose) {
+        console.error(`Error migrating ${filePath}:`, err.message);
+      }
+    }
+  }
+
+  return stats;
+}

package/src/store.mjs

@@ -164,6 +164,20 @@ export function resolveAttachmentPath(ref, amqRoot) {
  * verifying presence on disk and providing existence flags.
  */
 export function extractAttachments(body = "", metaAttachments = [], amqRoot = null, meta = {}) {
+  // If attachments are already structured and resolved (e.g. via migration or sendMaildirMessage), return directly
+  if (Array.isArray(metaAttachments) && metaAttachments.length > 0) {
+    const isStructured = metaAttachments.every(
+      (a) => typeof a === "object" && a !== null && (a.type === "blob" || a.type === "git" || a.exists !== undefined)
+    );
+    if (isStructured) {
+      return metaAttachments.map((a) => ({
+        ...a,
+        originalRef: a.originalRef || a.path || a.name,
+        sizeDisplay: a.sizeDisplay || (a.exists ? formatFileSize(a.sizeBytes || 0) : "Missing on disk"),
+      }));
+    }
+  }
+
   const attachments = [];
   const seen = new Set();
   const repoRoot = getRepoRootFromAmq(amqRoot);
@@ -171,7 +185,11 @@ export function extractAttachments(body = "", metaAttachments = [], amqRoot = nu
   function addCandidate(rawRef) {
     if (!rawRef) return;
     let clean = typeof rawRef === "string" ? rawRef.trim().replace(/^["'<(\[]+|[>"')\],;:]+$/g, "") : "";
-    if (typeof rawRef === "object") {
+    if (typeof rawRef === "object" && rawRef !== null) {
+      if (rawRef.type === "git" || rawRef.type === "blob") {
+        attachments.push(rawRef);
+        return;
+      }
       clean = rawRef.path || rawRef.sha256 || rawRef.name || "";
     }
     if (!clean || seen.has(clean) || clean.startsWith("http://") || clean.startsWith("https://")) {
@@ -184,49 +202,69 @@ export function extractAttachments(body = "", metaAttachments = [], amqRoot = nu
       return;
     }
 
-    // 1. Try hybrid CAS ingestion / Git pinning (Option A + B) with timestamp
-    if (amqRoot) {
-      try {
-        const ingested = ingestAttachment(rawRef, amqRoot, repoRoot, {
-          timestamp: meta?.created || null,
-          text: body,
-        });
-        if (ingested && ingested.exists) {
-          attachments.push({
-            ...ingested,
-            originalRef: typeof rawRef === "string" ? clean : (rawRef.name || clean),
-            sizeDisplay: formatFileSize(ingested.sizeBytes || 0),
-          });
-          return;
-        }
-      } catch {}
-    }
-
-    // 2. Fallback to disk resolution
     const ext = path.extname(clean).toLowerCase();
     const isImage = [".png", ".jpg", ".jpeg", ".gif", ".webp", ".svg", ".bmp"].includes(ext);
     const isLog = [".log", ".txt", ".csv", ".json", ".out", ".diff", ".patch"].includes(ext);
 
+    // 1. Check disk resolution first (sub-millisecond)
     const resolved = resolveAttachmentPath(clean, amqRoot);
-    const exists = Boolean(resolved);
-    let sizeBytes = 0;
-    if (exists) {
+    if (resolved) {
+      let sizeBytes = 0;
       try {
         sizeBytes = fs.statSync(resolved).size;
       } catch {}
+
+      attachments.push({
+        path: resolved,
+        originalRef: clean,
+        name: base,
+        ext,
+        isImage,
+        isLog,
+        exists: true,
+        sizeBytes,
+        sizeDisplay: formatFileSize(sizeBytes),
+        url: `/api/file?path=${encodeURIComponent(resolved)}`,
+      });
+      return;
+    }
+
+    // 2. Check CAS Blobstore if hash
+    if (amqRoot) {
+      const hashMatch = clean.match(/^(?:blob:)?([a-f0-9]{64})$/i);
+      if (hashMatch) {
+        const stored = getBlob(hashMatch[1], amqRoot);
+        if (stored) {
+          attachments.push({
+            type: "blob",
+            sha256: stored.sha256,
+            name: stored.name,
+            ext: stored.ext,
+            mime: stored.mime,
+            sizeBytes: stored.sizeBytes,
+            isImage,
+            isLog,
+            exists: true,
+            sizeDisplay: formatFileSize(stored.sizeBytes),
+            url: `/api/blob/${stored.sha256}${stored.ext ? `?ext=${encodeURIComponent(stored.ext)}` : ""}`,
+          });
+          return;
+        }
+      }
     }
 
+    // 3. Fallback: missing on disk (unmigrated legacy reference)
     attachments.push({
-      path: resolved || clean,
+      path: clean,
       originalRef: clean,
       name: base,
       ext,
       isImage,
       isLog,
-      exists,
-      sizeBytes,
-      sizeDisplay: exists ? formatFileSize(sizeBytes) : "Missing on disk",
-      url: exists ? `/api/file?path=${encodeURIComponent(resolved || clean)}` : null,
+      exists: false,
+      sizeBytes: 0,
+      sizeDisplay: "Missing on disk",
+      url: null,
     });
   }
 
@@ -236,8 +274,8 @@ export function extractAttachments(body = "", metaAttachments = [], amqRoot = nu
     }
   }
 
-  // Auto-scan body for referenced files (/tmp/..., paths with slashes, or image/log basenames)
-  const regex = /(?:(?:(?:\/|\.\/|[a-zA-Z0-9_.-]+\/)[a-zA-Z0-9_./-]+\.(?:png|jpg|jpeg|gif|webp|svg|bmp|log|txt|csv|json|diff|patch|out|gd|tres|tscn|sh|md))|(?:\b[a-zA-Z0-9_.-]+\.(?:png|jpg|jpeg|gif|webp|svg|bmp|log|diff|patch|out)\b))/gi;
+  // Auto-scan body for referenced media/logs (strictly excludes code files like .gd/.tscn)
+  const regex = /(?:(?:(?:\/|\.\/|[a-zA-Z0-9_.-]+\/)[a-zA-Z0-9_./-]+\.(?:png|jpg|jpeg|gif|webp|svg|bmp|log|txt|csv|json|diff|patch|out))|(?:\b[a-zA-Z0-9_.-]+\.(?:png|jpg|jpeg|gif|webp|svg|bmp|log|diff|patch|out)\b))/gi;
   const matches = body.match(regex) || [];
 
   for (const m of matches) {