pi-crew 0.2.3 → 0.2.5

package/src/extension/team-tool/context.ts

@@ -1,60 +1,60 @@
-import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
-import type { PiTeamsConfig } from "../../config/config.ts";
-import type { MetricRegistry } from "../../observability/metric-registry.ts";
-import type { TeamToolDetails } from "../team-tool-types.ts";
-import { toolResult, type PiTeamsToolResult } from "../tool-result.ts";
-
-export type TeamContext = Pick<ExtensionContext, "cwd"> & Partial<Pick<ExtensionContext, "model">> & {
-	sessionId?: string;
-	modelRegistry?: unknown;
-	sessionManager?: { getBranch?: () => unknown[] };
-	events?: { emit?: (event: string, data: unknown) => void };
-	metricRegistry?: MetricRegistry;
-	signal?: AbortSignal;
-	startForegroundRun?: (runner: (signal?: AbortSignal) => Promise<void>, runId?: string) => void;
-	abortForegroundRun?: (runId: string) => boolean;
-	onRunStarted?: (runId: string) => void;
-	onJsonEvent?: (taskId: string, runId: string, event: unknown) => void;
-	config?: PiTeamsConfig;
-};
-
-export function withSessionId<T extends Pick<ExtensionContext, "sessionManager">>(ctx: T): T & { sessionId?: string } {
-	const sessionId = ctx.sessionManager?.getSessionId?.();
-	return sessionId ? { ...ctx, sessionId } : { ...ctx };
-}
-
-export function result(text: string, details: TeamToolDetails, isError = false): PiTeamsToolResult {
-	return toolResult(text, details, isError);
-}
-
-export function formatScoped(name: string, source: string, description: string): string {
-	return `- ${name} (${source}): ${description}`;
-}
-
-function extractTextContent(content: unknown): string {
-	if (typeof content === "string") return content;
-	if (!Array.isArray(content)) return "";
-	return content.map((part) => part && typeof part === "object" && !Array.isArray(part) && typeof (part as { text?: unknown }).text === "string" ? (part as { text: string }).text : "").filter(Boolean).join("\n");
-}
-
-export function buildParentContext(ctx: TeamContext): string | undefined {
-	const branch = ctx.sessionManager?.getBranch?.();
-	if (!Array.isArray(branch) || branch.length === 0) return undefined;
-	const parts: string[] = [];
-	for (const entry of branch.slice(-20)) {
-		if (!entry || typeof entry !== "object" || Array.isArray(entry)) continue;
-		const record = entry as { type?: unknown; message?: unknown; summary?: unknown };
-		if (record.type === "compaction" && typeof record.summary === "string") parts.push(`[Summary]: ${record.summary}`);
-		const message = record.message && typeof record.message === "object" && !Array.isArray(record.message) ? record.message as { role?: unknown; content?: unknown } : undefined;
-		if (!message || (message.role !== "user" && message.role !== "assistant")) continue;
-		const text = extractTextContent(message.content).trim();
-		if (text) parts.push(`[${message.role === "user" ? "User" : "Assistant"}]: ${text}`);
-	}
-	if (!parts.length) return undefined;
-	return [`# Parent Conversation Context`, "The following context was inherited from the parent Pi session. Treat it as reference-only.", "", parts.join("\n\n")].join("\n");
-}
-
-export function configRecord(config: unknown): Record<string, unknown> {
-	if (!config || typeof config !== "object" || Array.isArray(config)) return {};
-	return config as Record<string, unknown>;
-}
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { PiTeamsConfig } from "../../config/config.ts";
+import type { MetricRegistry } from "../../observability/metric-registry.ts";
+import type { TeamToolDetails } from "../team-tool-types.ts";
+import { toolResult, type PiTeamsToolResult } from "../tool-result.ts";
+
+export type TeamContext = Pick<ExtensionContext, "cwd"> & Partial<Pick<ExtensionContext, "model">> & {
+	sessionId?: string;
+	modelRegistry?: unknown;
+	sessionManager?: { getBranch?: () => unknown[] };
+	events?: { emit?: (event: string, data: unknown) => void };
+	metricRegistry?: MetricRegistry;
+	signal?: AbortSignal;
+	startForegroundRun?: (runner: (signal?: AbortSignal) => Promise<void>, runId?: string) => void;
+	abortForegroundRun?: (runId: string) => boolean;
+	onRunStarted?: (runId: string) => void;
+	onJsonEvent?: (taskId: string, runId: string, event: unknown) => void;
+	config?: PiTeamsConfig;
+};
+
+export function withSessionId<T extends Pick<ExtensionContext, "sessionManager">>(ctx: T): T & { sessionId?: string } {
+	const sessionId = ctx.sessionManager?.getSessionId?.();
+	return sessionId ? { ...ctx, sessionId } : { ...ctx };
+}
+
+export function result(text: string, details: TeamToolDetails, isError = false): PiTeamsToolResult {
+	return toolResult(text, details, isError);
+}
+
+export function formatScoped(name: string, source: string, description: string): string {
+	return `- ${name} (${source}): ${description}`;
+}
+
+function extractTextContent(content: unknown): string {
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+	return content.map((part) => part && typeof part === "object" && !Array.isArray(part) && typeof (part as { text?: unknown }).text === "string" ? (part as { text: string }).text : "").filter(Boolean).join("\n");
+}
+
+export function buildParentContext(ctx: TeamContext): string | undefined {
+	const branch = ctx.sessionManager?.getBranch?.();
+	if (!Array.isArray(branch) || branch.length === 0) return undefined;
+	const parts: string[] = [];
+	for (const entry of branch.slice(-20)) {
+		if (!entry || typeof entry !== "object" || Array.isArray(entry)) continue;
+		const record = entry as { type?: unknown; message?: unknown; summary?: unknown };
+		if (record.type === "compaction" && typeof record.summary === "string") parts.push(`[Summary]: ${record.summary}`);
+		const message = record.message && typeof record.message === "object" && !Array.isArray(record.message) ? record.message as { role?: unknown; content?: unknown } : undefined;
+		if (!message || (message.role !== "user" && message.role !== "assistant")) continue;
+		const text = extractTextContent(message.content).trim();
+		if (text) parts.push(`[${message.role === "user" ? "User" : "Assistant"}]: ${text}`);
+	}
+	if (!parts.length) return undefined;
+	return [`# Parent Conversation Context`, "The following context was inherited from the parent Pi session. Treat it as reference-only.", "", parts.join("\n\n")].join("\n");
+}
+
+export function configRecord(config: unknown): Record<string, unknown> {
+	if (!config || typeof config !== "object" || Array.isArray(config)) return {};
+	return config as Record<string, unknown>;
+}

