@ifi/oh-pi-ant-colony 0.2.9 → 0.2.11

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

@@ -68,6 +68,18 @@ export interface CasteBudget {
 }
 
 /** Full budget plan for a colony run. */
+export interface RoutingTelemetrySnapshot {
+	totalRoutes: number;
+	avgLatencyMs: number;
+	outcomeCounts: {
+		claimed: number;
+		completed: number;
+		failed: number;
+		escalated: number;
+	};
+	escalationReasonCounts: Record<string, number>;
+}
+
 export interface BudgetPlan {
 	/** Per-caste allocations. */
 	castes: Record<AntCaste, CasteBudget>;
@@ -79,6 +91,8 @@ export interface BudgetPlan {
 	lowestRateLimitPct: number;
 	/** Human-readable summary for prompt injection. */
 	summary: string;
+	/** Aggregated routing telemetry used for reporting and debugging. */
+	routingTelemetry: RoutingTelemetrySnapshot;
 }
 
 // ═══ Constants ═══
@@ -210,6 +224,7 @@ export function buildBudgetSummary(
 	maxCost: number | null,
 	tasksDone: number,
 	tasksTotal: number,
+	routingTelemetry?: RoutingTelemetrySnapshot,
 ): string {
 	const parts: string[] = [];
 
@@ -233,6 +248,16 @@ export function buildBudgetSummary(
 		parts.push(`Progress: ${tasksDone}/${tasksTotal} tasks completed.`);
 	}
 
+	if (routingTelemetry && routingTelemetry.totalRoutes > 0) {
+		parts.push(
+			`Routing: ${routingTelemetry.totalRoutes} outcomes, avg latency ${routingTelemetry.avgLatencyMs}ms, escalations ${routingTelemetry.outcomeCounts.escalated}.`,
+		);
+		const topEscalation = Object.entries(routingTelemetry.escalationReasonCounts).sort((a, b) => b[1] - a[1])[0];
+		if (topEscalation) {
+			parts.push(`Top escalation reason: ${topEscalation[0]} (${topEscalation[1]}).`);
+		}
+	}
+
 	// Severity-specific guidance
 	switch (severity) {
 		case "critical":
@@ -265,6 +290,33 @@ export function buildBudgetSummary(
  * @param concurrency - Current concurrency config for max bounds.
  * @returns A complete budget plan with per-caste allocations.
  */
+export function buildRoutingTelemetrySnapshot(metrics: ColonyMetrics): RoutingTelemetrySnapshot {
+	const entries = metrics.routingTelemetry ?? [];
+	const outcomeCounts = {
+		claimed: 0,
+		completed: 0,
+		failed: 0,
+		escalated: 0,
+	};
+	const escalationReasonCounts: Record<string, number> = {};
+	let latencyTotal = 0;
+
+	for (const entry of entries) {
+		outcomeCounts[entry.outcome] += 1;
+		latencyTotal += entry.latencyMs;
+		for (const reason of entry.escalationReasons) {
+			escalationReasonCounts[reason] = (escalationReasonCounts[reason] ?? 0) + 1;
+		}
+	}
+
+	return {
+		totalRoutes: entries.length,
+		avgLatencyMs: entries.length > 0 ? Math.round(latencyTotal / entries.length) : 0,
+		outcomeCounts,
+		escalationReasonCounts,
+	};
+}
+
 export function planBudget(
 	usageLimits: UsageLimitsEvent | null,
 	metrics: ColonyMetrics,
@@ -311,6 +363,7 @@ export function planBudget(
 		};
 	}
 
+	const routingTelemetry = buildRoutingTelemetrySnapshot(metrics);
 	const summary = buildBudgetSummary(
 		severity,
 		lowestRateLimitPct,
@@ -318,6 +371,7 @@ export function planBudget(
 		maxCost,
 		metrics.tasksDone,
 		metrics.tasksTotal,
+		routingTelemetry,
 	);
 
 	return {
@@ -326,6 +380,7 @@ export function planBudget(
 		severity,
 		lowestRateLimitPct,
 		summary,
+		routingTelemetry,
 	};
 }
 

package/extensions/ant-colony/index.ts

@@ -35,6 +35,7 @@ import {
 	statusLabel,
 } from "./ui.js";
 import {
+	cleanupIsolatedWorktree,
 	formatWorkspaceReport,
 	formatWorkspaceSummary,
 	prepareColonyWorkspace,
@@ -549,6 +550,17 @@ export default function antColonyExtension(pi: ExtensionAPI) {
 		lastBgStatusSnapshotAt = 0;
 		throttledRender();
 
+		const cleanupWorkspace = (reason: "completion" | "crash") => {
+			const cleanupResult = cleanupIsolatedWorktree(workspace);
+			if (!cleanupResult) {
+				return;
+			}
+			pushLog(colony, {
+				level: /failed|skipped/i.test(cleanupResult) ? "warning" : "info",
+				text: `WORKTREE ${reason.toUpperCase()} CLEANUP · ${cleanupResult}`,
+			});
+		};
+
 		// Wait for completion in background, inject results
 		colony.promise
 			.then((state) => {
@@ -565,6 +577,7 @@ export default function antColonyExtension(pi: ExtensionAPI) {
 					level: ok ? "info" : "error",
 					text: `${statusLabel(phase)} · ${m.tasksDone}/${m.tasksTotal} · ${formatCost(m.totalCost)}`,
 				});
+				cleanupWorkspace("completion");
 
 				colonies.delete(colonyId);
 				if (colonies.size === 0) {
@@ -588,6 +601,7 @@ export default function antColonyExtension(pi: ExtensionAPI) {
 			})
 			.catch((e) => {
 				pushLog(colony, { level: "error", text: `CRASHED · ${String(e).slice(0, 120)}` });
+				cleanupWorkspace("crash");
 				colonies.delete(colonyId);
 				if (colonies.size === 0) {
 					pi.events.emit("ant-colony:clear-ui");
@@ -987,6 +1001,12 @@ export default function antColonyExtension(pi: ExtensionAPI) {
 			soldierModel: Type.Optional(
 				Type.String({ description: "Model for soldier ants (default: current session model)" }),
 			),
+			designWorkerModel: Type.Optional(Type.String({ description: "Model override for design worker class" })),
+			multimodalWorkerModel: Type.Optional(
+				Type.String({ description: "Model override for multimodal worker class (cheap-first default route)" }),
+			),
+			backendWorkerModel: Type.Optional(Type.String({ description: "Model override for backend worker class" })),
+			reviewWorkerModel: Type.Optional(Type.String({ description: "Model override for review worker class" })),
 		}),
 
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
@@ -1008,6 +1028,18 @@ export default function antColonyExtension(pi: ExtensionAPI) {
 			if (params.soldierModel) {
 				modelOverrides.soldier = params.soldierModel;
 			}
+			if (params.designWorkerModel) {
+				modelOverrides.design = params.designWorkerModel;
+			}
+			if (params.multimodalWorkerModel) {
+				modelOverrides.multimodal = params.multimodalWorkerModel;
+			}
+			if (params.backendWorkerModel) {
+				modelOverrides.backend = params.backendWorkerModel;
+			}
+			if (params.reviewWorkerModel) {
+				modelOverrides.review = params.reviewWorkerModel;
+			}
 
 			const colonyParams = {
 				goal: params.goal,

package/extensions/ant-colony/multimodal-routing.ts

@@ -0,0 +1,68 @@
+import type { EscalationReason, Task } from "./types.js";
+
+const IMAGE_EXTENSIONS = new Set([".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp", ".tiff", ".svg", ".heic"]);
+const VIDEO_EXTENSIONS = new Set([".mp4", ".mov", ".m4v", ".avi", ".mkv", ".webm", ".mpeg", ".mpg"]);
+
+export interface IngestionArtifact {
+	path: string;
+	kind: "image" | "video";
+}
+
+export interface MultimodalIngestionReport {
+	hasMultimodalInput: boolean;
+	artifacts: IngestionArtifact[];
+	summary: string;
+}
+
+export function preprocessMultimodalTask(task: Task): MultimodalIngestionReport {
+	const artifacts: IngestionArtifact[] = [];
+	for (const file of task.files) {
+		const lower = file.toLowerCase();
+		const imageExt = [...IMAGE_EXTENSIONS].find((ext) => lower.endsWith(ext));
+		if (imageExt) {
+			artifacts.push({ path: file, kind: "image" });
+			continue;
+		}
+		const videoExt = [...VIDEO_EXTENSIONS].find((ext) => lower.endsWith(ext));
+		if (videoExt) {
+			artifacts.push({ path: file, kind: "video" });
+		}
+	}
+
+	if (artifacts.length === 0) {
+		return {
+			hasMultimodalInput: false,
+			artifacts,
+			summary: "No image/video artifacts detected.",
+		};
+	}
+
+	const imageCount = artifacts.filter((a) => a.kind === "image").length;
+	const videoCount = artifacts.filter((a) => a.kind === "video").length;
+	return {
+		hasMultimodalInput: true,
+		artifacts,
+		summary: `Detected multimodal artifacts: ${imageCount} image(s), ${videoCount} video(s).`,
+	};
+}
+
+export function shouldEscalateMultimodalRoute(task: Task, report: MultimodalIngestionReport): EscalationReason[] {
+	const reasons: EscalationReason[] = [];
+	if (!report.hasMultimodalInput) {
+		return reasons;
+	}
+
+	if (report.artifacts.some((artifact) => artifact.kind === "video")) {
+		reasons.push("risk_flag");
+	}
+
+	if ((task.description ?? "").toLowerCase().includes("policy")) {
+		reasons.push("policy_violation");
+	}
+
+	if ((task.context ?? "").length > 5000) {
+		reasons.push("low_confidence");
+	}
+
+	return reasons;
+}

package/extensions/ant-colony/nest.ts

@@ -19,7 +19,7 @@
 
 import * as fs from "node:fs";
 import * as path from "node:path";
-import type { Ant, ColonyState, ConcurrencySample, Pheromone, Task, TaskStatus } from "./types.js";
+import type { Ant, ColonyState, ConcurrencySample, EscalationReason, Pheromone, Task, TaskStatus } from "./types.js";
 
 /** Minimum pheromone strength to keep (below this, entries are garbage-collected). */
 const PHEROMONE_MIN_STRENGTH = 0.05;
@@ -249,6 +249,31 @@ export class Nest {
 		this.writeTask(task);
 	}
 
+	recordRoutingOutcome(
+		taskId: string,
+		caste: "scout" | "worker" | "soldier" | "drone",
+		outcome: "claimed" | "completed" | "failed" | "escalated",
+		latencyMs: number,
+		escalationReasons: EscalationReason[] = [],
+	): void {
+		this.withStateLock(() => {
+			if (!this.stateCache) {
+				this.stateCache = this.readJson<ColonyState>(this.stateFile);
+			}
+			const routingTelemetry = [...(this.stateCache.metrics.routingTelemetry ?? [])];
+			routingTelemetry.push({
+				taskId,
+				caste,
+				outcome,
+				latencyMs: Math.max(0, Math.floor(latencyMs)),
+				escalationReasons,
+				timestamp: Date.now(),
+			});
+			this.stateCache.metrics.routingTelemetry = routingTelemetry.slice(-500);
+			this.writeJson(this.stateFile, this.stateCache);
+		});
+	}
+
 	/** Register a child task and link it to its parent's `spawnedTasks` list. */
 	addSubTask(parentId: string, child: Task): void {
 		this.writeTask(child);

package/extensions/ant-colony/queen.ts

@@ -24,6 +24,7 @@ import {
 } from "./budget-planner.js";
 import { adapt, defaultConcurrency, sampleSystem } from "./concurrency.js";
 import { buildImportGraph, type ImportGraph, taskDependsOn } from "./deps.js";
+import { preprocessMultimodalTask, shouldEscalateMultimodalRoute } from "./multimodal-routing.js";
 import { Nest } from "./nest.js";
 import { makePheromoneId, makeTaskId, resetAntCounter, runDrone, spawnAnt } from "./spawner.js";
 import type {
@@ -36,8 +37,11 @@ import type {
 	ColonyState,
 	ColonyWorkspace,
 	ModelOverrides,
+	PromoteFinalizeGateDecision,
+	PromoteFinalizeGateInput,
 	Task,
 	TaskPriority,
+	WorkerClass,
 } from "./types.js";
 import { DEFAULT_ANT_CONFIGS } from "./types.js";
 
@@ -158,6 +162,20 @@ function makeInitialScoutTask(goal: string): Task {
 	};
 }
 
+function classifyWorkerClass(title: string, description: string, files: string[]): WorkerClass {
+	const haystack = `${title}\n${description}\n${files.join("\n")}`.toLowerCase();
+	if (/(ui|ux|design|layout|style|css|figma|theme|color|typography|component)/.test(haystack)) {
+		return "design";
+	}
+	if (/(image|video|audio|vision|ocr|multimodal|caption|embedding)/.test(haystack)) {
+		return "multimodal";
+	}
+	if (/(review|qa|validate|verify|audit|test|lint|check)/.test(haystack)) {
+		return "review";
+	}
+	return "backend";
+}
+
 function childTaskFromParsed(
 	parentId: string,
 	parsed: {
@@ -179,6 +197,8 @@ function childTaskFromParsed(
 		priority: parsed.priority,
 		files: parsed.files,
 		context: parsed.context || undefined,
+		workerClass:
+			parsed.caste === "worker" ? classifyWorkerClass(parsed.title, parsed.description, parsed.files) : undefined,
 		claimedBy: null,
 		result: null,
 		error: null,
@@ -242,6 +262,38 @@ export function shouldUseScoutQuorum(goal: string): boolean {
 	return /(\n\s*\d+[.)]|[;；]| and |以及|并且|同时|步骤|phase|then|之后)/i.test(goal);
 }
 
+export function decidePromoteOrFinalize(input: PromoteFinalizeGateInput): PromoteFinalizeGateDecision {
+	const escalationReasons: PromoteFinalizeGateDecision["escalationReasons"] = [];
+	if (input.confidenceScore < 0.78) {
+		escalationReasons.push("low_confidence");
+	}
+	if (input.coverageScore < 0.85) {
+		escalationReasons.push("low_coverage");
+	}
+	if (input.riskFlags.length > 0) {
+		escalationReasons.push("risk_flag");
+	}
+	if (input.policyViolations.length > 0) {
+		escalationReasons.push("policy_violation");
+	}
+	if (input.sloBreached) {
+		escalationReasons.push("slo_breach");
+	}
+
+	if (escalationReasons.length > 0) {
+		return {
+			action: "promote",
+			escalationReasons,
+			cheapPassSummary: input.cheapPassSummary,
+		};
+	}
+
+	return {
+		action: "finalize",
+		escalationReasons,
+	};
+}
+
 export function validateExecutionPlan(tasks: Task[]): PlanValidation {
 	const issues: string[] = [];
 	const warnings: string[] = [];
@@ -378,7 +430,7 @@ interface WaveOptions {
 	modelOverrides?: ModelOverrides;
 	signal?: AbortSignal;
 	callbacks: QueenCallbacks;
-	emitSignal: (phase: ColonyState["status"], message: string) => void;
+	emitSignal: (phase: ColonyState["status"], message: string, extras?: Partial<ColonySignal>) => void;
 	authStorage?: AuthStorage;
 	modelRegistry?: ModelRegistry;
 	importGraph?: ImportGraph;
@@ -462,14 +514,30 @@ async function runAntWave(opts: WaveOptions): Promise<"ok" | "budget"> {
 		if (!task) {
 			return "empty";
 		}
+		nest.recordRoutingOutcome(task.id, caste, "claimed", 0);
+
+		const multimodalReport = caste === "worker" ? preprocessMultimodalTask(task) : null;
+		const multimodalEscalationReasons =
+			caste === "worker" && multimodalReport ? shouldEscalateMultimodalRoute(task, multimodalReport) : [];
+		if (multimodalEscalationReasons.length > 0) {
+			nest.recordRoutingOutcome(task.id, caste, "escalated", 0, multimodalEscalationReasons);
+		}
 
+		const shouldUseCheapMultimodalFirst = caste === "worker" && task.workerClass === "multimodal";
+		let selectedModel =
+			caste === "worker"
+				? (task.workerClass ? opts.modelOverrides?.[task.workerClass] : undefined) || casteModel
+				: casteModel;
+		if (shouldUseCheapMultimodalFirst && opts.modelOverrides?.multimodal) {
+			selectedModel = opts.modelOverrides.multimodal;
+		}
 		const ant: Ant = {
 			id: "",
 			caste,
 			status: "idle",
 			taskId: task.id,
 			pid: null,
-			model: casteModel,
+			model: selectedModel,
 			usage: { input: 0, output: 0, cost: 0, turns: 0 },
 			startedAt: Date.now(),
 			finishedAt: null,
@@ -483,7 +551,7 @@ async function runAntWave(opts: WaveOptions): Promise<"ok" | "budget"> {
 			const antSignal = antAbort.signal;
 			// Bio 7: Age polymorphism — conservative early, convergent late
 			const progress = state.metrics.tasksTotal > 0 ? state.metrics.tasksDone / state.metrics.tasksTotal : 0;
-			const config = { ...baseConfig };
+			const config = { ...baseConfig, model: selectedModel };
 			if (progress < 0.3) {
 				config.maxTurns = Math.max(baseConfig.maxTurns - 3, 5); // Conservative early phase
 			} else if (progress > 0.7) {
@@ -491,6 +559,11 @@ async function runAntWave(opts: WaveOptions): Promise<"ok" | "budget"> {
 			}
 			// Build budget-awareness prompt section for non-drone ants
 			const budgetSection = opts.budgetPlan ? buildBudgetPromptSection(opts.budgetPlan) : undefined;
+			const ingestionSection = multimodalReport?.hasMultimodalInput
+				? `## Multimodal Ingestion\n${multimodalReport.summary}\nArtifacts:\n${multimodalReport.artifacts
+						.map((artifact) => `- ${artifact.kind}: ${artifact.path}`)
+						.join("\n")}`
+				: undefined;
 			const antPromise =
 				caste === "drone"
 					? runDrone(cwd, nest, task)
@@ -504,7 +577,7 @@ async function runAntWave(opts: WaveOptions): Promise<"ok" | "budget"> {
 							callbacks.onAntUsage,
 							opts.authStorage,
 							opts.modelRegistry,
-							budgetSection,
+							[budgetSection, ingestionSection].filter(Boolean).join("\n\n") || undefined,
 						);
 			let timeoutId: ReturnType<typeof setTimeout>;
 			const result = await Promise.race([
@@ -519,9 +592,12 @@ async function runAntWave(opts: WaveOptions): Promise<"ok" | "budget"> {
 			callbacks.onAntDone?.(result.ant, task, result.output);
 
 			if (result.rateLimited) {
+				nest.recordRoutingOutcome(task.id, caste, "escalated", Date.now() - ant.startedAt, ["slo_breach"]);
 				return "rate_limited";
 			}
 
+			nest.recordRoutingOutcome(task.id, caste, "completed", Date.now() - ant.startedAt);
+
 			// Cost warning: signal when >80% of budget is spent
 			const curState = nest.getStateLight();
 			if (curState.maxCost != null) {
@@ -589,8 +665,10 @@ async function runAntWave(opts: WaveOptions): Promise<"ok" | "budget"> {
 			const count = retryCount.get(task.id) ?? 0;
 			if (isRetryable && count < MAX_RETRIES) {
 				retryCount.set(task.id, count + 1);
+				nest.recordRoutingOutcome(task.id, caste, "escalated", Date.now() - ant.startedAt, ["slo_breach"]);
 				nest.updateTaskStatus(task.id, "pending");
 			} else {
+				nest.recordRoutingOutcome(task.id, caste, "failed", Date.now() - ant.startedAt);
 				// Negative pheromone: failed task releases warning proportional to task scope
 				if (task.files.length > 0) {
 					const warnStrength = Math.min(1.0, 0.5 + task.files.length * 0.1);
@@ -800,12 +878,12 @@ export async function runColony(opts: QueenOptions): Promise<ColonyState> {
 		}
 	};
 
-	const emitSignal = (phase: ColonyState["status"], message: string) => {
+	const emitSignal = (phase: ColonyState["status"], message: string, extras?: Partial<ColonySignal>) => {
 		const state = nest.getStateLight();
 		const m = state.metrics;
 		const active = state.ants.filter((a) => a.status === "working").length;
 		const progress = m.tasksTotal > 0 ? m.tasksDone / m.tasksTotal : 0;
-		callbacks.onSignal?.({ phase, progress, active, cost: m.totalCost, message, colonyId: state.id });
+		callbacks.onSignal?.({ phase, progress, active, cost: m.totalCost, message, colonyId: state.id, ...extras });
 	};
 
 	const waveBase: Omit<WaveOptions, "caste"> & { importGraph?: ImportGraph } = {
@@ -1070,12 +1148,12 @@ export async function resumeColony(opts: QueenOptions): Promise<ColonyState> {
 
 	const { signal, callbacks } = opts;
 
-	const emitSignal = (phase: ColonyState["status"], message: string) => {
+	const emitSignal = (phase: ColonyState["status"], message: string, extras?: Partial<ColonySignal>) => {
 		const state = nest.getStateLight();
 		const m = state.metrics;
 		const active = state.ants.filter((a) => a.status === "working").length;
 		const progress = m.tasksTotal > 0 ? m.tasksDone / m.tasksTotal : 0;
-		callbacks.onSignal?.({ phase, progress, active, cost: m.totalCost, message, colonyId: state.id });
+		callbacks.onSignal?.({ phase, progress, active, cost: m.totalCost, message, colonyId: state.id, ...extras });
 	};
 
 	const waveBase: Omit<WaveOptions, "caste"> & { budgetPlan?: BudgetPlan | null } = {

package/extensions/ant-colony/types.ts

@@ -27,8 +27,10 @@ export const DEFAULT_ANT_CONFIGS: Record<AntCaste, Omit<AntConfig, "systemPrompt
 	drone: { caste: "drone", model: "", tools: ["bash"], maxTurns: 1 },
 };
 
-/** Per-caste model overrides from user config */
-export type ModelOverrides = Partial<Record<AntCaste, string>>;
+export type WorkerClass = "design" | "multimodal" | "backend" | "review";
+
+/** Per-caste / per-worker-class model overrides from user config */
+export type ModelOverrides = Partial<Record<AntCaste | WorkerClass, string>>;
 
 // ═══ Tasks (Food Sources) ═══
 export type TaskStatus = "pending" | "claimed" | "active" | "done" | "failed" | "blocked";
@@ -44,6 +46,7 @@ export interface Task {
 	priority: TaskPriority;
 	files: string[]; // Files locked by this task
 	context?: string; // Code snippets pre-loaded by scout
+	workerClass?: WorkerClass; // worker specialization for model routing
 	claimedBy: string | null; // ant id
 	result: string | null;
 	error: string | null;
@@ -162,6 +165,32 @@ export interface ConcurrencySample {
 	throughput: number; // tasks completed per minute
 }
 
+export type EscalationReason = "low_confidence" | "low_coverage" | "risk_flag" | "policy_violation" | "slo_breach";
+
+export interface PromoteFinalizeGateInput {
+	confidenceScore: number;
+	coverageScore: number;
+	riskFlags: string[];
+	policyViolations: string[];
+	sloBreached: boolean;
+	cheapPassSummary: string;
+}
+
+export interface PromoteFinalizeGateDecision {
+	action: "promote" | "finalize";
+	escalationReasons: EscalationReason[];
+	cheapPassSummary?: string;
+}
+
+export interface RoutingTelemetry {
+	taskId: string;
+	caste: AntCaste;
+	outcome: "claimed" | "completed" | "failed" | "escalated";
+	latencyMs: number;
+	escalationReasons: EscalationReason[];
+	timestamp: number;
+}
+
 export interface ColonyMetrics {
 	tasksTotal: number;
 	tasksDone: number;
@@ -171,6 +200,7 @@ export interface ColonyMetrics {
 	totalTokens: number;
 	startTime: number;
 	throughputHistory: number[]; // Sliding window of tasks/min throughput
+	routingTelemetry?: RoutingTelemetry[];
 }
 
 /** Colony signal — the single abstraction observers need to handle. */

package/extensions/ant-colony/worktree.ts

@@ -1,6 +1,6 @@
 import { execFileSync } from "node:child_process";
-import { existsSync, mkdirSync } from "node:fs";
-import { join, relative, resolve } from "node:path";
+import { existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
 import type { ColonyWorkspace } from "./types.js";
 
 const WORKTREE_ENV_FLAG = "PI_ANT_COLONY_WORKTREE";
@@ -58,6 +58,59 @@ function resolveExecutionCwd(worktreeRoot: string, repoRoot: string, originCwd:
 	return existsSync(candidate) ? candidate : worktreeRoot;
 }
 
+export function cleanupIsolatedWorktree(workspace: ColonyWorkspace): string | null {
+	if (workspace.mode !== "worktree" || !workspace.repoRoot || !workspace.worktreeRoot || !workspace.branch) {
+		return null;
+	}
+
+	const notes: string[] = [];
+	try {
+		if (existsSync(workspace.worktreeRoot)) {
+			git(workspace.repoRoot, ["worktree", "remove", "--force", workspace.worktreeRoot]);
+			notes.push("removed isolated worktree");
+		}
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : String(error);
+		notes.push(`worktree remove failed (${reason})`);
+	}
+
+	try {
+		if (workspace.branch) {
+			git(workspace.repoRoot, ["branch", "-D", workspace.branch]);
+			notes.push("deleted temporary branch");
+		}
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : String(error);
+		notes.push(`branch cleanup skipped (${reason})`);
+	}
+
+	try {
+		git(workspace.repoRoot, ["worktree", "prune"]);
+	} catch {
+		// ignore prune failures; this is best-effort hygiene.
+	}
+
+	try {
+		const parent = dirname(workspace.worktreeRoot);
+		rmSync(workspace.worktreeRoot, { recursive: true, force: true });
+		if (existsSync(parent) && isEmptyDir(parent)) {
+			rmSync(parent, { recursive: true, force: true });
+		}
+	} catch {
+		// ignore filesystem cleanup failures.
+	}
+
+	return notes.length > 0 ? `Cleanup: ${notes.join("; ")}.` : "Cleanup: no stale isolated worktree artifacts found.";
+}
+
+function isEmptyDir(path: string): boolean {
+	try {
+		return readdirSync(path).length === 0;
+	} catch {
+		return false;
+	}
+}
+
 export function worktreeEnabledByDefault(): boolean {
 	const raw = process.env[WORKTREE_ENV_FLAG];
 	if (typeof raw !== "string") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ifi/oh-pi-ant-colony",
-  "version": "0.2.9",
+  "version": "0.2.11",
   "description": "Autonomous multi-agent swarm extension for pi — adaptive concurrency, pheromone communication.",
   "keywords": [
     "pi-package"
@@ -22,5 +22,11 @@
     "@mariozechner/pi-coding-agent": "*",
     "@mariozechner/pi-tui": "*",
     "@sinclair/typebox": "*"
+  },
+  "scripts": {
+    "build": "pnpm run typecheck:worktree && pnpm run test:worktree",
+    "typecheck": "pnpm run typecheck:worktree",
+    "typecheck:worktree": "tsgo --project ./tsconfig.json --noEmit",
+    "test:worktree": "vitest run --config ./vitest.worktree.config.ts"
   }
 }