@tmustier/pi-agent-teams 0.4.0-beta.3 → 0.5.0

package/extensions/teams/leader-attach-commands.ts

@@ -30,6 +30,7 @@ export async function handleTeamAttachCommand(opts: {
 	setTaskListId: (id: string) => void;
 	refreshTasks: () => Promise<void>;
 	renderWidget: () => void;
+	restoreWidget: () => void;
 }): Promise<void> {
 	const {
 		ctx,
@@ -41,7 +42,7 @@ export async function handleTeamAttachCommand(opts: {
 		setStyle,
 		setTaskListId,
 		refreshTasks,
-		renderWidget,
+		restoreWidget,
 	} = opts;
 
 	const tokens = rest.map((t) => t.trim()).filter((t) => t.length > 0);
@@ -163,7 +164,8 @@ export async function handleTeamAttachCommand(opts: {
 	setTaskListId(cfg.taskListId);
 	setStyle(cfg.style ?? "normal");
 	await refreshTasks();
-	renderWidget();
+	// Clear any /team done suppression — attaching to a team is explicit intent to work.
+	restoreWidget();
 
 	const lines: string[] = [
 		`Attached to team: ${cfg.teamId}`,
@@ -185,8 +187,9 @@ export async function handleTeamDetachCommand(opts: {
 	setTaskListId: (id: string) => void;
 	refreshTasks: () => Promise<void>;
 	renderWidget: () => void;
+	restoreWidget: () => void;
 }): Promise<void> {
-	const { ctx, defaultTeamId, teammates, getActiveTeamId, setActiveTeamId, setTaskListId, refreshTasks, renderWidget } = opts;
+	const { ctx, defaultTeamId, teammates, getActiveTeamId, setActiveTeamId, setTaskListId, refreshTasks, restoreWidget } = opts;
 
 	const activeTeamId = getActiveTeamId();
 	if (activeTeamId === defaultTeamId) {
@@ -207,7 +210,8 @@ export async function handleTeamDetachCommand(opts: {
 	setActiveTeamId(defaultTeamId);
 	setTaskListId(defaultTeamId);
 	await refreshTasks();
-	renderWidget();
+	// Clear any /team done suppression — returning to own team.
+	restoreWidget();
 
 	if (releaseResult === "not_owner") {
 		ctx.ui.notify(

package/extensions/teams/leader-inbox.ts

@@ -10,12 +10,78 @@ import {
 	isShutdownRejected,
 } from "./protocol.js";
 import { ensureTeamConfig, setMemberStatus, upsertMember } from "./team-config.js";
-import { getTask } from "./task-store.js";
+import { getTask, listTasks } from "./task-store.js";
 
 import type { TeamsHookInvocation } from "./hooks.js";
 import type { TeamsStyle } from "./teams-style.js";
 import { formatMemberDisplayName, getTeamsStrings } from "./teams-style.js";
 
+/** Callback to inject a message into the leader LLM conversation. */
+export type SendLeaderLlmMessage = (content: string, options?: { deliverAs?: "steer" | "followUp" }) => void;
+
+/**
+ * Event-driven tracker for delegation batches.
+ *
+ * Tracks task IDs from delegate() calls. Tasks are only marked done
+ * when an idle_notification with completedTaskId is received — NOT
+ * by polling task file status. This avoids race conditions where
+ * listTasks() returns stale or premature data.
+ */
+export class DelegationTracker {
+	private batches: Array<{
+		taskIds: Set<string>;
+		completedIds: Set<string>;
+		notified: boolean;
+	}> = [];
+
+	/** Register a new batch of delegated task IDs. */
+	addBatch(taskIds: string[]): void {
+		if (taskIds.length === 0) return;
+		this.batches.push({
+			taskIds: new Set(taskIds),
+			completedIds: new Set(),
+			notified: false,
+		});
+	}
+
+	/**
+	 * Mark a task as completed (called when idle_notification with
+	 * completedTaskId is received). Returns any batches that became
+	 * fully complete as a result.
+	 */
+	markCompleted(taskId: string): Array<{ taskIds: string[] }> {
+		const newlyComplete: Array<{ taskIds: string[] }> = [];
+
+		for (const batch of this.batches) {
+			if (batch.notified) continue;
+			if (!batch.taskIds.has(taskId)) continue;
+
+			batch.completedIds.add(taskId);
+
+			const allDone = [...batch.taskIds].every((id) => batch.completedIds.has(id));
+			if (allDone) {
+				batch.notified = true;
+				newlyComplete.push({ taskIds: [...batch.taskIds] });
+			}
+		}
+
+		// Prune notified batches
+		this.batches = this.batches.filter((b) => !b.notified);
+		return newlyComplete;
+	}
+
+	/** Clear all tracked batches (e.g. on session switch). */
+	clear(): void {
+		this.batches = [];
+	}
+}
+
+/** Truncate a result string to stay within token budget. */
+function truncateResult(text: string, maxLen: number): string {
+	if (text.length <= maxLen) return text;
+	return text.slice(0, maxLen) + "…";
+}
+
 export async function pollLeaderInbox(opts: {
 	ctx: ExtensionContext;
 	teamId: string;
@@ -25,8 +91,11 @@ export async function pollLeaderInbox(opts: {
 	style: TeamsStyle;
 	pendingPlanApprovals: Map<string, { requestId: string; name: string; taskId?: string }>;
 	enqueueHook?: (invocation: TeamsHookInvocation) => void;
+	sendLeaderLlmMessage?: SendLeaderLlmMessage;
+	/** Batch delegation tracker for all-tasks-complete auto-notify. */
+	delegationTracker?: DelegationTracker;
 }): Promise<void> {
-	const { ctx, teamId, teamDir, taskListId, leadName, style, pendingPlanApprovals, enqueueHook } = opts;
+	const { ctx, teamId, teamDir, taskListId, leadName, style, pendingPlanApprovals, enqueueHook, sendLeaderLlmMessage, delegationTracker } = opts;
 	const strings = getTeamsStrings(style);
 
 	let msgs: Awaited<ReturnType<typeof popUnreadMessages>>;
@@ -38,6 +107,10 @@ export async function pollLeaderInbox(opts: {
 	}
 	if (!msgs.length) return;
 
+	// Collect batch completions across all messages in this poll cycle,
+	// then fire notifications once at the end (avoids duplicate triggers).
+	const batchCompletions: Array<{ taskIds: string[] }> = [];
+
 	for (const m of msgs) {
 		const approved = isShutdownApproved(m.text);
 		if (approved) {
@@ -132,6 +205,13 @@ export async function pollLeaderInbox(opts: {
 				} catch {
 					// ignore hook enqueue errors
 				}
+
+				// Event-driven batch tracking: mark this task done and
+				// collect any batches that became fully complete.
+				if (delegationTracker && idle.completedStatus !== "failed") {
+					const completed = delegationTracker.markCompleted(idle.completedTaskId);
+					batchCompletions.push(...completed);
+				}
 			}
 
 			if (idle.failureReason) {
@@ -200,8 +280,59 @@ export async function pollLeaderInbox(opts: {
 
 				if (idle.completedTaskId && idle.completedStatus === "failed") {
 					ctx.ui.notify(`${name} aborted task #${idle.completedTaskId}`, "warning");
+
+					// Inject failure notification into leader LLM conversation
+					if (sendLeaderLlmMessage) {
+						const task = await getTask(teamDir, taskListId, idle.completedTaskId);
+						const subject = task?.subject ? `: ${task.subject}` : "";
+						// Failed tasks store abort details, not the success-only `result` field.
+						const abortReasonRaw = task?.metadata?.["abortReason"];
+						const partialResultRaw = task?.metadata?.["partialResult"];
+						const abortReason = typeof abortReasonRaw === "string" ? truncateResult(abortReasonRaw, 300) : undefined;
+						const partialResult = typeof partialResultRaw === "string" ? truncateResult(partialResultRaw, 300) : undefined;
+						const lines = [
+							`[Team] ${formatMemberDisplayName(style, name)} failed task #${idle.completedTaskId}${subject}`,
+						];
+						if (abortReason) lines.push(`Reason: ${abortReason}`);
+						if (partialResult) lines.push(`Partial result: ${partialResult}`);
+						sendLeaderLlmMessage(lines.join("\n"), { deliverAs: "followUp" });
+					}
 				} else if (idle.completedTaskId) {
-					ctx.ui.notify(`${name} is idle task #${idle.completedTaskId}`, "info");
+					ctx.ui.notify(`${name} completed task #${idle.completedTaskId}`, "info");
+
+					// Inject completion notification into leader LLM conversation
+					if (sendLeaderLlmMessage) {
+						const task = await getTask(teamDir, taskListId, idle.completedTaskId);
+						const subject = task?.subject ? `: ${task.subject}` : "";
+						const resultRaw = task?.metadata?.["result"];
+						const result = typeof resultRaw === "string" ? truncateResult(resultRaw, 500) : undefined;
+						const lines = [
+							`[Team] ${formatMemberDisplayName(style, name)} completed task #${idle.completedTaskId}${subject}`,
+						];
+						if (result) lines.push(`Result: ${result}`);
+
+						// Check if all tasks are now completed
+						const allTasks = await listTasks(teamDir, taskListId);
+						const totalTasks = allTasks.length;
+						const completedTasks = allTasks.filter((t) => t.status === "completed");
+						const allDone = totalTasks > 0 && completedTasks.length === totalTasks;
+
+						if (allDone) {
+							lines.push("");
+							if (enqueueHook) {
+								// Hooks run asynchronously and may reopen tasks or create follow-ups.
+								lines.push(`All ${totalTasks} task(s) show completed — quality gates are still running and may change task states.`);
+							} else {
+								lines.push(`All ${totalTasks} task(s) are now completed. Review results and determine next steps.`);
+							}
+						} else {
+							const pending = allTasks.filter((t) => t.status === "pending").length;
+							const inProgress = allTasks.filter((t) => t.status === "in_progress").length;
+							lines.push(`Progress: ${completedTasks.length}/${totalTasks} done (${pending} pending, ${inProgress} in progress)`);
+						}
+
+						sendLeaderLlmMessage(lines.join("\n"), { deliverAs: "followUp" });
+					}
 				} else {
 					ctx.ui.notify(`${name} is idle`, "info");
 				}
@@ -209,6 +340,33 @@ export async function pollLeaderInbox(opts: {
 			continue;
 		}
 
-		ctx.ui.notify(`Message from ${m.from}: ${m.text}`, "info");
+		// Unrecognized message = teammate DM → route to leader LLM context
+		if (sendLeaderLlmMessage) {
+			sendLeaderLlmMessage(`[Team DM] ${m.from}: ${m.text}`, { deliverAs: "followUp" });
+		} else {
+			ctx.ui.notify(`Message from ${m.from}: ${m.text}`, "info");
+		}
+	}
+
+	// Fire batch-complete notifications (deduplicated across this poll cycle).
+	// Uses sendLeaderLlmMessage directly (without deliverAs) when idle so it
+	// triggers a new LLM turn, waking the leader to review and continue.
+	if (sendLeaderLlmMessage) {
+		for (const batch of batchCompletions) {
+			const taskRefs = batch.taskIds.map((id) => `#${id}`).join(", ");
+			const suffix = enqueueHook
+				? "Quality gates are still running and may change task states."
+				: "Review the results and continue.";
+			const msg = `[Team] All delegated tasks completed (${taskRefs}). ${suffix}`;
+			try {
+				if (ctx.isIdle()) {
+					sendLeaderLlmMessage(msg);
+				} else {
+					sendLeaderLlmMessage(msg, { deliverAs: "followUp" });
+				}
+			} catch {
+				ctx.ui.notify(`✅ ${msg}`, "info");
+			}
+		}
 	}
 }

package/extensions/teams/leader-info-commands.ts

@@ -5,16 +5,20 @@ import type { TeammateRpc } from "./teammate-rpc.js";
 import type { TeamConfig, TeamMember } from "./team-config.js";
 import type { TeamsStyle } from "./teams-style.js";
 import { formatMemberDisplayName, getTeamsStrings } from "./teams-style.js";
+import { resolveDisplayStatus, formatElapsed, formatTokens, lastMessageSummary, toolActivity } from "./teams-ui-shared.js";
+import type { ActivityTracker } from "./activity-tracker.js";
+import { listTasks } from "./task-store.js";
 
 export async function handleTeamListCommand(opts: {
 	ctx: ExtensionCommandContext;
 	teammates: Map<string, TeammateRpc>;
 	getTeamConfig: () => TeamConfig | null;
+	getTracker: () => ActivityTracker;
 	style: TeamsStyle;
 	refreshTasks: () => Promise<void>;
 	renderWidget: () => void;
 }): Promise<void> {
-	const { ctx, teammates, getTeamConfig, style, refreshTasks, renderWidget } = opts;
+	const { ctx, teammates, getTeamConfig, getTracker, style, refreshTasks, renderWidget } = opts;
 	const strings = getTeamsStrings(style);
 
 	await refreshTasks();
@@ -34,13 +38,19 @@ export async function handleTeamListCommand(opts: {
 		return;
 	}
 
+	const tracker = getTracker();
 	const lines: string[] = [];
 	for (const name of Array.from(names).sort()) {
 		const rpc = teammates.get(name);
 		const cfg = cfgByName.get(name);
-		const status = rpc ? rpc.status : cfg?.status ?? "offline";
+		const displayStatus = resolveDisplayStatus(rpc, cfg);
 		const kind = rpc ? "rpc" : cfg ? "manual" : "unknown";
-		lines.push(`${formatMemberDisplayName(style, name)}: ${status} (${kind})`);
+		const elapsed = rpc ? formatElapsed(Date.now() - rpc.lastStatusChangeAt) : "";
+		const activity = tracker.get(name);
+		const tool = toolActivity(activity.currentToolName);
+		const elapsedTag = elapsed ? ` ${elapsed}` : "";
+		const toolTag = tool ? ` (${tool})` : "";
+		lines.push(`${formatMemberDisplayName(style, name)}: ${displayStatus}${elapsedTag}${toolTag} [${kind}]`);
 	}
 
 	ctx.ui.notify(lines.join("\n"), "info");
@@ -138,3 +148,95 @@ export async function handleTeamEnvCommand(opts: {
 		"info",
 	);
 }
+
+export async function handleTeamStatusCommand(opts: {
+	ctx: ExtensionCommandContext;
+	rest: string[];
+	teammates: Map<string, TeammateRpc>;
+	getTeamConfig: () => TeamConfig | null;
+	getTracker: () => ActivityTracker;
+	teamId: string;
+	taskListId: string | null;
+	style: TeamsStyle;
+}): Promise<void> {
+	const { ctx, rest, teammates, getTeamConfig, getTracker, teamId, taskListId, style } = opts;
+	const strings = getTeamsStrings(style);
+	const tracker = getTracker();
+	const teamConfig = getTeamConfig();
+	const teamDir = getTeamDir(teamId);
+	const effectiveTlId = taskListId ?? teamId;
+
+	const nameRaw = rest[0];
+
+	// If no name, show summary of all workers (same as member_status with no name).
+	if (!nameRaw) {
+		const cfgMembers = teamConfig?.members ?? [];
+		const cfgByName = new Map<string, TeamMember>();
+		for (const m of cfgMembers) cfgByName.set(m.name, m);
+
+		const workerNames = new Set<string>();
+		for (const n of teammates.keys()) workerNames.add(n);
+		for (const m of cfgMembers) {
+			if (m.role === "worker" && m.status === "online") workerNames.add(m.name);
+		}
+
+		if (workerNames.size === 0) {
+			ctx.ui.notify(`No ${strings.memberTitle.toLowerCase()}s`, "info");
+			return;
+		}
+
+		const lines: string[] = [];
+		for (const n of Array.from(workerNames).sort()) {
+			const rpc = teammates.get(n);
+			const cfg = cfgByName.get(n);
+			const displayStatus = resolveDisplayStatus(rpc, cfg);
+			const activity = tracker.get(n);
+			const elapsed = rpc ? formatElapsed(Date.now() - rpc.lastStatusChangeAt) : "";
+			const tool = toolActivity(activity.currentToolName);
+			const toolTag = tool ? ` (${tool})` : "";
+			const stalledTag = displayStatus === "stalled" ? " ⚠ STALLED" : "";
+			lines.push(`${formatMemberDisplayName(style, n)}: ${displayStatus} ${elapsed}${toolTag} · ${formatTokens(activity.totalTokens)} tokens${stalledTag}`);
+		}
+		ctx.ui.notify(lines.join("\n"), "info");
+		return;
+	}
+
+	// Single worker detail view.
+	const name = sanitizeName(nameRaw);
+	const rpc = teammates.get(name);
+	const memberCfg = (teamConfig?.members ?? []).find((m) => m.name === name);
+	if (!rpc && !memberCfg) {
+		ctx.ui.notify(`Unknown ${strings.memberTitle.toLowerCase()}: ${name}`, "error");
+		return;
+	}
+
+	const displayStatus = resolveDisplayStatus(rpc, memberCfg);
+	const activity = tracker.get(name);
+	const elapsed = rpc ? formatElapsed(Date.now() - rpc.lastStatusChangeAt) : "";
+	const noEventFor = rpc ? formatElapsed(Date.now() - rpc.lastEventAt) : "";
+	const currentTool = toolActivity(activity.currentToolName);
+	const msgPreview = lastMessageSummary(rpc, 120);
+	const allTasks = await listTasks(teamDir, effectiveTlId);
+	const owned = allTasks.filter((t) => t.owner === name);
+	const activeTask = owned.find((t) => t.status === "in_progress");
+	const model = memberCfg?.meta?.["model"];
+	const cwd = memberCfg?.cwd;
+
+	const lines: string[] = [
+		`${formatMemberDisplayName(style, name)}: ${displayStatus}`,
+		`time in state: ${elapsed || "(unknown)"}`,
+		`last event: ${noEventFor || "(unknown)"} ago`,
+		`current activity: ${currentTool || "(none)"}`,
+		`tool calls: ${activity.toolUseCount} · turns: ${activity.turnCount} · tokens: ${formatTokens(activity.totalTokens)}`,
+	];
+	if (typeof model === "string" && model) lines.push(`model: ${model}`);
+	if (cwd) lines.push(`cwd: ${cwd}`);
+	if (activeTask) lines.push(`active task: #${activeTask.id} ${activeTask.subject}`);
+	lines.push(`tasks: ${owned.filter((t) => t.status === "pending").length} pending · ${owned.filter((t) => t.status === "in_progress").length} in-progress · ${owned.filter((t) => t.status === "completed").length} completed`);
+	if (msgPreview) lines.push(`last message: ${msgPreview}`);
+	if (displayStatus === "stalled") {
+		lines.push(`⚠ WARNING: no agent events for ${noEventFor} — worker may be stalled`);
+	}
+
+	ctx.ui.notify(lines.join("\n"), "info");
+}

package/extensions/teams/leader-lifecycle-commands.ts

@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import type { ExtensionCommandContext, ExtensionContext } from "@mariozechner/pi-coding-agent";
-import { cleanupTeamDir } from "./cleanup.js";
+import { cleanupTeamDir, gcStaleTeamDirs } from "./cleanup.js";
 import { writeToMailbox } from "./mailbox.js";
 import { sanitizeName } from "./names.js";
 import { getTeamDir, getTeamsRootDir, getTeamsStylesDir } from "./paths.js";
@@ -220,13 +220,23 @@ export async function handleTeamCleanupCommand(opts: {
 	}
 
 	try {
-		await cleanupTeamDir(teamsRoot, teamDir);
+		const result = await cleanupTeamDir(teamsRoot, teamDir, { teamId, repoCwd: ctx.cwd });
+		const parts: string[] = [`Cleaned up team directory: ${teamDir}`];
+		if (result.worktreeResult.removedWorktrees.length > 0) {
+			parts.push(`Removed ${result.worktreeResult.removedWorktrees.length} worktree(s)`);
+		}
+		if (result.worktreeResult.removedBranches.length > 0) {
+			parts.push(`Removed ${result.worktreeResult.removedBranches.length} branch(es)`);
+		}
+		for (const w of result.warnings) {
+			parts.push(`⚠ ${w}`);
+		}
+		ctx.ui.notify(parts.join("\n"), "warning");
 	} catch (err) {
 		ctx.ui.notify(err instanceof Error ? err.message : String(err), "error");
 		return;
 	}
 
-	ctx.ui.notify(`Cleaned up team directory: ${teamDir}`, "warning");
 	await refreshTasks();
 	renderWidget();
 }
@@ -519,6 +529,116 @@ export async function handleTeamStopCommand(opts: {
 	renderWidget();
 }
 
+/**
+ * `/team done` — end-of-run cleanup.
+ *
+ * Stops all teammates, hides the widget, and optionally cleans up team artifacts.
+ * This is the "team is finished" ergonomic counterpart to `/team cleanup`.
+ *
+ * Behavior:
+ * 1. Stops all RPC teammates (graceful, no confirmation prompt).
+ * 2. Marks all config-only workers offline.
+ * 3. Hides the Teams widget.
+ * 4. Notifies the user with a summary.
+ *
+ * Use `/team cleanup [--force]` afterward if you also want to delete task/mailbox files.
+ */
+export async function handleTeamDoneCommand(opts: {
+	ctx: ExtensionCommandContext;
+	rest: string[];
+	teamId: string;
+	teammates: Map<string, TeammateRpc>;
+	getTeamConfig: () => TeamConfig | null;
+	leadName: string;
+	style: TeamsStyle;
+	stopAllTeammates: (ctx: ExtensionContext, reason: string) => Promise<void>;
+	refreshTasks: () => Promise<void>;
+	getTasks: () => TeamTask[];
+	hideWidget: () => void;
+}): Promise<void> {
+	const { ctx, rest, teamId, teammates, getTeamConfig, leadName, style, stopAllTeammates, refreshTasks, getTasks, hideWidget } = opts;
+	const strings = getTeamsStrings(style);
+
+	const flags = rest.filter((a) => a.startsWith("--"));
+	const unknownFlags = flags.filter((f) => f !== "--force");
+	if (unknownFlags.length) {
+		ctx.ui.notify(`Unknown flag(s): ${unknownFlags.join(", ")}`, "error");
+		return;
+	}
+
+	await refreshTasks();
+	const tasks = getTasks();
+	const inProgress = tasks.filter((t) => t.status === "in_progress");
+
+	if (inProgress.length > 0 && !flags.includes("--force")) {
+		ctx.ui.notify(
+			`${inProgress.length} task(s) still in progress. Use /team done --force to end anyway.`,
+			"error",
+		);
+		return;
+	}
+
+	// Stop all RPC teammates
+	const reason = formatTeamsTemplate(strings.teamEndedAllStopped, {
+		members: `${strings.memberTitle.toLowerCase()}s`,
+		count: String(teammates.size),
+	});
+	await stopAllTeammates(ctx, reason);
+
+	// Mark manual/config workers offline
+	const cfg = getTeamConfig();
+	const teamDir = getTeamDir(teamId);
+	const manualWorkers = (cfg?.members ?? []).filter((m) => m.role === "worker" && m.status === "online");
+	for (const m of manualWorkers) {
+		if (teammates.has(m.name)) continue;
+		const ts = new Date().toISOString();
+		try {
+			await writeToMailbox(teamDir, TEAM_MAILBOX_NS, m.name, {
+				from: leadName,
+				text: JSON.stringify({
+					type: "shutdown_request",
+					requestId: randomUUID(),
+					from: leadName,
+					timestamp: ts,
+					reason: "Team done",
+				}),
+				timestamp: ts,
+			});
+		} catch {
+			// ignore
+		}
+		await setMemberStatus(teamDir, m.name, "offline", {
+			meta: { stoppedReason: "team-done", stoppedAt: ts },
+		});
+	}
+
+	// Unassign any in-progress tasks (force mode)
+	if (inProgress.length > 0) {
+		for (const task of inProgress) {
+			if (task.owner) {
+				await unassignTasksForAgent(teamDir, cfg?.taskListId ?? teamId, task.owner, "team done");
+			}
+		}
+	}
+
+	await refreshTasks();
+
+	// Hide the widget
+	hideWidget();
+
+	// Summary
+	const completed = tasks.filter((t) => t.status === "completed").length;
+	const pending = tasks.filter((t) => t.status === "pending").length;
+	const total = tasks.length;
+
+	const summaryParts = [`Team done. ${total} task(s): ${completed} completed`];
+	if (pending > 0) summaryParts.push(`${pending} pending`);
+	if (inProgress.length > 0) summaryParts.push(`${inProgress.length} were in-progress (unassigned)`);
+	summaryParts.push("Widget hidden. Use /team cleanup to remove artifacts.");
+
+	ctx.ui.notify(summaryParts.join(", ") + ".", "info");
+}
+
 export async function handleTeamKillCommand(opts: {
 	ctx: ExtensionCommandContext;
 	rest: string[];
@@ -557,3 +677,85 @@ export async function handleTeamKillCommand(opts: {
 	await refreshTasks();
 	renderWidget();
 }
+
+const DEFAULT_GC_MAX_AGE_HOURS = 24;
+
+export async function handleTeamGcCommand(opts: {
+	ctx: ExtensionCommandContext;
+	rest: string[];
+}): Promise<void> {
+	const { ctx, rest } = opts;
+
+	const flags = rest.filter((a) => a.startsWith("--"));
+	const argsOnly = rest.filter((a) => !a.startsWith("--"));
+	const dryRun = flags.includes("--dry-run");
+	const force = flags.includes("--force");
+
+	const unknownFlags = flags.filter((f) => f !== "--dry-run" && f !== "--force" && !f.startsWith("--max-age-hours="));
+	if (unknownFlags.length) {
+		ctx.ui.notify(`Unknown flag(s): ${unknownFlags.join(", ")}`, "error");
+		return;
+	}
+	if (argsOnly.length) {
+		ctx.ui.notify("Usage: /team gc [--dry-run] [--force] [--max-age-hours=N]", "error");
+		return;
+	}
+
+	// Parse --max-age-hours=N
+	let maxAgeHours = DEFAULT_GC_MAX_AGE_HOURS;
+	const maxAgeFlag = flags.find((f) => f.startsWith("--max-age-hours="));
+	if (maxAgeFlag) {
+		const val = Number(maxAgeFlag.split("=")[1]);
+		if (!Number.isFinite(val) || val < 0) {
+			ctx.ui.notify("--max-age-hours must be a non-negative number", "error");
+			return;
+		}
+		maxAgeHours = val;
+	}
+
+	const teamsRoot = getTeamsRootDir();
+	const maxAgeMs = maxAgeHours * 60 * 60 * 1000;
+
+	if (!force && !dryRun) {
+		if (process.stdout.isTTY && process.stdin.isTTY) {
+			const ok = await ctx.ui.confirm(
+				"Garbage collect teams",
+				`Remove all stale team directories older than ${maxAgeHours}h?\nTeams root: ${teamsRoot}`,
+			);
+			if (!ok) return;
+		} else {
+			ctx.ui.notify("Use --force or --dry-run in non-interactive mode", "error");
+			return;
+		}
+	}
+
+	const result = await gcStaleTeamDirs({
+		teamsRootDir: teamsRoot,
+		maxAgeMs,
+		repoCwd: ctx.cwd,
+		dryRun,
+	});
+
+	const lines: string[] = [];
+	if (dryRun) {
+		lines.push(`[DRY RUN] Would remove ${result.removed.length} of ${result.scanned} team dirs`);
+	} else {
+		lines.push(`Removed ${result.removed.length} of ${result.scanned} team dirs`);
+	}
+	if (result.skipped.length > 0) {
+		const byReason = new Map<string, number>();
+		for (const s of result.skipped) {
+			byReason.set(s.reason, (byReason.get(s.reason) ?? 0) + 1);
+		}
+		const parts: string[] = [];
+		for (const [reason, count] of byReason) {
+			parts.push(`${count} ${reason}`);
+		}
+		lines.push(`Skipped: ${parts.join(", ")}`);
+	}
+	for (const w of result.warnings) {
+		lines.push(`⚠ ${w}`);
+	}
+
+	ctx.ui.notify(lines.join("\n"), dryRun ? "info" : "warning");
+}