pi-crew 0.9.53 → 0.9.55

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

@@ -0,0 +1,98 @@
+/**
+ * Handler for `team action='orchestrate' planPath='/path/to/plan.md'`
+ *
+ * Parses a plan document and outputs agent chain commands.
+ */
+import * as fs from "node:fs";
+import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
+import { resolveRealContainedPath } from "../../utils/safe-paths.ts";
+import {
+	buildAgentChain,
+	formatPlanOverview,
+	type OrchestratedStep,
+	parsePlanDocument,
+	parsePlanDocumentSimple,
+} from "../plan-orchestrate.ts";
+import type { PiTeamsToolResult } from "../tool-result.ts";
+import { result, type TeamContext } from "./context.ts";
+
+/**
+ * Handle the orchestrate action.
+ *
+ * Parses a plan document (markdown with `<!-- tag: <tag> -->` comments)
+ * and outputs the decomposed agent chain commands.
+ *
+ * Usage: `team action='orchestrate' planPath='/path/to/plan.md'`
+ */
+export function handleOrchestrate(params: TeamToolParamsValue, ctx: TeamContext): PiTeamsToolResult {
+	const planPath = params.planPath as string | undefined;
+
+	if (!planPath) {
+		return result(
+			"orchestrate requires planPath parameter pointing to a markdown plan document.",
+			{ action: "orchestrate", status: "error" },
+			true,
+		);
+	}
+
+	// Resolve and validate path stays within ctx.cwd (path-traversal protection)
+	let resolvedPath: string;
+	try {
+		resolvedPath = resolveRealContainedPath(ctx.cwd, planPath);
+	} catch {
+		return result(`planPath must be within project directory: ${planPath}`, { action: "orchestrate", status: "error" }, true);
+	}
+
+	if (!fs.existsSync(resolvedPath)) {
+		return result(`Plan document not found: ${resolvedPath}`, { action: "orchestrate", status: "error" }, true);
+	}
+
+	// Try primary parser
+	let steps: OrchestratedStep[] = parsePlanDocument(resolvedPath);
+
+	// Fallback to simple parser
+	if (steps.length === 0) {
+		steps = parsePlanDocumentSimple(resolvedPath);
+	}
+
+	if (steps.length === 0) {
+		return result(
+			`No tagged sections found in plan document: ${resolvedPath}\n\nExpected format: <!-- tag: <tag> --> in markdown sections`,
+			{ action: "orchestrate", status: "error" },
+			true,
+		);
+	}
+
+	// Build overview and commands
+	const overview = formatPlanOverview(resolvedPath);
+	const commands = buildAgentChain(steps);
+
+	const outputLines: string[] = [
+		`Plan: ${resolvedPath}`,
+		`Steps: ${steps.length}`,
+		"",
+		"# Agent Chain Commands",
+		"",
+		...commands.map((cmd, i) => `${i + 1}. ${cmd}`),
+		"",
+		"# Full Overview",
+		overview,
+	];
+
+	return result(outputLines.join("\n"), {
+		action: "orchestrate",
+		status: "ok",
+		data: {
+			planPath: resolvedPath,
+			stepCount: steps.length,
+			commands,
+			steps: steps.map((sqs) => ({
+				stepId: sqs.stepId,
+				tag: sqs.tag,
+				chain: sqs.chain,
+				prompt: sqs.prompt,
+				heading: sqs.heading,
+			})),
+		},
+	});
+}

package/src/extension/team-tool/parallel-dispatch.ts