package/src/extension/team-tool/doctor.ts

@@ -1,242 +1,242 @@
-import { execFileSync, spawnSync } from "node:child_process";
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { allAgents, discoverAgents } from "../../agents/discover-agents.ts";
-import { allTeams, discoverTeams } from "../../teams/discover-teams.ts";
-import { allWorkflows, discoverWorkflows } from "../../workflows/discover-workflows.ts";
-import { loadConfig } from "../../config/config.ts";
-import { projectCrewRoot, userCrewRoot } from "../../utils/paths.ts";
-import { DEFAULT_PATHS } from "../../config/defaults.ts";
-import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
-import { getPiSpawnCommand } from "../../runtime/pi-spawn.ts";
-import { validateResources } from "../validate-resources.ts";
-import { detectDrift, formatDriftReport, type DriftReport } from "../../config/drift-detector.ts";
-import { TeamToolParams } from "../../schema/team-tool-schema.ts";
-import type { PiTeamsToolResult } from "../tool-result.ts";
-import { configRecord, result, type TeamContext } from "./context.ts";
-
-interface DoctorCheck {
-	label: string;
-	ok: boolean;
-	detail: string;
-}
-
-function firstOutputLine(stdout: string | null | undefined, stderr: string | null | undefined): string {
-	const output = `${stdout ?? ""}\n${stderr ?? ""}`.trim();
-	return output.split(/\r?\n/).find((line) => line.trim().length > 0)?.trim() ?? "available";
-}
-
-function commandExists(command: string, args: string[]): { ok: boolean; detail: string } {
-	try {
-		const output = spawnSync(command, args, { encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] });
-		if (output.error) {
-			return { ok: false, detail: output.error.message };
-		}
-		if (output.status !== 0) {
-			return { ok: false, detail: firstOutputLine(output.stdout, output.stderr) || `status ${output.status}` };
-		}
-		return { ok: true, detail: firstOutputLine(output.stdout, output.stderr) };
-	} catch (error) {
-		return { ok: false, detail: error instanceof Error ? error.message : String(error) };
-	}
-}
-
-function piCommandExists(): { ok: boolean; detail: string } {
-	const spec = getPiSpawnCommand(["--version"]);
-	const output = commandExists(spec.command, spec.args);
-	if (!output.ok) return output;
-	const executable = spec.command === "pi" ? "pi" : `${spec.command} ${spec.args[0] ?? ""}`.trim();
-	return { ok: true, detail: `${output.detail} (${executable})` };
-}
-
-function checkWritableDir(dir: string): { ok: boolean; detail: string } {
-	try {
-		if (!fs.existsSync(dir)) return { ok: false, detail: `${dir}: missing` };
-		if (!fs.statSync(dir).isDirectory()) return { ok: false, detail: `${dir}: not a directory` };
-		// fs.accessSync(W_OK) is unreliable on Windows; verify by writing a temp file.
-		const probePath = `${dir}/.pi-crew-write-test`;
-		try {
-			fs.writeFileSync(probePath, "ok", "utf-8");
-			fs.rmSync(probePath, { force: true });
-		} catch {
-			return { ok: false, detail: `${dir}: not writable (write test failed)` };
-		}
-		return { ok: true, detail: dir };
-	} catch (error) {
-		const message = error instanceof Error ? error.message : String(error);
-		return { ok: false, detail: `${dir}: ${message}` };
-	}
-}
-
-function auditJsonSchema(schema: unknown): string[] {
-	const issues: string[] = [];
-	const walk = (node: unknown): void => {
-		if (!node || typeof node !== "object" || Array.isArray(node)) return;
-		const record = node as Record<string, unknown>;
-		if (Array.isArray(record.type)) issues.push("schema node uses array-valued type");
-		if (record.description && !record.type && !record.anyOf && !record.oneOf && !record.allOf && !record.properties) issues.push(`description-only schema node: ${record.description}`);
-		if (record.type === "array" && !record.items) issues.push("array schema missing items");
-		if (record.type && (record.anyOf || record.oneOf)) issues.push("schema node combines type with union keyword");
-		for (const value of Object.values(record)) {
-			if (Array.isArray(value)) for (const item of value) walk(item);
-			else walk(value);
-		}
-	};
-	walk(schema);
-	return issues;
-}
-
-function makeLine(check: DoctorCheck): string {
-	return `- ${check.ok ? "OK" : "FAIL"} ${check.label}: ${check.detail}`;
-}
-
-function section(title: string, checks: () => DoctorCheck[]): string[] {
-	try {
-		return [title, ...checks().map(makeLine)];
-	} catch (error) {
-		const detail = error instanceof Error ? error.message : String(error);
-		return [title, `- FAIL ${title}: ${detail}`];
-	}
-}
-
-export interface TeamDoctorReportInput {
-	cwd: string;
-	configPath: string;
-	configErrors: string[];
-	configWarnings: string[];
-	model?: { provider: string; id: string };
-	validationErrors: number;
-	validationWarnings: number;
-	smokeChildPi?: { ok: boolean; detail: string };
-}
-
-export interface TeamDoctorReport {
-	text: string;
-	hasErrors: boolean;
-	drift?: DriftReport;
-}
-
-export function buildTeamDoctorReport(input: TeamDoctorReportInput): TeamDoctorReport {
-	// Compute drift once — reused in both Drift section and return value
-	const driftResult = detectDrift(
-		{
-			agents: allAgents(discoverAgents(input.cwd)).map((a) => a.name),
-			teams: allTeams(discoverTeams(input.cwd)).map((t) => t.name),
-			workflows: allWorkflows(discoverWorkflows(input.cwd)).map((w) => w.name),
-		},
-		loadConfig(input.cwd).config,
-	);
-	const sections = [
-		section("Runtime", () => {
-			const git = commandExists("git", ["--version"]);
-			const pi = piCommandExists();
-			return [
-				{ label: "cwd", ok: true, detail: input.cwd },
-				{ label: "platform", ok: true, detail: `${process.platform}/${process.arch} node=${process.version}` },
-				{ label: "pi command", ok: pi.ok, detail: pi.detail },
-				{ label: "git command", ok: git.ok, detail: git.detail },
-				{ label: "config", ok: input.configErrors.length === 0, detail: `${input.configPath} (${input.configErrors.length} errors)` },
-				{ label: "model", ok: true, detail: input.model ? `${input.model.provider}/${input.model.id}` : "not available in this context" },
-				{ label: "config warnings", ok: true, detail: `${input.configWarnings.length} warnings` },
-			];
-		}),
-		section("Filesystem", () => {
-			const userWritable = checkWritableDir(userCrewRoot());
-			const projectWritable = checkWritableDir(projectCrewRoot(input.cwd));
-			return [
-				{ label: "user state", ok: userWritable.ok || userWritable.detail.endsWith(": missing"), detail: userWritable.detail },
-				{ label: "project state", ok: projectWritable.ok || projectWritable.detail.endsWith(": missing"), detail: projectWritable.detail },
-				{ label: "project state root", ok: true, detail: path.join(projectCrewRoot(input.cwd), DEFAULT_PATHS.state.runsSubdir) },
-				{ label: "artifacts root", ok: true, detail: path.join(projectCrewRoot(input.cwd), DEFAULT_PATHS.state.artifactsSubdir) },
-			];
-		}),
-		section("Discovery", () => {
-			const discoveredAgents = allAgents(discoverAgents(input.cwd));
-			const discoveredTeams = allTeams(discoverTeams(input.cwd));
-			const discoveredWorkflows = allWorkflows(discoverWorkflows(input.cwd));
-			const agentModelHints = discoveredAgents.filter((agent) => agent.model || agent.fallbackModels?.length).length;
-			return [
-				{ label: "agents", ok: true, detail: `${discoveredAgents.length} discovered` },
-				{ label: "teams", ok: true, detail: `${discoveredTeams.length} discovered` },
-				{ label: "workflows", ok: true, detail: `${discoveredWorkflows.length} discovered` },
-				{ label: "resource model hints", ok: true, detail: `${agentModelHints} agents declare model/fallback preferences` },
-			];
-		}),
-		section("Resource validation", () => [{
-			label: "resource validation",
-			ok: input.validationErrors === 0,
-			detail: `${input.validationErrors} errors, ${input.validationWarnings} warnings`,
-		}]),
-		section("Drift", () => {
-			const driftErrors = driftResult.items.filter((item) => item.severity === "error").length;
-			const driftWarnings = driftResult.items.filter((item) => item.severity === "warning").length;
-			return [{
-				label: "config drift",
-				ok: !driftResult.hasDrift || driftErrors === 0,
-				detail: driftResult.hasDrift ? `${driftErrors} errors, ${driftWarnings} warnings` : "no drift detected",
-			}];
-		}),
-		section("Schema", () => {
-			const schemaIssues = auditJsonSchema(TeamToolParams);
-			return [{ label: "strict-provider schema", ok: schemaIssues.length === 0, detail: schemaIssues.length ? schemaIssues.slice(0, 3).join("; ") : "team tool schema compatible" }];
-		}),
-		section("Async/result delivery", () => [
-			{ label: "result watcher", ok: true, detail: "fs.watch with polling fallback for EMFILE/ENOSPC/EPERM" },
-			{ label: "async notifier", ok: true, detail: "session-stale guarded completion notifications enabled" },
-		]),
-		section("Worktrees", () => [
-			{ label: "leader repository", ok: true, detail: input.cwd },
-			{ label: "cleanup policy", ok: true, detail: "dirty worktrees preserved unless force is set" },
-		]),
-	];
-	if (input.smokeChildPi) {
-		sections.push([`Child check`, `- ${input.smokeChildPi.ok ? "OK" : "FAIL"} child Pi smoke: ${input.smokeChildPi.detail}`]);
-	}
-	const lines = ["pi-crew doctor report"];
-	for (const block of sections) {
-		if (block.length > 0) {
-			lines.push(...block);
-			lines.push("");
-		}
-	}
-	if (lines.at(-1) === "") lines.pop();
-	const text = lines.join("\n");
-	return { text, hasErrors: sections.some((sectionLines) => sectionLines.some((line) => line.includes("FAIL"))), drift: driftResult.hasDrift ? driftResult : undefined };
-}
-
-export function handleDoctor(ctx: TeamContext, params: TeamToolParamsValue = {}): PiTeamsToolResult {
-	const loadedConfig = loadConfig(ctx.cwd);
-	let smokeChildPi: { ok: boolean; detail: string } | undefined;
-	if (configRecord(params.config).smokeChildPi === true) {
-		try {
-			const spec = getPiSpawnCommand(["--mode", "json", "-p", "Reply with exactly PI-TEAMS-SMOKE-OK"]);
-			const output = execFileSync(spec.command, spec.args, {
-				cwd: ctx.cwd,
-				encoding: "utf-8",
-				stdio: ["ignore", "pipe", "pipe"],
-				timeout: 15_000,
-			}).trim();
-			smokeChildPi = { ok: output.includes("PI-TEAMS-SMOKE-OK"), detail: output.split("\n").slice(-1)[0] ?? "completed" };
-		} catch (error) {
-			const message = error instanceof Error ? error.message : String(error);
-			smokeChildPi = { ok: false, detail: message };
-		}
-	}
-	const validation = validateResources(ctx.cwd);
-	const { text, hasErrors, drift } = buildTeamDoctorReport({
-		cwd: ctx.cwd,
-		configPath: loadedConfig.path,
-		configErrors: loadedConfig.error ? [loadedConfig.error] : [],
-		configWarnings: loadedConfig.warnings ?? [],
-		model: ctx.model,
-		validationErrors: validation.issues.filter((issue) => issue.level === "error").length,
-		validationWarnings: validation.issues.filter((issue) => issue.level === "warning").length,
-		smokeChildPi,
-	});
-	// Append detailed drift section if any drift was detected
-	let finalText = text;
-	if (drift?.hasDrift) {
-		finalText = `${text}\n\nDrift details:\n${formatDriftReport(drift)}`;
-	}
-	return result(finalText, { action: "doctor", status: hasErrors ? "error" : "ok" }, hasErrors);
-}
+import { execFileSync, spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { allAgents, discoverAgents } from "../../agents/discover-agents.ts";
+import { allTeams, discoverTeams } from "../../teams/discover-teams.ts";
+import { allWorkflows, discoverWorkflows } from "../../workflows/discover-workflows.ts";
+import { loadConfig } from "../../config/config.ts";
+import { projectCrewRoot, userCrewRoot } from "../../utils/paths.ts";
+import { DEFAULT_PATHS } from "../../config/defaults.ts";
+import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
+import { getPiSpawnCommand } from "../../runtime/pi-spawn.ts";
+import { validateResources } from "../validate-resources.ts";
+import { detectDrift, formatDriftReport, type DriftReport } from "../../config/drift-detector.ts";
+import { TeamToolParams } from "../../schema/team-tool-schema.ts";
+import type { PiTeamsToolResult } from "../tool-result.ts";
+import { configRecord, result, type TeamContext } from "./context.ts";
+
+interface DoctorCheck {
+	label: string;
+	ok: boolean;
+	detail: string;
+}
+
+function firstOutputLine(stdout: string | null | undefined, stderr: string | null | undefined): string {
+	const output = `${stdout ?? ""}\n${stderr ?? ""}`.trim();
+	return output.split(/\r?\n/).find((line) => line.trim().length > 0)?.trim() ?? "available";
+}
+
+function commandExists(command: string, args: string[]): { ok: boolean; detail: string } {
+	try {
+		const output = spawnSync(command, args, { encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] });
+		if (output.error) {
+			return { ok: false, detail: output.error.message };
+		}
+		if (output.status !== 0) {
+			return { ok: false, detail: firstOutputLine(output.stdout, output.stderr) || `status ${output.status}` };
+		}
+		return { ok: true, detail: firstOutputLine(output.stdout, output.stderr) };
+	} catch (error) {
+		return { ok: false, detail: error instanceof Error ? error.message : String(error) };
+	}
+}
+
+function piCommandExists(): { ok: boolean; detail: string } {
+	const spec = getPiSpawnCommand(["--version"]);
+	const output = commandExists(spec.command, spec.args);
+	if (!output.ok) return output;
+	const executable = spec.command === "pi" ? "pi" : `${spec.command} ${spec.args[0] ?? ""}`.trim();
+	return { ok: true, detail: `${output.detail} (${executable})` };
+}
+
+function checkWritableDir(dir: string): { ok: boolean; detail: string } {
+	try {
+		if (!fs.existsSync(dir)) return { ok: false, detail: `${dir}: missing` };
+		if (!fs.statSync(dir).isDirectory()) return { ok: false, detail: `${dir}: not a directory` };
+		// fs.accessSync(W_OK) is unreliable on Windows; verify by writing a temp file.
+		const probePath = `${dir}/.pi-crew-write-test`;
+		try {
+			fs.writeFileSync(probePath, "ok", "utf-8");
+			fs.rmSync(probePath, { force: true });
+		} catch {
+			return { ok: false, detail: `${dir}: not writable (write test failed)` };
+		}
+		return { ok: true, detail: dir };
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		return { ok: false, detail: `${dir}: ${message}` };
+	}
+}
+
+function auditJsonSchema(schema: unknown): string[] {
+	const issues: string[] = [];
+	const walk = (node: unknown): void => {
+		if (!node || typeof node !== "object" || Array.isArray(node)) return;
+		const record = node as Record<string, unknown>;
+		if (Array.isArray(record.type)) issues.push("schema node uses array-valued type");
+		if (record.description && !record.type && !record.anyOf && !record.oneOf && !record.allOf && !record.properties) issues.push(`description-only schema node: ${record.description}`);
+		if (record.type === "array" && !record.items) issues.push("array schema missing items");
+		if (record.type && (record.anyOf || record.oneOf)) issues.push("schema node combines type with union keyword");
+		for (const value of Object.values(record)) {
+			if (Array.isArray(value)) for (const item of value) walk(item);
+			else walk(value);
+		}
+	};
+	walk(schema);
+	return issues;
+}
+
+function makeLine(check: DoctorCheck): string {
+	return `- ${check.ok ? "OK" : "FAIL"} ${check.label}: ${check.detail}`;
+}
+
+function section(title: string, checks: () => DoctorCheck[]): string[] {
+	try {
+		return [title, ...checks().map(makeLine)];
+	} catch (error) {
+		const detail = error instanceof Error ? error.message : String(error);
+		return [title, `- FAIL ${title}: ${detail}`];
+	}
+}
+
+export interface TeamDoctorReportInput {
+	cwd: string;
+	configPath: string;
+	configErrors: string[];
+	configWarnings: string[];
+	model?: { provider: string; id: string };
+	validationErrors: number;
+	validationWarnings: number;
+	smokeChildPi?: { ok: boolean; detail: string };
+}
+
+export interface TeamDoctorReport {
+	text: string;
+	hasErrors: boolean;
+	drift?: DriftReport;
+}
+
+export function buildTeamDoctorReport(input: TeamDoctorReportInput): TeamDoctorReport {
+	// Compute drift once — reused in both Drift section and return value
+	const driftResult = detectDrift(
+		{
+			agents: allAgents(discoverAgents(input.cwd)).map((a) => a.name),
+			teams: allTeams(discoverTeams(input.cwd)).map((t) => t.name),
+			workflows: allWorkflows(discoverWorkflows(input.cwd)).map((w) => w.name),
+		},
+		loadConfig(input.cwd).config,
+	);
+	const sections = [
+		section("Runtime", () => {
+			const git = commandExists("git", ["--version"]);
+			const pi = piCommandExists();
+			return [
+				{ label: "cwd", ok: true, detail: input.cwd },
+				{ label: "platform", ok: true, detail: `${process.platform}/${process.arch} node=${process.version}` },
+				{ label: "pi command", ok: pi.ok, detail: pi.detail },
+				{ label: "git command", ok: git.ok, detail: git.detail },
+				{ label: "config", ok: input.configErrors.length === 0, detail: `${input.configPath} (${input.configErrors.length} errors)` },
+				{ label: "model", ok: true, detail: input.model ? `${input.model.provider}/${input.model.id}` : "not available in this context" },
+				{ label: "config warnings", ok: true, detail: `${input.configWarnings.length} warnings` },
+			];
+		}),
+		section("Filesystem", () => {
+			const userWritable = checkWritableDir(userCrewRoot());
+			const projectWritable = checkWritableDir(projectCrewRoot(input.cwd));
+			return [
+				{ label: "user state", ok: userWritable.ok || userWritable.detail.endsWith(": missing"), detail: userWritable.detail },
+				{ label: "project state", ok: projectWritable.ok || projectWritable.detail.endsWith(": missing"), detail: projectWritable.detail },
+				{ label: "project state root", ok: true, detail: path.join(projectCrewRoot(input.cwd), DEFAULT_PATHS.state.runsSubdir) },
+				{ label: "artifacts root", ok: true, detail: path.join(projectCrewRoot(input.cwd), DEFAULT_PATHS.state.artifactsSubdir) },
+			];
+		}),
+		section("Discovery", () => {
+			const discoveredAgents = allAgents(discoverAgents(input.cwd));
+			const discoveredTeams = allTeams(discoverTeams(input.cwd));
+			const discoveredWorkflows = allWorkflows(discoverWorkflows(input.cwd));
+			const agentModelHints = discoveredAgents.filter((agent) => agent.model || agent.fallbackModels?.length).length;
+			return [
+				{ label: "agents", ok: true, detail: `${discoveredAgents.length} discovered` },
+				{ label: "teams", ok: true, detail: `${discoveredTeams.length} discovered` },
+				{ label: "workflows", ok: true, detail: `${discoveredWorkflows.length} discovered` },
+				{ label: "resource model hints", ok: true, detail: `${agentModelHints} agents declare model/fallback preferences` },
+			];
+		}),
+		section("Resource validation", () => [{
+			label: "resource validation",
+			ok: input.validationErrors === 0,
+			detail: `${input.validationErrors} errors, ${input.validationWarnings} warnings`,
+		}]),
+		section("Drift", () => {
+			const driftErrors = driftResult.items.filter((item) => item.severity === "error").length;
+			const driftWarnings = driftResult.items.filter((item) => item.severity === "warning").length;
+			return [{
+				label: "config drift",
+				ok: !driftResult.hasDrift || driftErrors === 0,
+				detail: driftResult.hasDrift ? `${driftErrors} errors, ${driftWarnings} warnings` : "no drift detected",
+			}];
+		}),
+		section("Schema", () => {
+			const schemaIssues = auditJsonSchema(TeamToolParams);
+			return [{ label: "strict-provider schema", ok: schemaIssues.length === 0, detail: schemaIssues.length ? schemaIssues.slice(0, 3).join("; ") : "team tool schema compatible" }];
+		}),
+		section("Async/result delivery", () => [
+			{ label: "result watcher", ok: true, detail: "fs.watch with polling fallback for EMFILE/ENOSPC/EPERM" },
+			{ label: "async notifier", ok: true, detail: "session-stale guarded completion notifications enabled" },
+		]),
+		section("Worktrees", () => [
+			{ label: "leader repository", ok: true, detail: input.cwd },
+			{ label: "cleanup policy", ok: true, detail: "dirty worktrees preserved unless force is set" },
+		]),
+	];
+	if (input.smokeChildPi) {
+		sections.push([`Child check`, `- ${input.smokeChildPi.ok ? "OK" : "FAIL"} child Pi smoke: ${input.smokeChildPi.detail}`]);
+	}
+	const lines = ["pi-crew doctor report"];
+	for (const block of sections) {
+		if (block.length > 0) {
+			lines.push(...block);
+			lines.push("");
+		}
+	}
+	if (lines.at(-1) === "") lines.pop();
+	const text = lines.join("\n");
+	return { text, hasErrors: sections.some((sectionLines) => sectionLines.some((line) => line.includes("FAIL"))), drift: driftResult.hasDrift ? driftResult : undefined };
+}
+
+export function handleDoctor(ctx: TeamContext, params: TeamToolParamsValue = {}): PiTeamsToolResult {
+	const loadedConfig = loadConfig(ctx.cwd);
+	let smokeChildPi: { ok: boolean; detail: string } | undefined;
+	if (configRecord(params.config).smokeChildPi === true) {
+		try {
+			const spec = getPiSpawnCommand(["--mode", "json", "-p", "Reply with exactly PI-TEAMS-SMOKE-OK"]);
+			const output = execFileSync(spec.command, spec.args, {
+				cwd: ctx.cwd,
+				encoding: "utf-8",
+				stdio: ["ignore", "pipe", "pipe"],
+				timeout: 15_000,
+			}).trim();
+			smokeChildPi = { ok: output.includes("PI-TEAMS-SMOKE-OK"), detail: output.split("\n").slice(-1)[0] ?? "completed" };
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			smokeChildPi = { ok: false, detail: message };
+		}
+	}
+	const validation = validateResources(ctx.cwd);
+	const { text, hasErrors, drift } = buildTeamDoctorReport({
+		cwd: ctx.cwd,
+		configPath: loadedConfig.path,
+		configErrors: loadedConfig.error ? [loadedConfig.error] : [],
+		configWarnings: loadedConfig.warnings ?? [],
+		model: ctx.model,
+		validationErrors: validation.issues.filter((issue) => issue.level === "error").length,
+		validationWarnings: validation.issues.filter((issue) => issue.level === "warning").length,
+		smokeChildPi,
+	});
+	// Append detailed drift section if any drift was detected
+	let finalText = text;
+	if (drift?.hasDrift) {
+		finalText = `${text}\n\nDrift details:\n${formatDriftReport(drift)}`;
+	}
+	return result(finalText, { action: "doctor", status: hasErrors ? "error" : "ok" }, hasErrors);
+}