@ifi/oh-pi-ant-colony 0.2.3 → 0.2.7

package/extensions/ant-colony/budget-planner.ts

@@ -0,0 +1,355 @@
+/**
+ * Budget Planner — Usage-aware resource allocation for the ant colony.
+ *
+ * Integrates with the usage-tracker extension via `pi.events` to access
+ * real-time provider rate limits (Claude session/weekly %, Codex 5h/weekly %)
+ * and session cost data. Uses this information to:
+ *
+ * 1. **Allocate per-caste budgets** — scouts get less (exploration is cheap),
+ *    workers get the bulk, soldiers get a review slice.
+ * 2. **Cap concurrency** — when rate limits are low, reduce parallel ants
+ *    to avoid 429s.
+ * 3. **Set per-ant cost ceilings** — individual ants get a maxCost derived
+ *    from the remaining budget and rate limit headroom.
+ * 4. **Inject budget context into prompts** — ants know how tight the budget
+ *    is and can adjust their behavior (e.g. skip low-priority work).
+ *
+ * The planner is purely functional: it takes usage data and colony state,
+ * returns an allocation. No side effects.
+ */
+
+import type { AntCaste, ColonyMetrics, ConcurrencyConfig } from "./types.js";
+
+// ═══ Types ═══
+
+/** Rate limit window from a provider (mirrors usage-tracker's RateWindow). */
+export interface RateWindow {
+	label: string;
+	percentLeft: number;
+	resetDescription: string | null;
+}
+
+/** Rate limit snapshot from a provider (mirrors usage-tracker's ProviderRateLimits). */
+export interface ProviderRateLimits {
+	provider: string;
+	windows: RateWindow[];
+	credits: number | null;
+	probedAt: number;
+	error: string | null;
+}
+
+/** Per-model usage data from the usage-tracker (mirrors usage-tracker's ModelUsage). */
+export interface ModelUsageSnapshot {
+	model: string;
+	provider: string;
+	turns: number;
+	input: number;
+	output: number;
+	costTotal: number;
+}
+
+/** Aggregate usage data broadcast by the usage-tracker extension via pi.events. */
+export interface UsageLimitsEvent {
+	providers: Map<string, ProviderRateLimits> | Record<string, ProviderRateLimits>;
+	sessionCost: number;
+	perModel: Map<string, ModelUsageSnapshot> | Record<string, ModelUsageSnapshot>;
+}
+
+/** Budget allocation for a single caste. */
+export interface CasteBudget {
+	/** Maximum total cost this caste may spend (USD). */
+	maxCost: number;
+	/** Maximum cost per individual ant (USD). */
+	maxCostPerAnt: number;
+	/** Maximum recommended concurrent ants for this caste. */
+	maxConcurrency: number;
+	/** Maximum turns per ant (tighter budget → fewer turns). */
+	maxTurns: number;
+}
+
+/** Full budget plan for a colony run. */
+export interface BudgetPlan {
+	/** Per-caste allocations. */
+	castes: Record<AntCaste, CasteBudget>;
+	/** Recommended global max concurrency (overrides adaptive controller upper bound). */
+	recommendedMaxConcurrency: number;
+	/** Overall severity: how constrained the budget is. */
+	severity: "comfortable" | "moderate" | "tight" | "critical";
+	/** Lowest rate limit percentage across all providers/windows. */
+	lowestRateLimitPct: number;
+	/** Human-readable summary for prompt injection. */
+	summary: string;
+}
+
+// ═══ Constants ═══
+
+/** Default turn counts per caste when budget is unconstrained. */
+const DEFAULT_TURNS: Record<AntCaste, number> = {
+	scout: 8,
+	worker: 15,
+	soldier: 8,
+	drone: 1,
+};
+
+/** Budget share per caste (must sum to 1.0). */
+const BUDGET_SHARES: Record<AntCaste, number> = {
+	scout: 0.1,
+	worker: 0.7,
+	soldier: 0.2,
+	drone: 0.0, // drones are free (execSync, no LLM)
+};
+
+/** Severity thresholds based on lowest rate limit %. */
+const SEVERITY_THRESHOLDS = {
+	critical: 10,
+	tight: 25,
+	moderate: 50,
+} as const;
+
+/** Concurrency caps per severity level. */
+const CONCURRENCY_CAPS: Record<BudgetPlan["severity"], number> = {
+	critical: 1,
+	tight: 2,
+	moderate: 3,
+	comfortable: 6,
+};
+
+/** Per-ant cost caps per severity level (USD). */
+const PER_ANT_COST_CAPS: Record<BudgetPlan["severity"], number> = {
+	critical: 0.05,
+	tight: 0.15,
+	moderate: 0.3,
+	comfortable: 0.5,
+};
+
+/** Turn multipliers per severity level. */
+const TURN_MULTIPLIERS: Record<BudgetPlan["severity"], number> = {
+	critical: 0.5,
+	tight: 0.7,
+	moderate: 0.85,
+	comfortable: 1.0,
+};
+
+// ═══ Core logic ═══
+
+/**
+ * Extract the lowest remaining percentage across all provider rate limit windows.
+ * Returns 100 if no rate limit data is available (assume unconstrained).
+ */
+export function getLowestRateLimitPct(
+	providers: Map<string, ProviderRateLimits> | Record<string, ProviderRateLimits> | null | undefined,
+): number {
+	if (!providers) {
+		return 100;
+	}
+
+	const entries = providers instanceof Map ? providers.values() : Object.values(providers);
+	let lowest = 100;
+
+	for (const provider of entries) {
+		if (provider.error || provider.windows.length === 0) {
+			continue;
+		}
+		for (const window of provider.windows) {
+			if (window.percentLeft < lowest) {
+				lowest = window.percentLeft;
+			}
+		}
+	}
+
+	return lowest;
+}
+
+/**
+ * Determine budget severity from the lowest rate limit percentage
+ * and the fraction of maxCost already spent.
+ */
+export function classifySeverity(
+	lowestRateLimitPct: number,
+	costSpent: number,
+	maxCost: number | null,
+): BudgetPlan["severity"] {
+	// Rate-limit severity
+	let rateSeverity: BudgetPlan["severity"] = "comfortable";
+	if (lowestRateLimitPct < SEVERITY_THRESHOLDS.critical) {
+		rateSeverity = "critical";
+	} else if (lowestRateLimitPct < SEVERITY_THRESHOLDS.tight) {
+		rateSeverity = "tight";
+	} else if (lowestRateLimitPct < SEVERITY_THRESHOLDS.moderate) {
+		rateSeverity = "moderate";
+	}
+
+	// Cost severity (only if a budget cap is set)
+	let costSeverity: BudgetPlan["severity"] = "comfortable";
+	if (maxCost != null && maxCost > 0) {
+		const costPctUsed = (costSpent / maxCost) * 100;
+		const costPctRemaining = 100 - costPctUsed;
+		if (costPctRemaining < SEVERITY_THRESHOLDS.critical) {
+			costSeverity = "critical";
+		} else if (costPctRemaining < SEVERITY_THRESHOLDS.tight) {
+			costSeverity = "tight";
+		} else if (costPctRemaining < SEVERITY_THRESHOLDS.moderate) {
+			costSeverity = "moderate";
+		}
+	}
+
+	// Return the worse of the two
+	const order: BudgetPlan["severity"][] = ["critical", "tight", "moderate", "comfortable"];
+	const rateIdx = order.indexOf(rateSeverity);
+	const costIdx = order.indexOf(costSeverity);
+	return order[Math.min(rateIdx, costIdx)];
+}
+
+/**
+ * Build a budget summary string for injection into ant prompts.
+ */
+export function buildBudgetSummary(
+	severity: BudgetPlan["severity"],
+	lowestRateLimitPct: number,
+	costSpent: number,
+	maxCost: number | null,
+	tasksDone: number,
+	tasksTotal: number,
+): string {
+	const parts: string[] = [];
+
+	// Rate limit info
+	if (lowestRateLimitPct < 100) {
+		parts.push(`Provider rate limit: ~${lowestRateLimitPct}% remaining.`);
+	}
+
+	// Cost info
+	if (maxCost != null && maxCost > 0) {
+		const remaining = Math.max(0, maxCost - costSpent);
+		parts.push(
+			`Budget: $${costSpent.toFixed(2)} spent of $${maxCost.toFixed(2)} ($${remaining.toFixed(2)} remaining).`,
+		);
+	} else if (costSpent > 0) {
+		parts.push(`Session cost so far: $${costSpent.toFixed(2)}.`);
+	}
+
+	// Progress
+	if (tasksTotal > 0) {
+		parts.push(`Progress: ${tasksDone}/${tasksTotal} tasks completed.`);
+	}
+
+	// Severity-specific guidance
+	switch (severity) {
+		case "critical":
+			parts.push(
+				"⚠️ CRITICAL: Resources nearly exhausted. Only execute essential high-priority tasks. Skip exploration, be extremely concise, minimize tool calls.",
+			);
+			break;
+		case "tight":
+			parts.push(
+				"⚠️ Budget is tight. Be efficient — prefer targeted edits over broad exploration. Skip low-priority or nice-to-have tasks.",
+			);
+			break;
+		case "moderate":
+			parts.push("Budget is moderate. Be reasonably efficient — avoid unnecessary exploration but don't cut corners.");
+			break;
+		case "comfortable":
+			// No extra guidance needed
+			break;
+	}
+
+	return parts.join(" ");
+}
+
+/**
+ * Plan the budget allocation for a colony based on current usage data.
+ *
+ * @param usageLimits - Rate limit and cost data from the usage-tracker extension (may be null if unavailable).
+ * @param metrics - Current colony metrics (cost spent, tasks done, etc.).
+ * @param maxCost - Colony-level cost cap (null = unlimited).
+ * @param concurrency - Current concurrency config for max bounds.
+ * @returns A complete budget plan with per-caste allocations.
+ */
+export function planBudget(
+	usageLimits: UsageLimitsEvent | null,
+	metrics: ColonyMetrics,
+	maxCost: number | null,
+	concurrency: ConcurrencyConfig,
+): BudgetPlan {
+	const lowestRateLimitPct = getLowestRateLimitPct(usageLimits?.providers ?? null);
+	const costSpent = metrics.totalCost;
+	const severity = classifySeverity(lowestRateLimitPct, costSpent, maxCost);
+
+	// Remaining budget for allocation
+	const remainingBudget = maxCost != null ? Math.max(0, maxCost - costSpent) : Number.POSITIVE_INFINITY;
+
+	// Recommended max concurrency (min of severity cap and hardware cap)
+	const recommendedMaxConcurrency = Math.min(CONCURRENCY_CAPS[severity], concurrency.max);
+
+	// Per-caste allocation
+	const castes = {} as Record<AntCaste, CasteBudget>;
+
+	for (const caste of ["scout", "worker", "soldier", "drone"] as AntCaste[]) {
+		const share = BUDGET_SHARES[caste];
+		const casteMaxCost = Number.isFinite(remainingBudget) ? remainingBudget * share : Number.POSITIVE_INFINITY;
+
+		const baseTurns = DEFAULT_TURNS[caste];
+		const adjustedTurns = Math.max(1, Math.floor(baseTurns * TURN_MULTIPLIERS[severity]));
+
+		const maxCostPerAnt = caste === "drone" ? 0 : Math.min(PER_ANT_COST_CAPS[severity], casteMaxCost);
+
+		// Concurrency: scouts and soldiers typically need fewer slots than workers
+		let casteConcurrency: number;
+		if (caste === "drone") {
+			casteConcurrency = recommendedMaxConcurrency; // drones are free
+		} else if (caste === "scout" || caste === "soldier") {
+			casteConcurrency = Math.max(1, Math.ceil(recommendedMaxConcurrency * 0.5));
+		} else {
+			casteConcurrency = recommendedMaxConcurrency;
+		}
+
+		castes[caste] = {
+			maxCost: casteMaxCost,
+			maxCostPerAnt,
+			maxConcurrency: casteConcurrency,
+			maxTurns: adjustedTurns,
+		};
+	}
+
+	const summary = buildBudgetSummary(
+		severity,
+		lowestRateLimitPct,
+		costSpent,
+		maxCost,
+		metrics.tasksDone,
+		metrics.tasksTotal,
+	);
+
+	return {
+		castes,
+		recommendedMaxConcurrency,
+		severity,
+		lowestRateLimitPct,
+		summary,
+	};
+}
+
+/**
+ * Apply a budget plan's concurrency constraints to the adaptive concurrency config.
+ * Returns a new config with `max` capped by the budget plan.
+ */
+export function applyConcurrencyCap(config: ConcurrencyConfig, plan: BudgetPlan): ConcurrencyConfig {
+	const cappedMax = Math.min(config.max, plan.recommendedMaxConcurrency);
+	return {
+		...config,
+		max: cappedMax,
+		current: Math.min(config.current, cappedMax),
+		optimal: Math.min(config.optimal, cappedMax),
+	};
+}
+
+/**
+ * Build the budget-awareness section for ant system prompts.
+ * Returns empty string if budget is comfortable (no need to distract the ant).
+ */
+export function buildBudgetPromptSection(plan: BudgetPlan): string {
+	if (plan.severity === "comfortable") {
+		return "";
+	}
+	return `\n## ⚠️ Budget Awareness\n${plan.summary}\n`;
+}