@@ -0,0 +1,183 @@
+/**
+ * Parallel dispatch handler — accepts an array of independent tasks
+ * and spawns them as concurrent background agents.
+ *
+ * Solves the host-agent limitation of only being able to emit
+ * one Agent() call per response turn. By calling `action=parallel`
+ * once with multiple tasks, the system handles fanout automatically.
+ */
+import { discoverAgents } from "../../agents/discover-agents.ts";
+import { loadConfig } from "../../config/config.ts";
+import { resolveCrewRuntime } from "../../runtime/runtime-resolver.ts";
+import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
+import { appendEvent } from "../../state/event-log.ts";
+import { createRunManifest } from "../../state/state-store.ts";
+import { spawnBackgroundTeamRun } from "../../subagents/async-entry.ts";
+import { discoverTeams } from "../../teams/discover-teams.ts";
+import type { TeamConfig } from "../../teams/team-config.ts";
+import { discoverWorkflows } from "../../workflows/discover-workflows.ts";
+import type { WorkflowConfig } from "../../workflows/workflow-config.ts";
+import { resolveCwdOverride } from "../registration/team-tool.ts";
+import type { PiTeamsToolResult } from "../tool-result.ts";
+import { result, type TeamContext } from "./context.ts";
+
+const MAX_CONCURRENCY = 8;
+const DEFAULT_CONCURRENCY = 4;
+const DEFAULT_TEAM = "fast-fix";
+const DEFAULT_AGENT = "explorer";
+
+export async function handleParallel(params: TeamToolParamsValue, ctx: TeamContext): Promise<PiTeamsToolResult> {
+	const tasksParam = params.config?.tasks;
+	if (!Array.isArray(tasksParam) || tasksParam.length === 0) {
+		return result("parallel action requires config.tasks: [{goal, agent?}]", { action: "parallel", status: "error" }, true);
+	}
+
+	const concurrency = Math.min(Math.max(1, Math.floor((params.config?.concurrency as number) ?? DEFAULT_CONCURRENCY)), MAX_CONCURRENCY);
+
+	const config = loadConfig(ctx.cwd);
+	const agentsResult = discoverAgents(ctx.cwd);
+	const allAgentsList = [...agentsResult.builtin, ...agentsResult.user, ...agentsResult.project];
+	const teams = discoverTeams(ctx.cwd);
+	const workflows = discoverWorkflows(ctx.cwd);
+
+	const teamName = (params.config?.team as string) ?? DEFAULT_TEAM;
+	const team =
+		teams.builtin.find((t) => t.name === teamName) ??
+		teams.user.find((t) => t.name === teamName) ??
+		teams.project.find((t) => t.name === teamName);
+	if (!team) {
+		return result(`Team '${teamName}' not found`, { action: "parallel", status: "error" }, true);
+	}
+
+	// H2: Use team's defaultWorkflow, fall back to "fast-fix"
+	const workflow = workflows.builtin.find((w) => w.name === team.defaultWorkflow) ?? workflows.builtin.find((w) => w.name === "fast-fix");
+	if (!workflow) {
+		return result("No suitable workflow found for parallel dispatch", { action: "parallel", status: "error" }, true);
+	}
+
+	const runtime = await resolveCrewRuntime(config.config);
+
+	const launched: Array<{ runId: string; goal: string; agent: string }> = [];
+	const errors: Array<{ goal: string; error: string }> = [];
+
+	// C1: Enforce concurrency limit with batched spawning
+	for (let batchStart = 0; batchStart < tasksParam.length; batchStart += concurrency) {
+		const batch = tasksParam.slice(batchStart, batchStart + concurrency);
+		const batchPromises = batch.map((task) => spawnSingleTask(task, ctx, allAgentsList, team, workflow, runtime));
+		const batchResults = await Promise.allSettled(batchPromises);
+		for (const res of batchResults) {
+			if (res.status === "fulfilled" && res.value.ok) {
+				launched.push(res.value.value);
+			} else if (res.status === "fulfilled" && !res.value.ok) {
+				errors.push(res.value.error);
+			} else {
+				const reason = (res as PromiseRejectedResult).reason;
+				errors.push({
+					goal: "(unknown)",
+					error: reason instanceof Error ? reason.message : String(reason),
+				});
+			}
+		}
+	}
+
+	const lines: string[] = [`Parallel dispatch: ${launched.length}/${tasksParam.length} tasks launched (concurrency: ${concurrency})`, ""];
+	for (const l of launched) {
+		lines.push(`  ✅ ${l.runId} — ${l.agent}: ${l.goal.slice(0, 80)}`);
+	}
+	for (const e of errors) {
+		lines.push(`  ❌ ${e.goal.slice(0, 80)}: ${e.error}`);
+	}
+
+	return result(
+		lines.join("\n"),
+		{
+			action: "parallel",
+			status: errors.length === tasksParam.length ? "error" : "ok",
+		},
+		errors.length === tasksParam.length,
+	);
+}
+
+type SpawnOk = {
+	ok: true;
+	value: { runId: string; goal: string; agent: string };
+};
+type SpawnErr = { ok: false; error: { goal: string; error: string } };
+type SpawnResult = SpawnOk | SpawnErr;
+
+async function spawnSingleTask(
+	task: unknown,
+	ctx: TeamContext,
+	allAgentsList: Array<{ name: string }>,
+	team: TeamConfig,
+	workflow: WorkflowConfig,
+	runtime: { available: boolean; kind: string },
+): Promise<SpawnResult> {
+	try {
+		const taskRec = task as Record<string, unknown>;
+		const goal = taskRec.goal as string;
+		const agentName = (taskRec.agent as string) ?? DEFAULT_AGENT;
+		const rawCwd = (taskRec.cwd as string) ?? undefined;
+
+		if (!goal) {
+			return {
+				ok: false,
+				error: {
+					goal: "(missing)",
+					error: "Each task must have a 'goal' field",
+				},
+			};
+		}
+
+		const agent = allAgentsList.find((a) => a.name === agentName);
+		if (!agent) {
+			return {
+				ok: false,
+				error: { goal, error: `Agent '${agentName}' not found` },
+			};
+		}
+
+		// H1: Validate taskCwd containment against project root
+		const cwdResult = resolveCwdOverride(ctx.cwd, rawCwd);
+		if (!cwdResult.ok) {
+			return { ok: false, error: { goal, error: cwdResult.error } };
+		}
+		const taskCwd = cwdResult.cwd;
+
+		const created = createRunManifest({
+			cwd: taskCwd,
+			team,
+			workflow,
+			goal,
+			// EXT F1: mirror handleRun — without ownerSessionId, the foreign-run check in
+			// cancel/retry/resume (cancel.ts:50: `typeof ownerSessionId === "string"`) is
+			// skipped and any session can cancel/retry parallel-dispatched runs.
+			ownerSessionId: ctx.sessionId,
+			runKind: "team-run",
+		});
+
+		appendEvent(created.manifest.eventsPath, {
+			type: "run.started",
+			runId: created.manifest.runId,
+			message: `Parallel task: ${goal}`,
+		});
+
+		if (runtime.available && runtime.kind === "child-process") {
+			await spawnBackgroundTeamRun(created.manifest);
+		}
+
+		return {
+			ok: true,
+			value: { runId: created.manifest.runId, goal, agent: agentName },
+		};
+	} catch (error) {
+		const goal = ((task as Record<string, unknown>).goal as string) ?? "(unknown)";
+		return {
+			ok: false,
+			error: {
+				goal,
+				error: error instanceof Error ? error.message : String(error),
+			},
+		};
+	}
+}

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

