pi-crew 0.1.45 → 0.1.49

package/src/runtime/team-runner.ts

@@ -3,6 +3,7 @@ import type { AgentConfig } from "../agents/agent-config.ts";
 import type { CrewLimitsConfig, CrewRuntimeConfig, CrewReliabilityConfig } from "../config/config.ts";
 import type { CrewRuntimeCapabilities } from "./runtime-resolver.ts";
 import { writeArtifact } from "../state/artifact-store.ts";
+import { executeHook, appendHookEvent } from "../hooks/registry.ts";
 import { appendEvent } from "../state/event-log.ts";
 import type { TeamConfig } from "../teams/team-config.ts";
 import type { ArtifactDescriptor, PolicyDecision, TeamRunManifest, TaskAttemptState, TeamTaskState } from "../state/types.ts";
@@ -25,6 +26,8 @@ import { childCorrelation, withCorrelation } from "../observability/correlation.
 import { resolveBatchConcurrency } from "./concurrency.ts";
 import { mapConcurrent } from "./parallel-utils.ts";
 import { permissionForRole } from "./role-permission.ts";
+import { CrewCancellationError, buildSyntheticTerminalEvidence, cancellationReasonFromSignal } from "./cancellation.ts";
+import { effectivenessPolicyDecision, evaluateRunEffectiveness, formatRunEffectivenessLines } from "./effectiveness.ts";
 
 export interface ExecuteTeamRunInput {
 	manifest: TeamRunManifest;
@@ -43,6 +46,8 @@ export interface ExecuteTeamRunInput {
 	signal?: AbortSignal;
 	reliability?: CrewReliabilityConfig;
 	metricRegistry?: MetricRegistry;
+	/** Skill override from the team tool. false disables skill injection for this run. */
+	skillOverride?: string[] | false;
 	/** Optional callback for JSON events from child Pi. Used for overflow recovery tracking. */
 	onJsonEvent?: (taskId: string, runId: string, event: unknown) => void;
 }
@@ -380,7 +385,11 @@ function formatTaskProgress(task: TeamTaskState): string {
 	return `- ${task.id}: ${task.status} (${task.role} -> ${task.agent})${task.taskPacket ? ` scope=${task.taskPacket.scope}` : ""}${task.verification ? ` green=${task.verification.observedGreenLevel}/${task.verification.requiredGreenLevel}` : ""}${task.error ? ` - ${task.error}` : ""}`;
 }
 
-function writeProgress(manifest: TeamRunManifest, tasks: TeamTaskState[], producer: string): TeamRunManifest {
+function runEffectivenessLines(manifest: TeamRunManifest, tasks: TeamTaskState[], executeWorkers: boolean, runtimeConfig?: CrewRuntimeConfig): string[] {
+	return formatRunEffectivenessLines(evaluateRunEffectiveness({ manifest, tasks, executeWorkers, runtimeConfig }));
+}
+
+function writeProgress(manifest: TeamRunManifest, tasks: TeamTaskState[], producer: string, executeWorkers = true, runtimeConfig?: CrewRuntimeConfig): TeamRunManifest {
 	const counts = new Map<string, number>();
 	for (const task of tasks) counts.set(task.status, (counts.get(task.status) ?? 0) + 1);
 	const queue = taskGraphSnapshot(tasks);
@@ -401,6 +410,9 @@ function writeProgress(manifest: TeamRunManifest, tasks: TeamTaskState[], produc
 			"## Tasks",
 			...tasks.map(formatTaskProgress),
 			"",
+			"## Effectiveness",
+			...runEffectivenessLines(manifest, tasks, executeWorkers, runtimeConfig),
+			"",
 		].join("\n"),
 	});
 	return { ...manifest, updatedAt: new Date().toISOString(), artifacts: [...manifest.artifacts.filter((artifact) => !(artifact.kind === "progress" && artifact.path === progress.path)), progress] };
@@ -495,6 +507,39 @@ function hasPendingMutatingAdaptiveTask(tasks: TeamTaskState[]): boolean {
 export async function executeTeamRun(input: ExecuteTeamRunInput): Promise<{ manifest: TeamRunManifest; tasks: TeamTaskState[] }> {
 	let workflow = input.workflow;
 	let manifest = updateRunStatus(input.manifest, "running", input.executeWorkers ? "Executing team workflow." : "Creating workflow prompts and placeholder results.");
+
+	try {
+		return await executeTeamRunCore(input, manifest, workflow);
+	} catch (error) {
+		// P1: Catch unhandled errors — ensure manifest is set to "failed" so it doesn't stay "running" forever.
+		const message = error instanceof Error ? error.message : String(error);
+		try {
+			manifest = updateRunStatus(manifest, "failed", `Unhandled error in team runner: ${message}`);
+			await saveRunManifestAsync(manifest);
+		} catch {
+			// Best-effort — state write may also fail
+		}
+		const tasks = refreshTaskGraphQueues(input.tasks).map((task) =>
+			task.status === "running" || task.status === "queued" || task.status === "waiting"
+				? { ...task, status: "failed" as const, finishedAt: new Date().toISOString(), error: message }
+				: task,
+		);
+		return { manifest, tasks };
+	}
+}
+
+async function executeTeamRunCore(
+	input: ExecuteTeamRunInput,
+	manifest: TeamRunManifest,
+	workflow: WorkflowConfig,
+): Promise<{ manifest: TeamRunManifest; tasks: TeamTaskState[] }> {
+	// Execute before_run_start hook (non-blocking by default)
+	const beforeRunReport = await executeHook("before_run_start", { runId: manifest.runId, cwd: manifest.cwd });
+	appendHookEvent(manifest, beforeRunReport);
+	if (beforeRunReport.outcome === "block") {
+		manifest = updateRunStatus(manifest, "blocked", beforeRunReport.reason ?? "before_run_start hook blocked the run.");
+		return { manifest, tasks: input.tasks };
+	}
 	let tasks = refreshTaskGraphQueues(input.tasks);
 	let queueIndex = buildTaskGraphIndex(tasks);
 	const canInjectAdaptivePlan = workflow.name === "implementation";
@@ -528,16 +573,28 @@ export async function executeTeamRun(input: ExecuteTeamRunInput): Promise<{ mani
 		manifest = updateRunStatus(manifest, "cancelled", "Plan approval was cancelled.");
 		return { manifest, tasks };
 	}
-	manifest = writeProgress(manifest, tasks, "team-runner");
+	manifest = writeProgress(manifest, tasks, "team-runner", input.executeWorkers, input.runtimeConfig);
 	await saveRunManifestAsync(manifest);
 	const runtimeKind = input.runtime?.kind ?? (input.executeWorkers ? "child-process" : "scaffold");
 	saveCrewAgents(manifest, recordsForMaterializedTasks(manifest, tasks, runtimeKind));
 
 	while (tasks.some((task) => task.status === "queued")) {
 		if (input.signal?.aborted) {
-			tasks = tasks.map((task) => task.status === "queued" || task.status === "running" || task.status === "waiting" ? { ...task, status: "cancelled", finishedAt: new Date().toISOString(), error: "Run cancelled." } : task);
+			const cancelReason = cancellationReasonFromSignal(input.signal);
+			const message = `${cancelReason.message} (${cancelReason.code})`;
+			const cancelledTaskIds: string[] = [];
+			tasks = tasks.map((task) => {
+				if (task.status !== "queued" && task.status !== "running" && task.status !== "waiting") return task;
+				cancelledTaskIds.push(task.id);
+				const base = { ...task, status: "cancelled" as const, finishedAt: new Date().toISOString(), error: message };
+				if (task.status === "running") {
+					return { ...base, terminalEvidence: [...(task.terminalEvidence ?? []), buildSyntheticTerminalEvidence("worker", cancelReason, task.startedAt)] };
+				}
+				return base;
+			});
 			await saveRunTasksAsync(manifest, tasks);
-			manifest = updateRunStatus(manifest, "cancelled", "Run cancelled.");
+			for (const taskId of cancelledTaskIds) appendEvent(manifest.eventsPath, { type: "task.cancelled", runId: manifest.runId, taskId, message, data: { reason: cancelReason.code } });
+			manifest = updateRunStatus(manifest, "cancelled", message, { data: { reason: cancelReason.code, cancelledTaskIds } });
 			return { manifest, tasks };
 		}
 
@@ -575,31 +632,44 @@ export async function executeTeamRun(input: ExecuteTeamRunInput): Promise<{ mani
 		}
 
 		appendEvent(manifest.eventsPath, { type: "task.progress", runId: manifest.runId, message: `Starting ready batch with ${readyBatch.length} task(s).`, data: { taskIds: readyBatch.map((task) => task.id), readyCount: snapshot.ready.length, blockedCount: snapshot.blocked.length, runningCount: snapshot.running.length, doneCount: snapshot.done.length, selectedCount: readyBatch.length, maxConcurrent: concurrency.maxConcurrent, defaultConcurrency: concurrency.defaultConcurrency, concurrencyReason: approvalPending ? `${concurrency.reason};plan-approval-read-only` : concurrency.reason } });
+		// Execute before_task_start hooks for the batch
+		for (const task of readyBatch) {
+			const taskReport = await executeHook("before_task_start", { runId: manifest.runId, taskId: task.id, cwd: manifest.cwd });
+			appendHookEvent(manifest, taskReport);
+			if (taskReport.outcome === "block") {
+				tasks = tasks.map((t) => t.id === task.id ? { ...t, status: "skipped" as const, error: taskReport.reason ?? "before_task_start hook blocked execution." } : t);
+				manifest = updateRunStatus(manifest, manifest.status, `Task '${task.id}' blocked by hook.`);
+			}
+		}
+		const batchTasks = readyBatch.filter((task) => tasks.find((t) => t.id === task.id && t.status !== "skipped"));
 		const results = await mapConcurrent(
-			readyBatch,
+			batchTasks,
 			concurrency.selectedCount,
 			async (task) => {
 				const step = findStep(workflow, task);
 				const agent = findAgent(input.agents, task);
-				const baseInput = { manifest, tasks, task, step, agent, signal: input.signal, executeWorkers: input.executeWorkers, runtimeKind: input.runtime?.kind, runtimeConfig: input.runtimeConfig, parentContext: input.parentContext, parentModel: input.parentModel, modelRegistry: input.modelRegistry, modelOverride: input.modelOverride, limits: input.limits, onJsonEvent: input.onJsonEvent };
+				const teamRole = input.team.roles.find((role) => role.name === task.role);
+				const baseInput = { manifest, tasks, task, step, agent, signal: input.signal, executeWorkers: input.executeWorkers, runtimeKind: input.runtime?.kind, runtimeConfig: input.runtimeConfig, parentContext: input.parentContext, parentModel: input.parentModel, modelRegistry: input.modelRegistry, modelOverride: input.modelOverride, teamRoleModel: teamRole?.model, teamRoleSkills: teamRole?.skills, skillOverride: input.skillOverride, limits: input.limits, onJsonEvent: input.onJsonEvent };
 				if (input.reliability?.autoRetry !== true) return withCorrelation(childCorrelation(manifest.runId, task.id), () => runTeamTask(baseInput));
 				let lastFailed: { manifest: TeamRunManifest; tasks: TeamTaskState[] } | undefined;
+				let lastAttemptId: string | undefined;
 				const attemptsSoFar: TaskAttemptState[] = [...(task.attempts ?? [])];
 				const policy = retryPolicyFromConfig(input.reliability);
 				try {
-					return await executeWithRetry(async (attempt) => {
+					return await executeWithRetry(async (attempt, info) => {
 						const startedAt = new Date().toISOString();
-						const inFlightAttempts: TaskAttemptState[] = [...attemptsSoFar, { startedAt }];
+						const inFlightAttempts: TaskAttemptState[] = [...attemptsSoFar, { attemptId: info.attemptId, startedAt }];
 						input.metricRegistry?.counter("crew.task.retry_attempt_total", "Retry attempts by run and task").inc({ runId: manifest.runId, taskId: task.id });
 						const fresh = loadRunManifestById(manifest.cwd, manifest.runId);
 						const freshManifest = fresh?.manifest ?? manifest;
 						const freshTasks = fresh?.tasks ?? tasks;
 						const freshTask = freshTasks.find((item) => item.id === task.id) ?? task;
+						if (freshTask.status !== "queued" && freshTask.status !== "running") return { manifest: freshManifest, tasks: freshTasks };
 						const taskWithAttempt: TeamTaskState = { ...freshTask, attempts: inFlightAttempts };
 						const result = await withCorrelation(childCorrelation(freshManifest.runId, task.id), () => runTeamTask({ ...baseInput, manifest: freshManifest, tasks: freshTasks, task: taskWithAttempt }));
 						const failed = failedTaskFrom(result, task.id);
 						const endedAt = new Date().toISOString();
-						const finishedAttempt: TaskAttemptState = { startedAt, endedAt, ...(failed?.error ? { error: failed.error } : {}) };
+						const finishedAttempt: TaskAttemptState = { attemptId: info.attemptId, startedAt, endedAt, ...(failed?.error ? { error: failed.error } : {}) };
 						attemptsSoFar.push(finishedAttempt);
 						const withAttempt = result.tasks.map((item) => item.id === task.id ? { ...item, attempts: [...attemptsSoFar] } : item);
 						const enriched = { manifest: result.manifest, tasks: withAttempt };
@@ -611,28 +681,54 @@ export async function executeTeamRun(input: ExecuteTeamRunInput): Promise<{ mani
 						return enriched;
 					}, policy, {
 						signal: input.signal,
-						onAttemptFailed: (attempt, error, delayMs) => {
-							appendEvent(manifest.eventsPath, { type: "crew.task.retry_attempt", runId: manifest.runId, taskId: task.id, message: error.message, data: { attempt, delayMs } });
+						attemptId: (attempt) => `${manifest.runId}:${task.id}:attempt-${attempt}`,
+						onAttemptFailed: (attempt, error, delayMs, info) => {
+							lastAttemptId = info.attemptId;
+							appendEvent(manifest.eventsPath, { type: "crew.task.retry_attempt", runId: manifest.runId, taskId: task.id, message: error.message, data: { attempt, attemptId: info.attemptId, delayMs }, metadata: { attemptId: info.attemptId } });
 							input.metricRegistry?.histogram("crew.task.retry_delay_ms", "Retry backoff delay, milliseconds").observe({ runId: manifest.runId, taskId: task.id }, delayMs);
 						},
-						onRetryGivenUp: (attempts, error) => {
-							appendDeadletter(manifest, { runId: manifest.runId, taskId: task.id, reason: "max-retries", attempts, lastError: error.message, timestamp: new Date().toISOString() });
+						onRetryGivenUp: (attempts, error, info) => {
+							lastAttemptId = info.attemptId;
+							appendDeadletter(manifest, { runId: manifest.runId, taskId: task.id, reason: "max-retries", attempts, attemptId: info.attemptId, lastError: error.message, timestamp: new Date().toISOString() });
 							input.metricRegistry?.counter("crew.task.deadletter_total", "Deadletter triggers by reason").inc({ reason: "max-retries" });
 							input.metricRegistry?.histogram("crew.task.retry_count", "Retries per task", [0, 1, 2, 3, 5, 10]).observe({ runId: manifest.runId, team: input.team.name }, Math.max(0, attempts - 1));
 						},
 					});
-				} catch {
+				} catch (retryError) {
+					if (retryError instanceof CrewCancellationError || input.signal?.aborted) {
+						const reason = retryError instanceof CrewCancellationError ? retryError.reason : cancellationReasonFromSignal(input.signal);
+						const fresh = loadRunManifestById(manifest.cwd, manifest.runId);
+						const freshManifest = fresh?.manifest ?? manifest;
+						const freshTasks = fresh?.tasks ?? tasks;
+						const cancelledTasks = freshTasks.map((item) => item.id === task.id && (item.status === "queued" || item.status === "running") ? { ...item, status: "cancelled" as const, finishedAt: new Date().toISOString(), error: `${reason.message} (${reason.code})` } : item);
+						appendEvent(freshManifest.eventsPath, { type: "task.cancelled", runId: freshManifest.runId, taskId: task.id, message: reason.message, data: { reason, phase: "retry" }, metadata: lastAttemptId ? { attemptId: lastAttemptId } : undefined });
+						return { manifest: updateRunStatus(freshManifest, "cancelled", reason.message), tasks: cancelledTasks };
+					}
 					if (lastFailed) return lastFailed;
 					const fresh = loadRunManifestById(manifest.cwd, manifest.runId);
 					const freshManifest = fresh?.manifest ?? manifest;
 					const freshTasks = fresh?.tasks ?? tasks;
 					const freshTask = freshTasks.find((item) => item.id === task.id) ?? task;
+					if (freshTask.status !== "queued" && freshTask.status !== "running") return { manifest: freshManifest, tasks: freshTasks };
 					return withCorrelation(childCorrelation(freshManifest.runId, task.id), () => runTeamTask({ ...baseInput, manifest: freshManifest, tasks: freshTasks, task: freshTask }));
 				}
 			},
 		);
+		if (results.length === 0) break;
 		manifest = { ...results.at(-1)!.manifest, artifacts: mergeArtifacts([manifest.artifacts, ...results.map((item) => item.manifest.artifacts)].flat()) };
 		tasks = __test__mergeTaskUpdates(tasks, results);
+		const cancelledResult = results.find((item) => item.manifest.status === "cancelled");
+		if (cancelledResult || input.signal?.aborted) {
+			const reason = input.signal?.aborted ? cancellationReasonFromSignal(input.signal) : undefined;
+			const message = reason?.message ?? cancelledResult?.manifest.summary ?? "Run cancelled during task execution.";
+			manifest = { ...manifest, status: "running" };
+			manifest = updateRunStatus(manifest, "cancelled", message);
+			await saveRunTasksAsync(manifest, tasks);
+			saveCrewAgents(manifest, recordsForMaterializedTasks(manifest, tasks, runtimeKind));
+			await saveRunManifestAsync(manifest);
+			appendEvent(manifest.eventsPath, { type: "run.cancelled", runId: manifest.runId, message, data: { reason, phase: "task-batch", cancelledResultRunId: cancelledResult?.manifest.runId } });
+			return { manifest, tasks };
+		}
 		queueIndex = buildTaskGraphIndex(tasks);
 		const injectedAfterBatch = attemptAdaptivePlan();
 		if (injectedAfterBatch.missing) {
@@ -657,30 +753,46 @@ export async function executeTeamRun(input: ExecuteTeamRunInput): Promise<{ mani
 		}
 		await saveRunTasksAsync(manifest, tasks);
 		saveCrewAgents(manifest, recordsForMaterializedTasks(manifest, tasks, runtimeKind));
-		const completedBatch = readyBatch.map((task) => tasks.find((item) => item.id === task.id) ?? task);
+		const completedBatch = batchTasks.map((task) => tasks.find((item) => item.id === task.id) ?? task);
 		const batchArtifact = writeArtifact(manifest.artifactsRoot, {
 			kind: "summary",
-			relativePath: `batches/${readyBatch.map((task) => task.id).join("+")}.md`,
+			relativePath: `batches/${batchTasks.map((task) => task.id).join("+")}.md`,
 			producer: "team-runner",
 			content: aggregateTaskOutputs(completedBatch, manifest),
 		});
-		const groupDelivery = deliverGroupJoin({ manifest, mode: resolveGroupJoinMode(input.runtimeConfig), batch: readyBatch, allTasks: tasks });
+		const groupDelivery = deliverGroupJoin({ manifest, mode: resolveGroupJoinMode(input.runtimeConfig), batch: batchTasks, allTasks: tasks });
 		manifest = { ...manifest, artifacts: mergeArtifacts([...manifest.artifacts, batchArtifact, ...(groupDelivery?.artifact ? [groupDelivery.artifact] : [])]) };
-		manifest = writeProgress(manifest, tasks, "team-runner");
+		manifest = writeProgress(manifest, tasks, "team-runner", input.executeWorkers, input.runtimeConfig);
 		await saveRunManifestAsync(manifest);
 	}
 
 	const failed = tasks.find((task) => task.status === "failed");
+	const waiting = tasks.find((task) => task.status === "waiting");
+	const running = tasks.find((task) => task.status === "running");
 	manifest = applyPolicy(manifest, tasks, input.limits);
+	const effectiveness = evaluateRunEffectiveness({ manifest, tasks, executeWorkers: input.executeWorkers, runtimeConfig: input.runtimeConfig });
+	const effectivenessDecision = effectivenessPolicyDecision(effectiveness);
+	if (effectivenessDecision) {
+		manifest = { ...manifest, policyDecisions: [...(manifest.policyDecisions ?? []), effectivenessDecision], updatedAt: new Date().toISOString() };
+		appendEvent(manifest.eventsPath, { type: "run.effectiveness", runId: manifest.runId, message: effectivenessDecision.message, data: { effectiveness, policyDecision: effectivenessDecision } });
+	}
 	const blockingDecision = manifest.policyDecisions?.find((item) => item.action === "block" || item.action === "escalate");
 	if (failed) {
 		manifest = updateRunStatus(manifest, "failed", `Failed at task '${failed.id}'.`);
+	} else if (waiting) {
+		manifest = updateRunStatus(manifest, "blocked", `Waiting for response to task '${waiting.id}'.`);
+	} else if (running) {
+		manifest = updateRunStatus(manifest, "blocked", `Task '${running.id}' is still running.`);
+	} else if (effectiveness.severity === "failed") {
+		manifest = updateRunStatus(manifest, "failed", effectivenessDecision?.message ?? "Run effectiveness guard failed.");
+	} else if (effectiveness.severity === "blocked") {
+		manifest = updateRunStatus(manifest, "blocked", effectivenessDecision?.message ?? "Run effectiveness guard blocked completion.");
 	} else if (blockingDecision) {
 		manifest = updateRunStatus(manifest, "blocked", blockingDecision.message);
 	} else {
 		manifest = updateRunStatus(manifest, "completed", input.executeWorkers ? "Team workflow completed." : "Team workflow scaffold completed without launching child workers.");
 	}
-	manifest = writeProgress(manifest, tasks, "team-runner");
+	manifest = writeProgress(manifest, tasks, "team-runner", input.executeWorkers, input.runtimeConfig);
 	await saveRunManifestAsync(manifest);
 	const usage = aggregateUsage(tasks);
 	const summaryArtifact = writeArtifact(manifest.artifactsRoot, {
@@ -699,6 +811,9 @@ export async function executeTeamRun(input: ExecuteTeamRunInput): Promise<{ mani
 			"## Tasks",
 			...tasks.map(formatTaskProgress),
 			"",
+			"## Effectiveness",
+			...runEffectivenessLines(manifest, tasks, input.executeWorkers, input.runtimeConfig),
+			"",
 			"## Policy decisions",
 			...(manifest.policyDecisions?.length ? summarizePolicyDecisions(manifest.policyDecisions) : ["- (none)"]),
 			"",

package/src/runtime/workspace-tree.ts

@@ -0,0 +1,298 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+
+// ── Public types ───────────────────────────────────────────────────────
+
+export interface WorkspaceTree {
+	rootPath: string;
+	rendered: string;
+	truncated: boolean;
+	totalLines: number;
+}
+
+export interface WorkspaceTreeOptions {
+	/** Directory depth below root. Root is depth 0. Default: 3 */
+	maxDepth?: number;
+	/** Max entries per directory. Default: 12 */
+	dirLimit?: number;
+	/** Hard line limit for the rendered output. Default: 120 */
+	lineCap?: number;
+	/** Directory names to skip entirely. Default: node_modules, .git, .next, dist, build, target, .venv, .cache, .turbo */
+	excludedDirs?: Set<string>;
+}
+
+// ── Defaults ───────────────────────────────────────────────────────────
+
+const DEFAULT_MAX_DEPTH = 3;
+const DEFAULT_DIR_LIMIT = 12;
+const DEFAULT_LINE_CAP = 120;
+const DEFAULT_EXCLUDED_DIRS: ReadonlySet<string> = new Set([
+	"node_modules",
+	".git",
+	".next",
+	"dist",
+	"build",
+	"target",
+	".venv",
+	".cache",
+	".turbo",
+]);
+
+// ── Internal types ─────────────────────────────────────────────────────
+
+interface TreeNode {
+	name: string;
+	relativePath: string;
+	depth: number;
+	isDirectory: boolean;
+	mtimeMs: number;
+	size: number;
+	children: TreeNode[];
+	droppedChildCount: number;
+}
+
+interface RenderLine {
+	text: string;
+	depth: number;
+	isRoot: boolean;
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────
+
+export function formatBytes(bytes: number): string {
+	if (bytes < 1024) return `${bytes}B`;
+	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+	if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+	return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)}GB`;
+}
+
+export function formatAge(seconds: number): string {
+	if (seconds < 60) return "just now";
+	if (seconds < 3600) return `${Math.floor(seconds / 60)}m`;
+	if (seconds < 86400) return `${Math.floor(seconds / 3600)}h`;
+	if (seconds < 86400 * 14) return `${Math.floor(seconds / 86400)}d`;
+	return `${Math.floor(seconds / (86400 * 7))}w`;
+}
+
+// ── Tree building ──────────────────────────────────────────────────────
+
+function compareByRecency(a: TreeNode, b: TreeNode): number {
+	const diff = b.mtimeMs - a.mtimeMs;
+	if (diff !== 0) return diff;
+	return a.name.localeCompare(b.name);
+}
+
+function applyDirLimit(
+	children: TreeNode[],
+	limit: number,
+): { visible: TreeNode[]; dropped: number } {
+	if (children.length <= limit) {
+		return { visible: children, dropped: 0 };
+	}
+	if (limit <= 1) {
+		return { visible: children.slice(0, limit), dropped: children.length - limit };
+	}
+	// Keep first (limit-1) by recency + always keep the oldest (last after sort)
+	const recent = children.slice(0, limit - 1);
+	const oldest = children[children.length - 1];
+	const visible = oldest ? [...recent, oldest] : recent;
+	return { visible, dropped: children.length - limit };
+}
+
+async function readChildren(
+	rootPath: string,
+	parent: TreeNode,
+	excludedDirs: ReadonlySet<string>,
+): Promise<TreeNode[]> {
+	const dirPath = parent.relativePath
+		? path.join(rootPath, parent.relativePath)
+		: rootPath;
+
+	let names: string[];
+	try {
+		names = await fs.readdir(dirPath);
+	} catch {
+		return [];
+	}
+
+	const nodes = await Promise.all(
+		names.map(async (name): Promise<TreeNode | null> => {
+			// Skip hidden entries
+			if (name.startsWith(".")) return null;
+			const relativePath = parent.relativePath
+				? `${parent.relativePath}/${name}`
+				: name;
+			const absolutePath = path.join(rootPath, relativePath);
+			try {
+				const stat = await fs.stat(absolutePath);
+				if (stat.isDirectory() && excludedDirs.has(name)) return null;
+				return {
+					name,
+					relativePath,
+					depth: parent.depth + 1,
+					isDirectory: stat.isDirectory(),
+					mtimeMs: stat.mtimeMs,
+					size: stat.size,
+					children: [],
+					droppedChildCount: 0,
+				};
+			} catch {
+				return null;
+			}
+		}),
+	);
+
+	return nodes.filter((n): n is TreeNode => n !== null).sort(compareByRecency);
+}
+
+async function collectTree(
+	rootPath: string,
+	maxDepth: number,
+	dirLimit: number,
+	excludedDirs: ReadonlySet<string>,
+): Promise<{ root: TreeNode; truncated: boolean }> {
+	const rootStat = await fs.stat(rootPath);
+	const root: TreeNode = {
+		name: ".",
+		relativePath: "",
+		depth: 0,
+		isDirectory: true,
+		mtimeMs: rootStat.mtimeMs,
+		size: rootStat.size,
+		children: [],
+		droppedChildCount: 0,
+	};
+
+	let truncated = false;
+	const queue: TreeNode[] = [root];
+	let cursor = 0;
+
+	while (cursor < queue.length) {
+		const parent = queue[cursor];
+		cursor += 1;
+		if (!parent || parent.depth >= maxDepth) continue;
+
+		const children = await readChildren(rootPath, parent, excludedDirs);
+		const { visible, dropped } = applyDirLimit(children, dirLimit);
+		parent.children = visible;
+		parent.droppedChildCount = dropped;
+		if (dropped > 0) truncated = true;
+
+		for (const child of visible) {
+			if (child.isDirectory) queue.push(child);
+		}
+	}
+
+	return { root, truncated };
+}
+
+// ── Rendering ──────────────────────────────────────────────────────────
+
+function collectLines(node: TreeNode, nowMs: number, lines: RenderLine[]): void {
+	if (node.depth === 0) {
+		lines.push({ text: ".", depth: 0, isRoot: true });
+	} else {
+		const indent = "  ".repeat(node.depth);
+		const suffix = node.isDirectory ? "/" : "";
+		const label = `${indent}- ${node.name}${suffix}`;
+		if (node.isDirectory) {
+			lines.push({ text: label, depth: node.depth, isRoot: false });
+		} else {
+			const ageSeconds = Math.max(0, Math.floor((nowMs - node.mtimeMs) / 1000));
+			const size = formatBytes(node.size);
+			const age = formatAge(ageSeconds);
+			lines.push({ text: `${label}  ${size}  ${age}`, depth: node.depth, isRoot: false });
+		}
+	}
+
+	if (node.droppedChildCount > 0) {
+		// When we kept recent + oldest, render recent children, then truncation line, then oldest
+		const recentChildren = node.children.slice(0, -1);
+		const oldestChild = node.children[node.children.length - 1];
+		for (const child of recentChildren) collectLines(child, nowMs, lines);
+
+		const childDepth = node.depth + 1;
+		const indent = "  ".repeat(childDepth);
+		lines.push({
+			text: `${indent}- … ${node.droppedChildCount} more`,
+			depth: childDepth,
+			isRoot: false,
+		});
+
+		if (oldestChild) collectLines(oldestChild, nowMs, lines);
+	} else {
+		for (const child of node.children) collectLines(child, nowMs, lines);
+	}
+}
+
+function applyLineCap(
+	lines: RenderLine[],
+	cap: number,
+): { lines: RenderLine[]; elided: number } {
+	if (lines.length <= cap) return { lines, elided: 0 };
+
+	const target = Math.max(1, cap - 1);
+	const removeCount = lines.length - target;
+	// Remove deepest non-root entries first
+	const removable = lines
+		.map((line, index) => ({ line, index }))
+		.filter((item) => !item.line.isRoot)
+		.sort((a, b) => b.line.depth - a.line.depth || b.index - a.index)
+		.slice(0, removeCount);
+
+	if (removable.length === 0) return { lines, elided: 0 };
+
+	const removedIndexes = new Set(removable.map((item) => item.index));
+	const kept = lines.filter((_, index) => !removedIndexes.has(index));
+	kept.push({
+		text: `… (${removable.length} lines elided)`,
+		depth: 0,
+		isRoot: false,
+	});
+	return { lines: kept, elided: removable.length };
+}
+
+// ── Public API ─────────────────────────────────────────────────────────
+
+const emptyResult = (rootPath: string): WorkspaceTree => ({
+	rootPath,
+	rendered: "",
+	truncated: false,
+	totalLines: 0,
+});
+
+export async function buildWorkspaceTree(
+	cwd: string,
+	options?: WorkspaceTreeOptions,
+): Promise<WorkspaceTree> {
+	const rootPath = path.resolve(cwd);
+	try {
+		const maxDepth = options?.maxDepth ?? DEFAULT_MAX_DEPTH;
+		const dirLimit = options?.dirLimit ?? DEFAULT_DIR_LIMIT;
+		const lineCap = options?.lineCap ?? DEFAULT_LINE_CAP;
+		const excludedDirs = options?.excludedDirs ?? DEFAULT_EXCLUDED_DIRS;
+
+		const { root, truncated: dirTruncated } = await collectTree(
+			rootPath,
+			maxDepth,
+			dirLimit,
+			excludedDirs,
+		);
+
+		const nowMs = Date.now();
+		const lines: RenderLine[] = [];
+		collectLines(root, nowMs, lines);
+
+		const { lines: capped, elided } = applyLineCap(lines, lineCap);
+		const rendered = capped.map((l) => l.text).join("\n");
+
+		return {
+			rootPath,
+			rendered,
+			truncated: dirTruncated || elided > 0,
+			totalLines: capped.length,
+		};
+	} catch {
+		return emptyResult(rootPath);
+	}
+}