package/extensions/ant-colony/index.ts

@@ -54,6 +54,8 @@ interface ColonyLogEntry {
 }
 
 interface BackgroundColony {
+	/** Short identifier for this colony (c1, c2, ...). */
+	id: string;
 	goal: string;
 	abortController: AbortController;
 	state: ColonyState | null;
@@ -64,8 +66,30 @@ interface BackgroundColony {
 }
 
 export default function antColonyExtension(pi: ExtensionAPI) {
-	// Currently running background colony (only one at a time)
-	let activeColony: BackgroundColony | null = null;
+	/** All running background colonies, keyed by short ID. */
+	const colonies = new Map<string, BackgroundColony>();
+	/** Auto-incrementing colony counter for generating IDs. */
+	let colonyCounter = 0;
+
+	/** Generate a short colony ID like c1, c2, ... */
+	function nextColonyId(): string {
+		colonyCounter++;
+		return `c${colonyCounter}`;
+	}
+
+	/**
+	 * Resolve a colony by ID. If no ID given and exactly one colony is running,
+	 * returns that one. Returns null if no match or ambiguous.
+	 */
+	function resolveColony(idArg?: string): BackgroundColony | null {
+		if (idArg) {
+			return colonies.get(idArg) ?? null;
+		}
+		if (colonies.size === 1) {
+			return colonies.values().next().value ?? null;
+		}
+		return null;
+	}
 
 	// Prevent main process polling from blocking: only allow explicit manual snapshots with cooldown
 	let lastBgStatusSnapshotAt = 0;
@@ -166,26 +190,30 @@ export default function antColonyExtension(pi: ExtensionAPI) {
 		}
 
 		renderHandler = () => {
-			if (!activeColony) {
+			if (colonies.size === 0) {
 				return;
 			}
-			const { state } = activeColony;
-			const elapsed = state ? formatDuration(Date.now() - state.createdAt) : "0s";
-			const m = state?.metrics;
-			const phase = state?.status || "scouting";
-			const progress = calcProgress(m);
-			const pct = `${Math.round(progress * 100)}%`;
-			const active = activeColony.antStreams.size;
-
-			const parts = [`🐜 ${statusIcon(phase)} ${statusLabel(phase)}`];
-			parts.push(m ? `${m.tasksDone}/${m.tasksTotal} (${pct})` : `0/0 (${pct})`);
-			parts.push(`⚡${active}`);
-			if (m) {
-				parts.push(formatCost(m.totalCost));
+			const statusParts: string[] = [];
+			for (const colony of colonies.values()) {
+				const { state } = colony;
+				const elapsed = state ? formatDuration(Date.now() - state.createdAt) : "0s";
+				const m = state?.metrics;
+				const phase = state?.status || "scouting";
+				const progress = calcProgress(m);
+				const pct = `${Math.round(progress * 100)}%`;
+				const active = colony.antStreams.size;
+
+				const parts = [`🐜[${colony.id}] ${statusIcon(phase)} ${statusLabel(phase)}`];
+				parts.push(m ? `${m.tasksDone}/${m.tasksTotal} (${pct})` : `0/0 (${pct})`);
+				parts.push(`⚡${active}`);
+				if (m) {
+					parts.push(formatCost(m.totalCost));
+				}
+				parts.push(elapsed);
+				statusParts.push(parts.join(" │ "));
 			}
-			parts.push(elapsed);
 
-			ctx.ui.setStatus("ant-colony", parts.join(" │ "));
+			ctx.ui.setStatus("ant-colony", statusParts.join("  ·  "));
 		};
 		clearHandler = () => {
 			ctx.ui.setStatus("ant-colony", undefined);
@@ -228,6 +256,7 @@ export default function antColonyExtension(pi: ExtensionAPI) {
 				signal: signal ?? undefined,
 				callbacks,
 				modelRegistry: params.modelRegistry,
+				eventBus: pi.events, // Usage-tracker integration for budget-aware planning
 			});
 
 			return {
@@ -255,17 +284,11 @@ export default function antColonyExtension(pi: ExtensionAPI) {
 			modelRegistry?: any;
 		},
 		resume = false,
-	) {
-		if (activeColony) {
-			pi.events.emit("ant-colony:notify", {
-				msg: "A colony is already running. Use /colony-stop first.",
-				level: "warning",
-			});
-			return;
-		}
-
+	): string {
+		const colonyId = nextColonyId();
 		const abortController = new AbortController();
 		const colony: BackgroundColony = {
+			id: colonyId,
 			goal: params.goal,
 			abortController,
 			state: null,
@@ -275,7 +298,7 @@ export default function antColonyExtension(pi: ExtensionAPI) {
 			promise: null as any, // set below
 		};
 
-		pushLog(colony, { level: "info", text: "INITIALIZING · Colony launched in background" });
+		pushLog(colony, { level: "info", text: `INITIALIZING · Colony [${colonyId}] launched in background` });
 
 		let lastPhase = "";
 
@@ -290,7 +313,7 @@ export default function antColonyExtension(pi: ExtensionAPI) {
 					pi.sendMessage(
 						{
 							customType: "ant-colony-progress",
-							content: `[COLONY_SIGNAL:${signal.phase.toUpperCase()}] 🐜 ${signal.message} (${pct}%, ${formatCost(signal.cost)})`,
+							content: `[COLONY_SIGNAL:${signal.phase.toUpperCase()}] 🐜[${colonyId}] ${signal.message} (${pct}%, ${formatCost(signal.cost)})`,
 							display: true,
 						},
 						{ triggerTurn: false, deliverAs: "followUp" },
@@ -326,7 +349,7 @@ export default function antColonyExtension(pi: ExtensionAPI) {
 				pi.sendMessage(
 					{
 						customType: "ant-colony-progress",
-						content: `[COLONY_SIGNAL:TASK_DONE] 🐜 ${icon} ${task.title.slice(0, 60)} (${progress}, ${cost})`,
+						content: `[COLONY_SIGNAL:TASK_DONE] 🐜[${colonyId}] ${icon} ${task.title.slice(0, 60)} (${progress}, ${cost})`,
 						display: true,
 					},
 					{ triggerTurn: false, deliverAs: "followUp" },
@@ -371,10 +394,11 @@ export default function antColonyExtension(pi: ExtensionAPI) {
 			callbacks,
 			authStorage: undefined,
 			modelRegistry: params.modelRegistry,
+			eventBus: pi.events, // Usage-tracker integration for budget-aware planning
 		};
 		colony.promise = resume ? resumeColony(colonyOpts) : runColony(colonyOpts);
 
-		activeColony = colony;
+		colonies.set(colonyId, colony);
 		lastBgStatusSnapshotAt = 0;
 		throttledRender();
 
@@ -389,39 +413,44 @@ export default function antColonyExtension(pi: ExtensionAPI) {
 					text: `${ok ? "COMPLETE" : "FAILED"} · ${m.tasksDone}/${m.tasksTotal} · ${formatCost(m.totalCost)}`,
 				});
 
-				// Clear UI
-				pi.events.emit("ant-colony:clear-ui");
-				activeColony = null;
+				colonies.delete(colonyId);
+				if (colonies.size === 0) {
+					pi.events.emit("ant-colony:clear-ui");
+				}
 
 				// Inject results into conversation
 				pi.sendMessage(
 					{
 						customType: "ant-colony-report",
-						content: `[COLONY_SIGNAL:COMPLETE]\n${report}`,
+						content: `[COLONY_SIGNAL:COMPLETE] [${colonyId}]\n${report}`,
 						display: true,
 					},
 					{ triggerTurn: true, deliverAs: "followUp" },
 				);
 
 				pi.events.emit("ant-colony:notify", {
-					msg: `🐜 Colony ${ok ? "completed" : "failed"}: ${m.tasksDone}/${m.tasksTotal} tasks │ ${formatCost(m.totalCost)}`,
+					msg: `🐜[${colonyId}] Colony ${ok ? "completed" : "failed"}: ${m.tasksDone}/${m.tasksTotal} tasks │ ${formatCost(m.totalCost)}`,
 					level: ok ? "success" : "error",
 				});
 			})
 			.catch((e) => {
 				pushLog(colony, { level: "error", text: `CRASHED · ${String(e).slice(0, 120)}` });
-				pi.events.emit("ant-colony:clear-ui");
-				activeColony = null;
-				pi.events.emit("ant-colony:notify", { msg: `🐜 Colony crashed: ${e}`, level: "error" });
+				colonies.delete(colonyId);
+				if (colonies.size === 0) {
+					pi.events.emit("ant-colony:clear-ui");
+				}
+				pi.events.emit("ant-colony:notify", { msg: `🐜[${colonyId}] Colony crashed: ${e}`, level: "error" });
 				pi.sendMessage(
 					{
 						customType: "ant-colony-report",
-						content: `[COLONY_SIGNAL:FAILED]\n## 🐜 Colony Crashed\n${e}`,
+						content: `[COLONY_SIGNAL:FAILED] [${colonyId}]\n## 🐜 Colony Crashed\n${e}`,
 						display: true,
 					},
 					{ triggerTurn: true, deliverAs: "followUp" },
 				);
 			});
+
+		return colonyId;
 	}
 
 	// ═══ Custom message renderer for colony progress signals ═══
@@ -494,8 +523,8 @@ export default function antColonyExtension(pi: ExtensionAPI) {
 	pi.registerShortcut("ctrl+shift+a", {
 		description: "Show ant colony details",
 		async handler(ctx) {
-			if (!activeColony) {
-				ctx.ui.notify("No colony is currently running.", "info");
+			if (colonies.size === 0) {
+				ctx.ui.notify("No colonies are currently running.", "info");
 				return;
 			}
 
@@ -505,9 +534,18 @@ export default function antColonyExtension(pi: ExtensionAPI) {
 					let cachedLines: string[] | undefined;
 					let currentTab: "tasks" | "streams" | "log" = "tasks";
 					let taskFilter: "all" | "active" | "done" | "failed" = "all";
+					/** Which colony to display (cycles with 'n'). */
+					let selectedColonyIdx = 0;
+
+					const getSelectedColony = (): BackgroundColony | null => {
+						const ids = [...colonies.keys()];
+						if (ids.length === 0) return null;
+						const idx = selectedColonyIdx % ids.length;
+						return colonies.get(ids[idx]) ?? null;
+					};
 
 					const buildLines = (width: number): string[] => {
-						const c = activeColony;
+						const c = getSelectedColony();
 						if (!c) return [theme.fg("muted", "  No colony running.")];
 
 						const lines: string[] = [];
@@ -523,8 +561,18 @@ export default function antColonyExtension(pi: ExtensionAPI) {
 						const activeAnts = c.antStreams.size;
 						const barWidth = Math.max(10, Math.min(24, w - 28));
 
+						// Show colony selector if multiple are running
+						if (colonies.size > 1) {
+							const ids = [...colonies.keys()];
+							const idx = selectedColonyIdx % ids.length;
+							const selector = ids
+								.map((id, i) => (i === idx ? theme.fg("accent", theme.bold(`[${id}]`)) : theme.fg("muted", id)))
+								.join(" ");
+							lines.push(`  ${selector}  ${theme.fg("dim", "(n = next colony)")}`);
+						}
+
 						lines.push(
-							theme.fg("accent", theme.bold("  🐜 Colony Details")) + theme.fg("muted", ` │ ${elapsed} │ ${cost}`),
+							theme.fg("accent", theme.bold(`  🐜 Colony [${c.id}]`)) + theme.fg("muted", ` │ ${elapsed} │ ${cost}`),
 						);
 						lines.push(theme.fg("muted", `  Goal: ${trim(c.goal, w - 8)}`));
 						lines.push(
@@ -703,6 +751,7 @@ export default function antColonyExtension(pi: ExtensionAPI) {
 							else if (data.toLowerCase() === "a") taskFilter = "active";
 							else if (data.toLowerCase() === "d") taskFilter = "done";
 							else if (data.toLowerCase() === "f") taskFilter = "failed";
+							else if (data.toLowerCase() === "n") selectedColonyIdx++;
 							else return;
 
 							cachedWidth = undefined;
@@ -745,18 +794,6 @@ export default function antColonyExtension(pi: ExtensionAPI) {
 		}),
 
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-			if (activeColony) {
-				return {
-					content: [
-						{
-							type: "text",
-							text: "A colony is already running in the background. Use /colony-stop to cancel it first.",
-						},
-					],
-					isError: true,
-				};
-			}
-
 			const currentModel = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : null;
 			if (!currentModel) {
 				return {
@@ -786,13 +823,13 @@ export default function antColonyExtension(pi: ExtensionAPI) {
 			}
 
 			// Interactive mode: run in background
-			launchBackgroundColony(colonyParams);
+			const launchedId = launchBackgroundColony(colonyParams);
 
 			return {
 				content: [
 					{
 						type: "text",
-						text: `[COLONY_SIGNAL:LAUNCHED]\n🐜 Colony launched in background.\nGoal: ${params.goal}\n\nThe colony runs autonomously in passive mode. Progress is pushed via [COLONY_SIGNAL:*] follow-up messages. Do not poll bg_colony_status unless the user explicitly asks for a manual snapshot.`,
+						text: `[COLONY_SIGNAL:LAUNCHED] [${launchedId}]\n🐜 Colony [${launchedId}] launched in background (${colonies.size} active).\nGoal: ${params.goal}\n\nThe colony runs autonomously in passive mode. Progress is pushed via [COLONY_SIGNAL:*] follow-up messages. Do not poll bg_colony_status unless the user explicitly asks for a manual snapshot.`,
 					},
 				],
 			};
@@ -816,9 +853,17 @@ export default function antColonyExtension(pi: ExtensionAPI) {
 			container.addChild(
 				new Text(theme.fg("success", "✓ ") + theme.fg("toolTitle", theme.bold("Colony launched in background")), 0, 0),
 			);
-			if (activeColony) {
-				container.addChild(new Text(theme.fg("muted", `  Goal: ${activeColony.goal.slice(0, 70)}`), 0, 0));
-				container.addChild(new Text(theme.fg("muted", "  Ctrl+Shift+A for details │ /colony-stop to cancel"), 0, 0));
+			if (colonies.size > 0) {
+				for (const colony of colonies.values()) {
+					container.addChild(new Text(theme.fg("muted", `  [${colony.id}] ${colony.goal.slice(0, 65)}`), 0, 0));
+				}
+				container.addChild(
+					new Text(
+						theme.fg("muted", `  ${colonies.size} active │ Ctrl+Shift+A for details │ /colony-stop to cancel`),
+						0,
+						0,
+					),
+				);
 			}
 			return container;
 		},
@@ -826,9 +871,8 @@ export default function antColonyExtension(pi: ExtensionAPI) {
 
 	// ═══ Helper: build status summary ═══
 
-	function buildStatusText(): string {
-		if (!activeColony) return "No colony is currently running.";
-		const c = activeColony;
+	/** Build a status summary for a single colony. */
+	function buildColonyStatusText(c: BackgroundColony): string {
 		const state = c.state;
 		const elapsed = state ? formatDuration(Date.now() - state.createdAt) : "0s";
 		const m = state?.metrics;
@@ -851,15 +895,29 @@ export default function antColonyExtension(pi: ExtensionAPI) {
 		return lines.join("\n");
 	}
 
+	/** Build a status summary for all running colonies. */
+	function buildStatusText(): string {
+		if (colonies.size === 0) return "No colonies are currently running.";
+		if (colonies.size === 1) {
+			const colony = colonies.values().next().value;
+			return colony ? buildColonyStatusText(colony) : "No colonies are currently running.";
+		}
+		const parts: string[] = [`${colonies.size} colonies running:\n`];
+		for (const colony of colonies.values()) {
+			parts.push(`── [${colony.id}] ──\n${buildColonyStatusText(colony)}\n`);
+		}
+		return parts.join("\n");
+	}
+
 	// ═══ Tool: bg_colony_status ═══
 	pi.registerTool({
 		name: "bg_colony_status",
 		label: "Colony Status",
 		description:
-			"Optional manual snapshot for a running colony. Progress is pushed passively via COLONY_SIGNAL follow-up messages; call this only when the user explicitly asks.",
+			"Optional manual snapshot for running colonies. Progress is pushed passively via COLONY_SIGNAL follow-up messages; call this only when the user explicitly asks.",
 		parameters: Type.Object({}),
 		async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
-			if (!activeColony) {
+			if (colonies.size === 0) {
 				return {
 					content: [{ type: "text" as const, text: "No colony is currently running." }],
 				};
@@ -900,70 +958,171 @@ export default function antColonyExtension(pi: ExtensionAPI) {
 		},
 	});
 
+	// ═══ Command: /colony ═══
+	pi.registerCommand("colony", {
+		description: "Launch an ant colony swarm to accomplish a goal",
+		async handler(args, ctx) {
+			const goal = args.trim();
+			if (!goal) {
+				ctx.ui.notify("Usage: /colony <goal> — describe what the colony should accomplish", "warning");
+				return;
+			}
+
+			const currentModel = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : null;
+			if (!currentModel) {
+				ctx.ui.notify("Colony failed: no model available in current session.", "error");
+				return;
+			}
+
+			const id = launchBackgroundColony({
+				cwd: ctx.cwd,
+				goal,
+				currentModel,
+				modelOverrides: {},
+				modelRegistry: ctx.modelRegistry ?? undefined,
+			});
+			ctx.ui.notify(
+				`🐜[${id}] Colony launched (${colonies.size} active): ${goal.slice(0, 70)}${goal.length > 70 ? "..." : ""}`,
+				"info",
+			);
+		},
+	});
+
+	// ═══ Command: /colony-count ═══
+	pi.registerCommand("colony-count", {
+		description: "Show how many colonies are currently running",
+		async handler(_args, ctx) {
+			if (colonies.size === 0) {
+				ctx.ui.notify("No colonies running.", "info");
+			} else {
+				const ids = [...colonies.values()].map((c) => `[${c.id}] ${c.goal.slice(0, 50)}`).join("\n  ");
+				ctx.ui.notify(`${colonies.size} active ${colonies.size === 1 ? "colony" : "colonies"}:\n  ${ids}`, "info");
+			}
+		},
+	});
+
 	// ═══ Command: /colony-status ═══
 	pi.registerCommand("colony-status", {
-		description: "Show current colony progress",
-		async handler(_args, ctx) {
-			if (!activeColony) {
-				ctx.ui.notify("No colony is currently running.", "info");
+		description: "Show current colony progress (optionally specify ID: /colony-status c1)",
+		getArgumentCompletions(prefix) {
+			const items = [...colonies.keys()]
+				.filter((id) => id.startsWith(prefix))
+				.map((id) => {
+					const c = colonies.get(id);
+					return { value: id, label: `${id} — ${c?.goal.slice(0, 50) ?? ""}` };
+				});
+			return items.length > 0 ? items : null;
+		},
+		async handler(args, ctx) {
+			const idArg = args.trim() || undefined;
+			if (colonies.size === 0) {
+				ctx.ui.notify("No colonies are currently running.", "info");
 				return;
 			}
-			ctx.ui.notify(buildStatusText(), "info");
+			if (idArg) {
+				const colony = resolveColony(idArg);
+				if (!colony) {
+					ctx.ui.notify(`Colony "${idArg}" not found. Active: ${[...colonies.keys()].join(", ")}`, "warning");
+					return;
+				}
+				ctx.ui.notify(buildColonyStatusText(colony), "info");
+			} else {
+				ctx.ui.notify(buildStatusText(), "info");
+			}
 		},
 	});
 
 	// ═══ Command: /colony-stop ═══
 	pi.registerCommand("colony-stop", {
-		description: "Stop the running background colony",
-		async handler(_args, ctx) {
-			if (!activeColony) {
-				ctx.ui.notify("No colony is currently running.", "info");
+		description: "Stop a colony (specify ID, or stops all if none given)",
+		getArgumentCompletions(prefix) {
+			const items = [
+				{ value: "all", label: "all — Stop all running colonies" },
+				...[...colonies.keys()]
+					.filter((id) => id.startsWith(prefix))
+					.map((id) => {
+						const c = colonies.get(id);
+						return { value: id, label: `${id} — ${c?.goal.slice(0, 50) ?? ""}` };
+					}),
+			].filter((i) => i.value.startsWith(prefix));
+			return items.length > 0 ? items : null;
+		},
+		async handler(args, ctx) {
+			const idArg = args.trim() || undefined;
+			if (colonies.size === 0) {
+				ctx.ui.notify("No colonies are currently running.", "info");
 				return;
 			}
-			activeColony.abortController.abort();
-			ctx.ui.notify("🐜 Colony abort signal sent. Waiting for ants to finish...", "warning");
+			if (!idArg || idArg === "all") {
+				const count = colonies.size;
+				for (const colony of colonies.values()) {
+					colony.abortController.abort();
+				}
+				ctx.ui.notify(`🐜 Abort signal sent to ${count} ${count === 1 ? "colony" : "colonies"}.`, "warning");
+			} else {
+				const colony = resolveColony(idArg);
+				if (!colony) {
+					ctx.ui.notify(`Colony "${idArg}" not found. Active: ${[...colonies.keys()].join(", ")}`, "warning");
+					return;
+				}
+				colony.abortController.abort();
+				ctx.ui.notify(`🐜[${colony.id}] Abort signal sent. Waiting for ants to finish...`, "warning");
+			}
 		},
 	});
 
 	pi.registerCommand("colony-resume", {
-		description: "Resume a colony from its last checkpoint",
-		async handler(_args, ctx) {
-			if (activeColony) {
-				ctx.ui.notify("A colony is already running.", "warning");
+		description: "Resume colonies from their last checkpoint (resumes all resumable by default)",
+		async handler(args, ctx) {
+			const all = Nest.findAllResumable(ctx.cwd);
+			if (all.length === 0) {
+				ctx.ui.notify("No resumable colonies found.", "info");
 				return;
 			}
-			const found = Nest.findResumable(ctx.cwd);
-			if (!found) {
-				ctx.ui.notify("No resumable colony found.", "info");
+
+			// If an argument is given, try to match a specific colony ID
+			const target = args.trim();
+			const toResume = target ? all.filter((r) => r.colonyId === target) : [all[0]];
+
+			if (toResume.length === 0) {
+				ctx.ui.notify(`Colony "${target}" not found. Resumable: ${all.map((r) => r.colonyId).join(", ")}`, "warning");
 				return;
 			}
-			ctx.ui.notify(`🐜 Resuming colony: ${found.state.goal.slice(0, 60)}...`, "info");
-			launchBackgroundColony(
-				{
-					cwd: ctx.cwd,
-					goal: found.state.goal,
-					maxCost: found.state.maxCost ?? undefined,
-					currentModel: ctx.currentModel,
-					modelOverrides: {},
-					modelRegistry: ctx.modelRegistry,
-				},
-				true,
-			);
+
+			for (const found of toResume) {
+				const id = launchBackgroundColony(
+					{
+						cwd: ctx.cwd,
+						goal: found.state.goal,
+						maxCost: found.state.maxCost ?? undefined,
+						currentModel: ctx.currentModel,
+						modelOverrides: {},
+						modelRegistry: ctx.modelRegistry,
+					},
+					true,
+				);
+				ctx.ui.notify(`🐜[${id}] Resuming: ${found.state.goal.slice(0, 60)}...`, "info");
+			}
 		},
 	});
 
 	// ═══ Cleanup on shutdown ═══
 	pi.on("session_shutdown", async () => {
-		if (activeColony) {
-			activeColony.abortController.abort();
-			// Wait for colony to finish gracefully (max 5s)
+		if (colonies.size > 0) {
+			for (const colony of colonies.values()) {
+				colony.abortController.abort();
+			}
+			// Wait for all colonies to finish gracefully (max 5s)
 			try {
-				await Promise.race([activeColony.promise, new Promise((r) => setTimeout(r, 5000))]);
+				await Promise.race([
+					Promise.all([...colonies.values()].map((c) => c.promise)),
+					new Promise((r) => setTimeout(r, 5000)),
+				]);
 			} catch {
 				/* ignore */
 			}
 			pi.events.emit("ant-colony:clear-ui");
-			activeColony = null;
+			colonies.clear();
 		}
 	});
 }

package/extensions/ant-colony/nest.ts

@@ -494,7 +494,18 @@ export class Nest {
 	 * scouting, working, or reviewing and has no `finishedAt` timestamp).
 	 */
 	static findResumable(cwd: string): { colonyId: string; state: ColonyState } | null {
+		const all = Nest.findAllResumable(cwd);
+		return all.length > 0 ? all[0] : null;
+	}
+
+	/**
+	 * Find all resumable colonies in the working directory.
+	 * Returns colonies whose state is incomplete (not done/failed/budget_exceeded).
+	 * Sorted by `createdAt` descending so the most recent colony is first.
+	 */
+	static findAllResumable(cwd: string): Array<{ colonyId: string; state: ColonyState }> {
 		const parentDir = path.join(cwd, ".ant-colony");
+		const results: Array<{ colonyId: string; state: ColonyState }> = [];
 		try {
 			for (const dir of fs.readdirSync(parentDir)) {
 				const stateFile = path.join(parentDir, dir, "state.json");
@@ -508,13 +519,14 @@ export class Nest {
 					state.status !== "failed" &&
 					state.status !== "budget_exceeded"
 				) {
-					return { colonyId: dir, state };
+					results.push({ colonyId: dir, state });
 				}
 			}
 		} catch {
 			// No .ant-colony directory — nothing to resume
 		}
-		return null;
+		results.sort((a, b) => (b.state.createdAt ?? 0) - (a.state.createdAt ?? 0));
+		return results;
 	}
 
 	/**

package/extensions/ant-colony/prompts.ts

@@ -82,11 +82,15 @@ export function buildPrompt(
 	castePrompt: string,
 	maxTurns?: number,
 	tandem?: { parentResult?: string; priorError?: string },
+	budgetSection?: string,
 ): string {
 	let prompt = `${castePrompt}\n\n`;
 	if (maxTurns) {
 		prompt += `## ⚠️ Turn Limit\nYou have a MAXIMUM of ${maxTurns} turns. Plan accordingly — reserve your LAST turn to output the structured result format above. Do NOT waste turns on unnecessary exploration.\n\n`;
 	}
+	if (budgetSection) {
+		prompt += budgetSection;
+	}
 	if (pheromoneContext) {
 		prompt += `## Colony Pheromone Trail (intelligence from other ants)\n${pheromoneContext}\n\n`;
 	}

package/extensions/ant-colony/queen.ts

@@ -15,6 +15,13 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import type { AuthStorage, ModelRegistry } from "@mariozechner/pi-coding-agent";
+import {
+	applyConcurrencyCap,
+	type BudgetPlan,
+	buildBudgetPromptSection,
+	planBudget,
+	type UsageLimitsEvent,
+} from "./budget-planner.js";
 import { adapt, defaultConcurrency, sampleSystem } from "./concurrency.js";
 import { buildImportGraph, type ImportGraph, taskDependsOn } from "./deps.js";
 import { Nest } from "./nest.js";
@@ -44,6 +51,13 @@ export interface QueenCallbacks {
 	onComplete?(state: ColonyState): void;
 }
 
+/** Event emitter interface for inter-extension communication. */
+export interface ColonyEventBus {
+	emit(event: string, data?: unknown): void;
+	on(event: string, handler: (data: unknown) => void): void;
+	off(event: string, handler: (data: unknown) => void): void;
+}
+
 export interface QueenOptions {
 	cwd: string;
 	goal: string;
@@ -55,6 +69,8 @@ export interface QueenOptions {
 	callbacks: QueenCallbacks;
 	authStorage?: AuthStorage;
 	modelRegistry?: ModelRegistry;
+	/** Event bus for cross-extension communication (usage-tracker integration). */
+	eventBus?: ColonyEventBus;
 }
 
 function makeColonyId(): string {
@@ -305,6 +321,8 @@ interface WaveOptions {
 	authStorage?: AuthStorage;
 	modelRegistry?: ModelRegistry;
 	importGraph?: ImportGraph;
+	/** Budget plan from the usage-aware planner (may be null if no data available). */
+	budgetPlan?: BudgetPlan | null;
 }
 
 /**
@@ -341,6 +359,14 @@ async function runAntWave(opts: WaveOptions): Promise<"ok" | "budget"> {
 	const casteModel = opts.modelOverrides?.[caste] || currentModel;
 	const baseConfig = { ...DEFAULT_ANT_CONFIGS[caste], model: casteModel };
 
+	// Budget-aware turn cap: if the budget planner recommends fewer turns, use that
+	if (opts.budgetPlan) {
+		const casteBudget = opts.budgetPlan.castes[caste];
+		if (casteBudget && casteBudget.maxTurns < baseConfig.maxTurns) {
+			baseConfig.maxTurns = casteBudget.maxTurns;
+		}
+	}
+
 	let backoffMs = 0; // 429 backoff duration
 	let consecutiveRateLimits = 0; // Consecutive rate limit counter
 	const retryCount = new Map<string, number>(); // taskId → retry count
@@ -400,10 +426,22 @@ async function runAntWave(opts: WaveOptions): Promise<"ok" | "budget"> {
 			} else if (progress > 0.7) {
 				config.maxTurns = Math.max(baseConfig.maxTurns - 5, 5); // Late convergence, only cleanup/fixes
 			}
+			// Build budget-awareness prompt section for non-drone ants
+			const budgetSection = opts.budgetPlan ? buildBudgetPromptSection(opts.budgetPlan) : undefined;
 			const antPromise =
 				caste === "drone"
 					? runDrone(cwd, nest, task)
-					: spawnAnt(cwd, nest, task, config, antSignal, callbacks.onAntStream, opts.authStorage, opts.modelRegistry);
+					: spawnAnt(
+							cwd,
+							nest,
+							task,
+							config,
+							antSignal,
+							callbacks.onAntStream,
+							opts.authStorage,
+							opts.modelRegistry,
+							budgetSection,
+						);
 			let timeoutId: ReturnType<typeof setTimeout>;
 			const result = await Promise.race([
 				antPromise.finally(() => clearTimeout(timeoutId)),
@@ -596,7 +634,11 @@ async function runAntWave(opts: WaveOptions): Promise<"ok" | "budget"> {
 			nest.recordSample(sample);
 		}
 
-		const concurrency = adapt(state.concurrency, pending.length);
+		let concurrency = adapt(state.concurrency, pending.length);
+		// Apply budget-aware concurrency cap (rate limits / cost constraints)
+		if (opts.budgetPlan) {
+			concurrency = applyConcurrencyCap(concurrency, opts.budgetPlan);
+		}
 		nest.updateState({ concurrency });
 
 		// Dispatch ants (concurrency determined by adapt())
@@ -711,7 +753,32 @@ export async function runColony(opts: QueenOptions): Promise<ColonyState> {
 		modelRegistry: opts.modelRegistry,
 	};
 
+	// ═══ Usage-aware budget planning ═══
+	// Query the usage-tracker extension for rate limit / cost data via the event bus.
+	// The result is used to cap concurrency, limit turns, and inject budget context into prompts.
+	const refreshBudgetPlan = (): BudgetPlan | null => {
+		if (!opts.eventBus) {
+			// No event bus → plan based on colony metrics alone (no rate limit awareness)
+			return planBudget(null, nest.getStateLight().metrics, opts.maxCost ?? null, nest.getStateLight().concurrency);
+		}
+
+		// Request fresh data from usage-tracker (fire-and-forget, they respond via "usage:limits")
+		let latestLimits: UsageLimitsEvent | null = null;
+		const handler = (data: unknown) => {
+			latestLimits = data as UsageLimitsEvent;
+		};
+		opts.eventBus.on("usage:limits", handler);
+		opts.eventBus.emit("usage:query");
+		opts.eventBus.off("usage:limits", handler);
+
+		const state = nest.getStateLight();
+		return planBudget(latestLimits, state.metrics, opts.maxCost ?? null, state.concurrency);
+	};
+
 	try {
+		// Initial budget plan
+		waveBase.budgetPlan = refreshBudgetPlan();
+
 		// ═══ Phase 1: Scouting (Bio 5: Colony voting — complex goals get multiple scouts) ═══
 		const scoutCountBase = opts.goal.length > 500 ? 3 : opts.goal.length > 200 ? 2 : 1;
 		const scoutCount = shouldUseScoutQuorum(opts.goal) ? Math.max(2, scoutCountBase) : scoutCountBase;
@@ -785,6 +852,7 @@ export async function runColony(opts: QueenOptions): Promise<ColonyState> {
 		}
 
 		// ═══ Phase 2: Working ═══
+		waveBase.budgetPlan = refreshBudgetPlan(); // Refresh budget before work phase
 		nest.updateState({ status: "working" });
 
 		// Build import graph for dependency-aware scheduling
@@ -885,6 +953,7 @@ export async function runColony(opts: QueenOptions): Promise<ColonyState> {
 		}
 
 		// ═══ Phase 3: Review ═══
+		waveBase.budgetPlan = refreshBudgetPlan(); // Refresh budget before review phase
 		const completedWorkerTasks = nest.getAllTasks().filter((t) => t.caste === "worker" && t.status === "done");
 		if (completedWorkerTasks.length > 0 && (!tscPassed || completedWorkerTasks.length > 3)) {
 			nest.updateState({ status: "reviewing" });
@@ -949,7 +1018,7 @@ export async function resumeColony(opts: QueenOptions): Promise<ColonyState> {
 		callbacks.onSignal?.({ phase, progress, active, cost: m.totalCost, message });
 	};
 
-	const waveBase: Omit<WaveOptions, "caste"> = {
+	const waveBase: Omit<WaveOptions, "caste"> & { budgetPlan?: BudgetPlan | null } = {
 		nest,
 		cwd: opts.cwd,
 		signal,
@@ -961,6 +1030,19 @@ export async function resumeColony(opts: QueenOptions): Promise<ColonyState> {
 		modelRegistry: opts.modelRegistry,
 	};
 
+	// Budget plan for resumed colony
+	if (opts.eventBus) {
+		let latestLimits: UsageLimitsEvent | null = null;
+		const handler = (data: unknown) => {
+			latestLimits = data as UsageLimitsEvent;
+		};
+		opts.eventBus.on("usage:limits", handler);
+		opts.eventBus.emit("usage:query");
+		opts.eventBus.off("usage:limits", handler);
+		const state = nest.getStateLight();
+		waveBase.budgetPlan = planBudget(latestLimits, state.metrics, opts.maxCost ?? null, state.concurrency);
+	}
+
 	const cleanup = () => {
 		nest.destroy();
 		const parentDir = path.join(opts.cwd, ".ant-colony");

package/extensions/ant-colony/spawner.ts

@@ -182,6 +182,7 @@ export async function spawnAnt(
 	onStream?: (event: AntStreamEvent) => void,
 	authStorage?: AuthStorage,
 	modelRegistry?: ModelRegistry,
+	budgetPromptSection?: string,
 ): Promise<AntResult> {
 	if (!antConfig.model) {
 		throw new Error("No model resolved for ant");
@@ -221,7 +222,7 @@ export async function spawnAnt(
 
 	const pheromoneCtx = nest.getPheromoneContext(task.files);
 	const castePrompt = CASTE_PROMPTS[antConfig.caste];
-	const systemPrompt = buildPrompt(task, pheromoneCtx, castePrompt, effectiveMaxTurns, tandem);
+	const systemPrompt = buildPrompt(task, pheromoneCtx, castePrompt, effectiveMaxTurns, tandem, budgetPromptSection);
 
 	const auth = authStorage ?? new AuthStorage();
 	const registry = modelRegistry ?? new ModelRegistry(auth);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ifi/oh-pi-ant-colony",
-  "version": "0.2.3",
+  "version": "0.2.7",
   "description": "Autonomous multi-agent swarm extension for pi — adaptive concurrency, pheromone communication.",
   "keywords": [
     "pi-package"