@@ -0,0 +1,50 @@
+import { composeSingleAgentPrompt } from "../../runtime/single-agent-compose.ts";
+import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
+import { allTeams, discoverTeams } from "../../teams/discover-teams.ts";
+import { allWorkflows, discoverWorkflows } from "../../workflows/discover-workflows.ts";
+import { validateWorkflowForTeam } from "../../workflows/validate-workflow.ts";
+import type { PiTeamsToolResult } from "../tool-result.ts";
+import { result, type TeamContext } from "./context.ts";
+
+export function handlePlan(params: TeamToolParamsValue, ctx: TeamContext): PiTeamsToolResult {
+	const teamName = params.team ?? "default";
+	const team = allTeams(discoverTeams(ctx.cwd)).find((item) => item.name === teamName);
+	if (!team) return result(`Team '${teamName}' not found.`, { action: "plan", status: "error" }, true);
+	const workflowName = params.workflow ?? team.defaultWorkflow ?? "default";
+	const workflow = allWorkflows(discoverWorkflows(ctx.cwd)).find((item) => item.name === workflowName);
+	if (!workflow) return result(`Workflow '${workflowName}' not found.`, { action: "plan", status: "error" }, true);
+	const errors = validateWorkflowForTeam(workflow, team);
+	if (errors.length > 0)
+		return result(
+			[`Workflow '${workflow.name}' is not valid for team '${team.name}':`, ...errors.map((error) => `- ${error}`)].join("\n"),
+			{ action: "plan", status: "error" },
+			true,
+		);
+	const goal = params.goal ?? params.task ?? "(not provided)";
+	// ROADMAP T2.2: single-agent composition mode (cliff hedge).
+	if (params.singleAgent) {
+		const composed = composeSingleAgentPrompt(workflow, goal);
+		return result(
+			[
+				`Single-agent plan for ${team.name} / ${workflow.name} (${composed.stepCount} phases composed into one sequential prompt):`,
+				"",
+				composed.prompt,
+				"",
+				"This prompt can be handed to a single agent to execute the entire workflow sequentially — pi-crew's cliff-resilient mode (survives single-agent domination).",
+			].join("\n"),
+			{ action: "plan", status: "ok" },
+		);
+	}
+	const lines = [
+		`Team plan: ${team.name}`,
+		`Workflow: ${workflow.name}`,
+		`Goal: ${goal}`,
+		"",
+		"Steps:",
+		...workflow.steps.map(
+			(step, index) =>
+				`${index + 1}. ${step.id} [${step.role}]${step.dependsOn?.length ? ` after ${step.dependsOn.join(", ")}` : ""}`,
+		),
+	];
+	return result(lines.join("\n"), { action: "plan", status: "ok" });
+}

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

@@ -0,0 +1,150 @@
+import { readCrewAgents, recordFromTask, saveCrewAgents } from "../../runtime/crew-agent-records.ts";
+import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
+import { appendEvent } from "../../state/event-log.ts";
+import { withRunLockSync } from "../../state/locks.ts";
+import { appendMailboxMessage, updateMailboxMessageReply } from "../../state/mailbox.ts";
+import { loadRunManifestById, saveRunTasks, updateRunStatus } from "../../state/state-store.ts";
+import { logInternalError } from "../../utils/internal-error.ts";
+import { locateRunCwd } from "../team-tool.ts";
+import type { PiTeamsToolResult } from "../tool-result.ts";
+import { result, type TeamContext } from "./context.ts";
+import { RUN_NOT_FOUND_HINT } from "./run-not-found.ts";
+
+/**
+ * Handle `respond` action: send a message to a waiting (interactive) task.
+ * The task must be in "waiting" status. The message is stored in the task's
+ * mailbox and the task is re-queued for durable scheduler resume.
+ */
+export function handleRespond(params: TeamToolParamsValue, ctx: TeamContext): PiTeamsToolResult {
+	if (!params.runId) return result("Respond requires runId.", { action: "respond", status: "error" }, true);
+	if (!params.message && !params.taskId)
+		return result("Respond requires taskId and/or message.", { action: "respond", status: "error" }, true);
+
+	const runCwd = locateRunCwd(params.runId, ctx.cwd);
+	if (!runCwd) return result(`Run '${params.runId}' not found.${RUN_NOT_FOUND_HINT}`, { action: "respond", status: "error" }, true);
+	const loaded = loadRunManifestById(runCwd, params.runId); // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency
+	if (!loaded) return result(`Run '${params.runId}' not found.${RUN_NOT_FOUND_HINT}`, { action: "respond", status: "error" }, true);
+
+	return withRunLockSync(loaded.manifest, () => {
+		const fresh = loadRunManifestById(loaded.manifest.cwd, params.runId!); // NOTE: inside withRunLockSync - consistent read
+		if (!fresh) return result(`Run '${params.runId}' not found.${RUN_NOT_FOUND_HINT}`, { action: "respond", status: "error" }, true);
+		const foreignRun = typeof fresh.manifest.ownerSessionId === "string" && fresh.manifest.ownerSessionId !== ctx.sessionId;
+		if (foreignRun && !params.force)
+			return result(
+				`Run ${fresh.manifest.runId} belongs to another session. Use force: true to override.`,
+				{
+					action: "respond",
+					status: "error",
+					runId: fresh.manifest.runId,
+				},
+				true,
+			);
+
+		const taskId = params.taskId;
+		const message = params.message ?? "";
+
+		const targetTasks = taskId
+			? fresh.tasks.filter((t) => t.id === taskId && t.status === "waiting")
+			: fresh.tasks.filter((t) => t.status === "waiting");
+
+		if (targetTasks.length === 0) {
+			const existing = taskId ? fresh.tasks.find((t) => t.id === taskId) : undefined;
+			const hint =
+				" Use api operation=follow-up-agent for continuation prompts or api operation=steer-agent to interrupt active work.";
+			return result(
+				(taskId
+					? existing
+						? `Task '${taskId}' is ${existing.status}, not waiting.`
+						: `Task '${taskId}' not found.`
+					: `No waiting tasks in run ${fresh.manifest.runId}.`) + hint,
+				{
+					action: "respond",
+					status: "error",
+					runId: fresh.manifest.runId,
+				},
+				true,
+			);
+		}
+
+		const resumed = new Set(targetTasks.map((t) => t.id));
+		const mailboxIds: string[] = [];
+		for (const task of targetTasks) {
+			const mailbox = appendMailboxMessage(fresh.manifest, {
+				direction: "inbox",
+				from: "leader",
+				to: task.id,
+				taskId: task.id,
+				body: message || "(resume)",
+				kind: "response",
+				priority: "normal",
+				deliveryMode: "next_turn",
+				data: { action: "respond", kind: "response" },
+				replyTo: params.replyTo,
+				replyFrom: params.replyFrom,
+				replyDeadline: params.replyDeadline,
+			});
+			mailboxIds.push(mailbox.id);
+		}
+
+		// If this respond includes a replyTo, update the original message with reply metadata.
+		if (params.replyTo) {
+			updateMailboxMessageReply(fresh.manifest, params.replyTo, message || "(resume)");
+		}
+
+		// Re-queue waiting tasks so durable scheduler/resume can pick them up again.
+		const updatedTasks = fresh.tasks.map((task) => {
+			if (!resumed.has(task.id)) return task;
+			return {
+				...task,
+				status: "queued" as const,
+				startedAt: undefined,
+				finishedAt: undefined,
+				error: undefined,
+				adaptive: {
+					...task.adaptive,
+					phase: "resumed",
+					task: message || task.adaptive?.task || "",
+				},
+			};
+		});
+
+		saveRunTasks(fresh.manifest, updatedTasks);
+		let manifest = fresh.manifest;
+		if (
+			manifest.status === "blocked" ||
+			manifest.status === "completed" ||
+			manifest.status === "failed" ||
+			manifest.status === "cancelled"
+		) {
+			manifest = updateRunStatus(manifest, "running", `Resumed ${resumed.size} waiting task(s).`);
+		}
+		for (const taskId of resumed) {
+			appendEvent(manifest.eventsPath, {
+				type: "task.resumed",
+				runId: manifest.runId,
+				taskId,
+				message: message || "Task re-queued after respond.",
+				data: { mailboxIds },
+			});
+		}
+		try {
+			const existingRuntimes = new Map(readCrewAgents(fresh.manifest).map((a) => [a.taskId, a.runtime]));
+			saveCrewAgents(
+				fresh.manifest,
+				updatedTasks.map((task) => recordFromTask(fresh.manifest, task, existingRuntimes.get(task.id) ?? "child-process")),
+			);
+		} catch (error) {
+			logInternalError("team-tool.handleRespond.crewAgents", error, `runId=${fresh.manifest.runId}`);
+		}
+
+		const resumedIds = targetTasks.map((t) => t.id);
+		return result(`Resumed ${resumedIds.length} waiting task(s): ${resumedIds.join(", ")}. Message: ${message || "(no message)"}`, {
+			action: "respond",
+			status: "ok",
+			runId: fresh.manifest.runId,
+			resumedIds,
+			mailboxIds,
+			intent: `responding to ${resumedIds.join(", ")} in ${fresh.manifest.runId}`,
+		});
+	});
+}

package/src/extension/team-tool/run-deadline.ts

@@ -0,0 +1,66 @@
+import type { PiTeamsConfig } from "../../config/config.ts";
+import { loadConfig } from "../../config/config.ts";
+import type { TeamContext } from "./context.ts";
+
+/**
+ * Resolved run deadline — a shared AbortController, its signal, and the
+ * computed deadline in milliseconds.
+ */
+export interface RunDeadline {
+	/** AbortSignal to pass to run executors (executeTeamRun, runDynamicWorkflow). */
+	signal: AbortSignal;
+	/** Computed deadline in milliseconds (used for `waitForRun` timeoutMs). */
+	deadlineMs: number;
+	/** Underlying controller — callers may link additional parent signals. */
+	controller: AbortController;
+}
+
+/** Fallback deadline when no config or param override is available: 1 hour. */
+export const DEFAULT_RUN_DEADLINE_MS = 3_600_000;
+
+/**
+ * Resolve a unified run deadline with a shared AbortController.
+ *
+ * CORE-8 fix: previously three code paths in run.ts used inconsistent timeout
+ * policies — the DWF path used `AbortSignal.timeout(3_600_000)`, the foreground
+ * async path used `waitForRun(timeoutMs: 3_600_000)`, and the inline scaffold
+ * path passed `ctx.signal` with **zero** deadline fallback (could hang
+ * indefinitely if the caller signal never fires).
+ *
+ * This helper unifies all three into a single resolution strategy:
+ *
+ * Priority: `params.timeoutMs` → `config.limits.maxRunMinutes * 60_000` →
+ * `DEFAULT_RUN_DEADLINE_MS` (1 hour).
+ *
+ * The returned AbortController is linked to `ctx.signal` (caller abort
+ * propagates immediately) and armed with a deadline timer (`setTimeout` +
+ * `unref` so it never keeps the event loop alive). Callers may link additional
+ * parent signals to `controller` — e.g. a `startForegroundRun` callback signal.
+ *
+ * The `params` generic accepts the full `TeamToolParamsValue` (or any object
+ * with an optional `timeoutMs`); the value is read defensively via cast so the
+ * weak-type TS2559 check does not fire.
+ */
+export function resolveRunDeadline<T extends object>(
+	ctx: Pick<TeamContext, "cwd" | "signal">,
+	params: T,
+	config?: PiTeamsConfig,
+): RunDeadline {
+	const timeoutMs = (params as { timeoutMs?: number }).timeoutMs;
+	const effectiveConfig = config ?? loadConfig(ctx.cwd).config;
+	const maxRunMinutes = effectiveConfig?.limits?.maxRunMinutes;
+	const deadlineMs = timeoutMs ?? (maxRunMinutes ? maxRunMinutes * 60_000 : DEFAULT_RUN_DEADLINE_MS);
+
+	const controller = new AbortController();
+	// Propagate caller abort (ctx.signal) to the shared controller.
+	if (ctx.signal) {
+		if (ctx.signal.aborted) controller.abort();
+		else ctx.signal.addEventListener("abort", () => controller.abort(), { once: true });
+	}
+	// Arm the deadline timer (unref'd so it never blocks process exit).
+	if (deadlineMs > 0) {
+		const timer = setTimeout(() => controller.abort(), deadlineMs);
+		timer.unref?.();
+	}
+	return { signal: controller.signal, deadlineMs, controller };
+}

package/src/extension/team-tool/run-not-found.ts

@@ -0,0 +1,49 @@
+/**
+ * run-not-found.ts — Centralized "Run not found" error helper (DX: F2).
+ *
+ * Round 16 DX audit found that a stale/typo'd runId hits a blank
+ * "Run '<id>' not found." wall in 8+ handlers (status, resume, steer, export,
+ * forget, cleanup, invalidate, worktrees, events, artifacts). The run IDs are
+ * long (`team_20260615173318_b9c8fe49a74e0760`), so typos/truncation are
+ * near-certain for new users — yet `team list` (which shows recent runs) is
+ * never suggested.
+ *
+ * This module centralizes the message + recovery hint so every handler stays
+ * consistent and the hint never drifts.
+ */
+
+import type { TeamToolDetails } from "../team-tool-types.ts";
+import { result, type TeamContext } from "./context.ts";
+
+/** Recovery hint appended to every "Run not found" message. */
+export const RUN_NOT_FOUND_HINT = "\n\nTip: run action='list' to see recent runs and their IDs.";
+
+/**
+ * Build the standard "Run not found" error result with a recovery hint.
+ *
+ * @param runId  the (missing/typo'd) run id the caller passed
+ * @param action the action that was attempted (for the details.action field)
+ */
+export function runNotFound(runId: string, action: string): ReturnType<typeof result> {
+	return result(`Run '${runId}' not found.${RUN_NOT_FOUND_HINT}`, { action, status: "error" } satisfies TeamToolDetails, true);
+}
+
+/**
+ * Helper: resolve a runId to its cwd, returning a runNotFound() result when
+ * missing. Reduces the boilerplate `locateRunCwd → if (!runCwd) return ...`
+ * duplicated across handlers.
+ */
+export function resolveRunOrNotFound(
+	runId: string,
+	action: string,
+	cwd: string,
+	locate: (runId: string, cwd: string) => string | undefined,
+): { kind: "found"; runCwd: string } | { kind: "notfound"; result: ReturnType<typeof result> } {
+	const runCwd = locate(runId, cwd);
+	if (!runCwd) return { kind: "notfound", result: runNotFound(runId, action) };
+	return { kind: "found", runCwd };
+}
+
+// Re-export TeamContext so callers importing this helper don't need a second
+// import line — keeps the diff in each handler to a single import swap.
+export type { TeamContext };