pi-crew 0.9.65 → 0.9.67

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

@@ -10,7 +10,7 @@ import {
 } from "../../runtime/process/cancellation.ts";
 import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
 import { withRunLockSync } from "../../state/coordination/locks.ts";
-import { appendEvent } from "../../state/event-log/event-log.ts";
+import { appendEvent, appendEventAsync } from "../../state/event-log/event-log.ts";
 import { loadRunManifestById, saveRunTasks, updateRunStatus } from "../../state/stores/state-store.ts";
 import { logInternalError } from "../../utils/internal-error.ts";
 import { locateRunCwd } from "../team-tool.ts";
@@ -21,6 +21,28 @@ import { enforceDestructiveIntent, intentFromConfig } from "./intent-policy.ts";
 import { paramRequired } from "./param-error.ts";
 import { RUN_NOT_FOUND_HINT } from "./run-not-found.ts";
 
+/** Retryable terminal statuses (a task in one of these can be re-queued). */
+const RETRYABLE_STATUSES: ReadonlySet<string> = new Set(["failed", "cancelled"]);
+
+/**
+ * Pure pre-lock decision for `action='retry'`: a run whose manifest status is
+ * "completed" (terminal success) and has no retryable tasks has nothing to
+ * retry. Returns true so the caller short-circuits with a clear message
+ * BEFORE acquiring the run lock — avoiding a misleading
+ * "run.lock is locked by another operation" error from a stale lock file left
+ * behind by a completed async run (finding #4, real-test-2026-08-10-full-9-tier).
+ *
+ * Exported for unit testing (handleRetry itself needs filesystem state).
+ */
+export function retryShortCircuitsCompleted(
+	runStatus: string,
+	tasks: ReadonlyArray<{ id: string; status: string }>,
+	targetTaskId?: string,
+): boolean {
+	if (runStatus !== "completed") return false;
+	return !tasks.some((task) => (targetTaskId ? task.id === targetTaskId : true) && RETRYABLE_STATUSES.has(task.status));
+}
+
 export interface AbortOwnedResult {
 	abortedIds: string[];
 	missingIds: string[];
@@ -126,6 +148,18 @@ export async function handleRetry(params: TeamToolParamsValue, ctx: TeamContext,
 
 	const targetTaskId = typeof params.taskId === "string" ? params.taskId : undefined;
 
+	// Pre-lock terminal-status check: a completed run has nothing to retry.
+	// Short-circuit BEFORE acquiring the run lock so a stale lock file left by a
+	// completed async run does not surface a misleading "run.lock is locked by
+	// another operation" error (finding #4 in real-test-2026-08-10-full-9-tier).
+	if (retryShortCircuitsCompleted(loaded.manifest.status, loaded.tasks, targetTaskId)) {
+		return result(
+			`Run ${loaded.manifest.runId} is already completed; retry only applies to failed/cancelled runs.`,
+			{ action: "retry", status: "error", runId: loaded.manifest.runId },
+			true,
+		);
+	}
+
 	return withRunLockSync(loaded.manifest, () => {
 		const retryableStatuses: ReadonlySet<string> = new Set(["failed", "cancelled"]);
 
@@ -164,12 +198,21 @@ export async function handleRetry(params: TeamToolParamsValue, ctx: TeamContext,
 
 		const retriedTaskIds = [...retriedIds];
 		for (const taskId of retriedTaskIds) {
-			appendEvent(loaded.manifest.eventsPath, {
+			// H1 (2026-08-10): inside a sync run-lock callback — cannot await;
+			// fire-and-forget async. task.retried is informational; the queued
+			// status is the authoritative record in tasks.json.
+			void appendEventAsync(loaded.manifest.eventsPath, {
 				type: "task.retried",
 				runId: loaded.manifest.runId,
 				taskId,
 				message: `Task ${taskId} queued for retry.`,
-			});
+			}).catch((error) =>
+				logInternalError(
+					"cancel.retry-event",
+					error instanceof Error ? error : new Error(String(error)),
+					`runId=${loaded.manifest.runId}`,
+				),
+			);
 		}
 
 		if (deps) invalidateSnapshot(loaded.manifest.runId, runCwd, deps);
@@ -233,7 +276,9 @@ export async function handleCancel(params: TeamToolParamsValue, ctx: TeamContext
 	if (asyncPid !== undefined && asyncPid > 0) {
 		try {
 			killProcessPid(asyncPid);
-			appendEvent(loaded.manifest.eventsPath, {
+			// H1 (2026-08-10): informational event in async context — await the
+			// async lock path (non-blocking event loop, ~1ms vs ~14ms sync).
+			await appendEventAsync(loaded.manifest.eventsPath, {
 				type: "async.kill_requested",
 				runId: loaded.manifest.runId,
 				message: "Sent SIGTERM to background runner process.",

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

@@ -130,10 +130,13 @@ export async function handleManageDomain(params: TeamToolParamsValue, ctx: TeamC
 						unsetPaths,
 					});
 					return result(
-						["Updated pi-crew config.", `Path: ${saved.path}`, "Effective config:", JSON.stringify(saved.config, null, 2)].join(
-							"\n",
-						),
-						{ action: "config", status: "ok" },
+						[
+							saved.written ? "Updated pi-crew config." : "Config unchanged (no effective changes).",
+							`Path: ${saved.path}`,
+							"Effective config:",
+							JSON.stringify(saved.config, null, 2),
+						].join("\n"),
+						{ action: "config", status: "ok", written: saved.written },
 					);
 				} catch (error) {
 					const message = error instanceof Error ? error.message : String(error);

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

@@ -2,6 +2,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { loadRunManifestById } from "../../state/stores/state-store.ts";
 import type { TeamRunManifest, TeamTaskState } from "../../state/types.ts";
+import { locateRunCwd } from "../team-tool.ts";
 import { RUN_NOT_FOUND_HINT } from "./run-not-found.ts";
 
 /**
@@ -215,7 +216,8 @@ export function handleExplain(
 		return result("explain requires runId", { action: "explain", status: "error" }, true);
 	}
 
-	const loaded = loadRunManifestById(cwd, params.runId); // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency
+	const runCwd = locateRunCwd(params.runId, cwd);
+	const loaded = runCwd ? loadRunManifestById(runCwd, params.runId) : undefined; // 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: "explain", status: "error" }, true);
 	}

package/src/extension/team-tool/goal-wrap.ts

@@ -24,7 +24,7 @@ import { GoalStore } from "../../runtime/goal-workflow/goal-state-store.ts";
 import { snapshotManifests } from "../../runtime/verification/verification-integrity.ts";
 import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
 import { atomicWriteJson } from "../../state/atomic-write.ts";
-import { appendEvent } from "../../state/event-log/event-log.ts";
+import { appendEventAsync } from "../../state/event-log/event-log.ts";
 import { createRunPaths, saveRunManifestAsync } from "../../state/stores/state-store.ts";
 import type { GoalLoopState, TeamRunManifest } from "../../state/types.ts";
 import { logInternalError } from "../../utils/internal-error.ts";
@@ -269,7 +269,7 @@ export async function startGoalWrappedRun(
 			runKind: "goal-loop",
 		};
 		await saveRunManifestAsync(goalLoopManifest);
-		appendEvent(paths.eventsPath, {
+		await appendEventAsync(paths.eventsPath, {
 			type: "goal.loop_start",
 			runId: goalId,
 			data: {

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

@@ -19,7 +19,7 @@ import { GoalStore } from "../../runtime/goal-workflow/goal-state-store.ts";
 import { snapshotManifests } from "../../runtime/verification/verification-integrity.ts";
 import { isWorkspaceBusy } from "../../runtime/workspace-lock.ts";
 import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
-import { appendEvent } from "../../state/event-log/event-log.ts";
+import { appendEventAsync } from "../../state/event-log/event-log.ts";
 import { createRunPaths, saveRunManifestAsync } from "../../state/stores/state-store.ts";
 import type { GoalLoopState, GoalLoopStatus, TeamRunManifest } from "../../state/types.ts";
 import { logInternalError } from "../../utils/internal-error.ts";
@@ -193,7 +193,7 @@ async function handleStart(input: GoalSubActionInput): Promise<ReturnType<typeof
 			runKind: "goal-loop",
 		};
 		await saveRunManifestAsync(goalLoopManifest);
-		appendEvent(paths.eventsPath, {
+		await appendEventAsync(paths.eventsPath, {
 			type: "goal.loop_start",
 			runId: goalId,
 			data: {
@@ -438,7 +438,7 @@ async function handleResume(input: GoalSubActionInput): Promise<ReturnType<typeo
 	if (hint) {
 		withHint = store.patch(goalId, { nextTurnFeedback: hint }, eventsPath) ?? updated;
 	}
-	appendEvent(eventsPath, {
+	await appendEventAsync(eventsPath, {
 		type: "goal.resumed",
 		runId: goalId,
 		data: { goalId, fromState: existing.state, hint: hint?.slice(0, 200) },
@@ -487,7 +487,7 @@ async function handleResume(input: GoalSubActionInput): Promise<ReturnType<typeo
 		// 'goal resume' (which requires paused/stuck). Leaving it at 'running' with no process made
 		// the goal un-resumable — the user had to pause-then-resume as a workaround.
 		store.compareAndSetStatus(goalId, "running", existing.state, eventsPath);
-		appendEvent(eventsPath, {
+		await appendEventAsync(eventsPath, {
 			type: "goal.resume_spawn_failed",
 			runId: goalId,
 			data: { goalId, error: msg, rolledBackTo: existing.state },

package/src/extension/team-tool/lifecycle-actions.ts

@@ -5,7 +5,7 @@ import { appendHookEvent, executeHook } from "../../hooks/registry.ts";
 import { killProcessPid } from "../../runtime/child-pi/child-pi.ts";
 import { terminateLiveAgentsForRun } from "../../runtime/live-session/live-agent-manager.ts";
 import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
-import { appendEvent } from "../../state/event-log/event-log.ts";
+import { appendEvent, appendEventAsync } from "../../state/event-log/event-log.ts";
 import { loadRunManifestById } from "../../state/stores/state-store.ts";
 import { logInternalError } from "../../utils/internal-error.ts";
 import { projectCrewRoot, userCrewRoot, userPiRoot } from "../../utils/paths.ts";
@@ -16,6 +16,7 @@ import { listImportedRuns } from "../import-index.ts";
 import { exportRunBundle } from "../run-export.ts";
 import { importRunBundle } from "../run-import.ts";
 import { pruneFinishedRuns } from "../run-maintenance.ts";
+import { locateRunCwd } from "../team-tool.ts";
 import type { PiTeamsToolResult } from "../tool-result.ts";
 import { configRecord, result, type TeamContext } from "./context.ts";
 import { enforceDestructiveIntent, intentFromConfig } from "./intent-policy.ts";
@@ -29,7 +30,9 @@ export function handleWorktrees(params: TeamToolParamsValue, ctx: TeamContext):
 			{ action: "worktrees", status: "error" },
 			true,
 		);
-	const loaded = loadRunManifestById(ctx.cwd, params.runId); // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency
+	const runCwd = locateRunCwd(params.runId, ctx.cwd);
+	if (!runCwd) return result(`Run '${params.runId}' not found.${RUN_NOT_FOUND_HINT}`, { action: "worktrees", 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: "worktrees", status: "error" }, true);
 	const withWorktrees = loaded.tasks.filter((task) => task.worktree);
 	const lines = [
@@ -125,7 +128,7 @@ export async function handleExport(params: TeamToolParamsValue, ctx: TeamContext
 	}
 
 	const exported = exportRunBundle(loaded.manifest, loaded.tasks);
-	appendEvent(loaded.manifest.eventsPath, {
+	await appendEventAsync(loaded.manifest.eventsPath, {
 		type: "run.exported",
 		runId: loaded.manifest.runId,
 		data: exported,
@@ -253,7 +256,7 @@ export async function handleForget(params: TeamToolParamsValue, ctx: TeamContext
 			true,
 		);
 	const intent = intentFromConfig(params.config);
-	appendEvent(loaded.manifest.eventsPath, {
+	await appendEventAsync(loaded.manifest.eventsPath, {
 		type: "run.forget_requested",
 		runId: loaded.manifest.runId,
 		message: "Run state and artifacts are being forgotten.",
@@ -273,7 +276,7 @@ export async function handleForget(params: TeamToolParamsValue, ctx: TeamContext
 	if (asyncPid !== undefined && asyncPid > 0) {
 		try {
 			killProcessPid(asyncPid);
-			appendEvent(loaded.manifest.eventsPath, {
+			await appendEventAsync(loaded.manifest.eventsPath, {
 				type: "async.kill_requested",
 				runId: loaded.manifest.runId,
 				message: "Sent SIGTERM to background runner process (forget).",
@@ -652,7 +655,7 @@ async function handleRunCleanup(params: TeamToolParamsValue, ctx: TeamContext):
 		signal: ctx.signal,
 	});
 	const intent = intentFromConfig(params.config);
-	appendEvent(loaded.manifest.eventsPath, {
+	await appendEventAsync(loaded.manifest.eventsPath, {
 		type: "worktree.cleanup",
 		runId: loaded.manifest.runId,
 		data: {

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

@@ -11,7 +11,7 @@ import { loadConfig } from "../../config/config.ts";
 import { spawnBackgroundTeamRun } from "../../runtime/async-runner.ts";
 import { resolveCrewRuntime } from "../../runtime/model/runtime-resolver.ts";
 import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
-import { appendEvent } from "../../state/event-log/event-log.ts";
+import { appendEventAsync } from "../../state/event-log/event-log.ts";
 import { createRunManifest } from "../../state/stores/state-store.ts";
 import { discoverTeams } from "../../teams/discover-teams.ts";
 import type { TeamConfig } from "../../teams/team-config.ts";
@@ -165,7 +165,7 @@ async function spawnSingleTask(
 			runKind: "team-run",
 		});
 
-		appendEvent(created.manifest.eventsPath, {
+		await appendEventAsync(created.manifest.eventsPath, {
 			type: "run.started",
 			runId: created.manifest.runId,
 			message: `Parallel task: ${goal}`,

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

@@ -2,7 +2,7 @@ import { readCrewAgents, recordFromTask, saveCrewAgents } from "../../runtime/cr
 import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
 import { withRunLockSync } from "../../state/coordination/locks.ts";
 import { appendMailboxMessage, updateMailboxMessageReply } from "../../state/coordination/mailbox.ts";
-import { appendEvent } from "../../state/event-log/event-log.ts";
+import { appendEventAsync } from "../../state/event-log/event-log.ts";
 import { loadRunManifestById, saveRunTasks, updateRunStatus } from "../../state/stores/state-store.ts";
 import { logInternalError } from "../../utils/internal-error.ts";
 import { locateRunCwd } from "../team-tool.ts";
@@ -133,13 +133,21 @@ export function handleRespond(params: TeamToolParamsValue, ctx: TeamContext): Pi
 			manifest = updateRunStatus(manifest, "running", `Resumed ${resumed.size} waiting task(s).`);
 		}
 		for (const taskId of resumed) {
-			appendEvent(manifest.eventsPath, {
+			// H1 (2026-08-10): handleRespond is a SYNC function inside a sync
+			// run-lock callback — cannot await; fire-and-forget async.
+			void appendEventAsync(manifest.eventsPath, {
 				type: "task.resumed",
 				runId: manifest.runId,
 				taskId,
 				message: message || "Task re-queued after respond.",
 				data: { mailboxIds },
-			});
+			}).catch((error) =>
+				logInternalError(
+					"respond.resumed-event",
+					error instanceof Error ? error : new Error(String(error)),
+					`runId=${manifest.runId}`,
+				),
+			);
 		}
 		try {
 			const existingRuntimes = new Map(readCrewAgents(fresh.manifest).map((a) => [a.taskId, a.runtime]));

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

@@ -0,0 +1,357 @@
+/**
+ * Run-intent validation phase (H3 phase 4).
+ *
+ * Extracted from `handleRun` (src/extension/team-tool/run.ts) on 2026-08-10.
+ * Validates the tool params → resolved team/workflow/agent + goal + analysis,
+ * returning either a validated `RunIntent` (for materialization) or an error
+ * result. Behaviour is byte-identical to the inline block it replaces —
+ * including the exact error-precedence order the run tests assert on.
+ *
+ * The chain dispatch stays in `handleRun` because it recurses via a lazy
+ * injected handleRun reference (run.ts ↔ chain-dispatch.ts import cycle).
+ */
+
+import * as fs from "node:fs";
+import { allAgents, discoverAgents } from "../../agents/discover-agents.ts";
+import { loadConfig } from "../../config/config.ts";
+import { sanitizeTaskText } from "../../runtime/task-packet.ts";
+import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
+import { allTeams, discoverTeams } from "../../teams/discover-teams.ts";
+import type { TeamConfig } from "../../teams/team-config.ts";
+import { errorMessage } from "../../utils/guards.ts";
+import { logInternalError } from "../../utils/internal-error.ts";
+import { resolveRealContainedPath } from "../../utils/safe-paths.ts";
+import { allWorkflows, discoverWorkflows } from "../../workflows/discover-workflows.ts";
+import type { WorkflowConfig } from "../../workflows/workflow-config.ts";
+import { assertCleanLeaderAsync, findGitRootAsync } from "../../worktree/worktree-manager.ts";
+import type { PiTeamsToolResult } from "../tool-result.ts";
+import type { TeamContext } from "./context.ts";
+import { result } from "./context.ts";
+import { isGoalWrapEnabled, shouldGoalWrap, startGoalWrappedRun } from "./goal-wrap.ts";
+import { paramRequired } from "./param-error.ts";
+
+/** Cap for inline/path analysis content (mirrors the schema maxLength). */
+const MAX_ANALYSIS_BYTES = 100_000;
+
+/**
+ * Module-scoped latch for the crew-init dynamic import (moved verbatim from
+ * run.ts — see the comment there for the jiti TDZ race it guards).
+ */
+var crewInitPromise: Promise<typeof import("../../state/crew-init.ts")> | undefined;
+function loadCrewInit(): Promise<typeof import("../../state/crew-init.ts")> {
+	if (!crewInitPromise) {
+		crewInitPromise = import("../../state/crew-init.ts");
+	}
+	return crewInitPromise;
+}
+
+/**
+ * Resolve analysis text from inline or file. Mutual exclusivity mirrors the
+ * `budgetTotal`/`budgetUnlimited` pattern (cold-review #2 blocking fix).
+ */
+function resolveAnalysisText(
+	params: TeamToolParamsValue,
+	cwd: string,
+): { text?: string; error?: string; source: "inline" | "path" | "none" } {
+	const hasInline = typeof params.analysis === "string" && params.analysis.length > 0;
+	const hasPath = typeof params.analysisPath === "string" && params.analysisPath.length > 0;
+
+	if (hasInline && hasPath) {
+		return {
+			error: "`analysis` and `analysisPath` are mutually exclusive. Set exactly one.",
+			source: "none",
+		};
+	}
+	if (!hasInline && !hasPath) return { source: "none" };
+
+	if (hasPath) {
+		let resolved: string;
+		try {
+			resolved = resolveRealContainedPath(cwd, params.analysisPath as string);
+		} catch {
+			return {
+				error: `analysisPath must be within project directory: ${params.analysisPath}`,
+				source: "none",
+			};
+		}
+		if (!fs.existsSync(resolved)) {
+			return {
+				error: `Analysis file not found: ${resolved}`,
+				source: "none",
+			};
+		}
+		// Size cap BEFORE reading: mirror the inline schema cap (maxLength 100_000)
+		// so a large file can't blow up worker prompts via the sharedReads channel.
+		const { size } = fs.statSync(resolved);
+		if (size > MAX_ANALYSIS_BYTES) {
+			return {
+				error: `Analysis file too large: ${size} bytes (max ${MAX_ANALYSIS_BYTES}). Trim the analysis or pass a summary inline.`,
+				source: "none",
+			};
+		}
+		const raw = fs.readFileSync(resolved, "utf-8");
+		const sanitized = sanitizeTaskText(raw);
+		if (!sanitized) return { source: "none" };
+		return { text: sanitized, source: "path" };
+	}
+
+	// hasInline
+	const sanitized = sanitizeTaskText(params.analysis as string);
+	if (!sanitized) return { source: "none" };
+	return { text: sanitized, source: "inline" };
+}
+
+/** The validated run intent produced by {@link validateRunIntent}. */
+export interface RunIntent {
+	goal: string;
+	intentPrefix: string;
+	/** cwd after the git-root auto-correction for worktree mode. */
+	resolvedCtx: TeamContext;
+	directAgent: boolean;
+	team: TeamConfig;
+	workflow: WorkflowConfig;
+	/** All discovered agents (needed by the execution phase for executeTeamRun). */
+	agents: ReturnType<typeof allAgents>;
+	analysisParam: { text?: string; error?: string; source: "inline" | "path" | "none" };
+	isDynamicWorkflow: boolean;
+	/** params.runKind only when the workflow is dynamic (else undefined). */
+	effectiveRunKind: TeamToolParamsValue["runKind"];
+	/** normalizeSkillOverride result — matches TeamRunManifest.skillOverride. */
+	skillOverride: false | string[] | undefined;
+}
+
+/**
+ * Validate the run params into a {@link RunIntent}.
+ *
+ * Error-precedence order (asserted by run tests, do not reorder):
+ * goal/params → crew-init → worktree precondition → agent → team →
+ * workflow → analysis → workflow-validation. Non-validation branches
+ * (chain dispatch, goal-wrap delegation) are handled inside.
+ */
+export async function validateRunIntent(
+	params: TeamToolParamsValue,
+	ctx: TeamContext,
+): Promise<{ kind: "ok"; intent: RunIntent } | { kind: "error"; result: PiTeamsToolResult }> {
+	const goal = params.goal ?? params.task;
+	if (!goal)
+		return {
+			kind: "error",
+			result: result(
+				paramRequired("run", "goal or task", "{ action: 'run', goal: '<what to achieve>' }"),
+				{ action: "run", status: "error" },
+				true,
+			),
+		};
+	const intentPrefix = goal.length > 60 ? `${goal.slice(0, 57)}...` : goal;
+
+	// P0: Ensure .crew directory structure exists before creating any manifests.
+	// Latch shared across concurrent `team` tool calls (see loadCrewInit).
+	const workingDir = ctx.cwd ?? process.cwd();
+	const { ensureCrewDirectory } = await loadCrewInit();
+	await ensureCrewDirectory(workingDir);
+
+	// WORKTREE FIX: If worktree mode is needed but cwd is not a git repo,
+	// auto-correct to the nearest git repo root.
+	let resolvedCtx = ctx;
+	if (workingDir) {
+		try {
+			const gitRoot = await findGitRootAsync(workingDir);
+			if (gitRoot && gitRoot !== workingDir) {
+				resolvedCtx = { ...ctx, cwd: gitRoot };
+			}
+		} catch {
+			// cwd is not in a git repo — validate below if worktree mode is needed
+		}
+	}
+
+	// WORKTREE PRECONDITION CHECK: validate git repo exists and is clean
+	// BEFORE creating the run manifest.
+	if (params.workspaceMode === "worktree") {
+		let gitRoot: string | undefined;
+		try {
+			gitRoot = await findGitRootAsync(resolvedCtx.cwd);
+		} catch {
+			// not a git repo
+		}
+		if (!gitRoot) {
+			return {
+				kind: "error",
+				result: result(
+					`Worktree mode requires a git repository. '${resolvedCtx.cwd}' is not inside a git repo.\nUse workspaceMode: 'single' or run from a git repository.`,
+					{ action: "run", status: "error" },
+					true,
+				),
+			};
+		}
+		// Check if clean leader is required (can be disabled via config)
+		const preCheckConfig = loadConfig(resolvedCtx.cwd);
+		if (preCheckConfig.config.requireCleanWorktreeLeader !== false) {
+			try {
+				await assertCleanLeaderAsync(gitRoot);
+			} catch (err) {
+				const msg = errorMessage(err);
+				return {
+					kind: "error",
+					result: result(
+						`${msg}\nCommit or stash changes before using worktree mode, or use workspaceMode: 'single'.`,
+						{ action: "run", status: "error" },
+						true,
+					),
+				};
+			}
+		}
+	}
+
+	const teams = allTeams(discoverTeams(resolvedCtx.cwd));
+	const workflows = allWorkflows(discoverWorkflows(resolvedCtx.cwd));
+	const agents = allAgents(discoverAgents(resolvedCtx.cwd));
+	const directAgent = params.agent ? agents.find((item) => item.name === params.agent) : undefined;
+	if (params.agent && !directAgent)
+		return { kind: "error", result: result(`Agent '${params.agent}' not found.`, { action: "run", status: "error" }, true) };
+	const teamName = params.team ?? "default";
+	const team = directAgent
+		? {
+				name: `direct-${directAgent.name}`,
+				description: `Direct subagent run for ${directAgent.name}`,
+				source: "builtin" as const,
+				filePath: "<generated>",
+				roles: [
+					{
+						name: params.role ?? "agent",
+						agent: directAgent.name,
+						description: directAgent.description,
+					},
+				],
+				defaultWorkflow: "direct-agent",
+				workspaceMode: params.workspaceMode,
+			}
+		: teams.find((item) => item.name === teamName);
+	if (!team) return { kind: "error", result: result(`Team '${teamName}' not found.`, { action: "run", status: "error" }, true) };
+	// BUG-44 (github #44): `chain` is a dispatcher-only workflow — see the
+	// comment in run.ts; chain steps forwarding params.workflow fall back to
+	// the team's default workflow.
+	const workflowName = directAgent
+		? "direct-agent"
+		: params.workflow === "chain" && !params.chain
+			? (team.defaultWorkflow ?? "default")
+			: (params.workflow ?? team.defaultWorkflow ?? "default");
+	const baseWorkflow = directAgent
+		? {
+				name: "direct-agent",
+				description: `Direct task for ${directAgent.name}`,
+				source: "builtin" as const,
+				filePath: "<generated>",
+				steps: [
+					{
+						id: "01_agent",
+						role: params.role ?? "agent",
+						task: "{goal}",
+						model: params.model,
+						reads: params.analysis || params.analysisPath ? ["analysis.md"] : undefined,
+					},
+				],
+			}
+		: workflows.find((item) => item.name === workflowName);
+	if (!baseWorkflow)
+		return { kind: "error", result: result(`Workflow '${workflowName}' not found.`, { action: "run", status: "error" }, true) };
+
+	// ANALYSIS CHANNEL (round-X Y1): resolve analysis text BEFORE
+	// createRunManifest so validation errors fail-fast (no orphan run state).
+	const analysisParam = resolveAnalysisText(params, resolvedCtx.cwd);
+	if (analysisParam.error) return { kind: "error", result: result(analysisParam.error, { action: "run", status: "error" }, true) };
+
+	// LAZY: dodge the jiti ESM/CJS interop TDZ race on the static `import { expandParallelResearchWorkflow }` (issue #28, RFC 17). Multi-line form breaks scripts/check-lazy-imports.mjs.
+	const { expandParallelResearchWorkflow: expandParallelResearch } = await import("../../runtime/scheduling/parallel-research.ts");
+	const workflow = directAgent ? baseWorkflow : expandParallelResearch(baseWorkflow, resolvedCtx.cwd);
+	const isDynamicWorkflow =
+		!directAgent && (workflow as import("../../workflows/workflow-config.ts").WorkflowConfig).runtime === "dynamic";
+	if (params.runKind !== undefined && !isDynamicWorkflow) {
+		logInternalError(
+			"team-tool.run.runKindIgnored",
+			new Error(`Ignoring runKind='${params.runKind}' because workflow '${workflow.name}' is not dynamic.`),
+			undefined,
+			"warn",
+		);
+	}
+
+	// PREFLIGHT (advisory only, since v0.9.15) — informational notes per the
+	// rule in .crew/knowledge.md "pi-crew USAGE THRESHOLD RULE". Never blocks.
+	if (!directAgent) {
+		// LAZY: defer preflight-validator import until a team run requests it.
+		const { validateWorkflowUsage } = await import("../../workflows/preflight-validator.ts");
+		const preflight = validateWorkflowUsage(workflow, {
+			force: params.force === true,
+		});
+		const icon = preflight.level === "warn" ? "⚠️ " : preflight.level === "note" ? "ℹ️  " : "";
+		const tag = preflight.level.toUpperCase();
+		console.warn(`${icon}[team-tool.preflight] ${tag}: ${preflight.message} (workflow=${workflow.name})`);
+		if (preflight.suggestion) {
+			console.warn(`[team-tool.preflight] → ${preflight.suggestion}`);
+		}
+	}
+
+	// RFC v0.5 vision: goal-wrap. If .crew/config.json has
+	// goalWrap[workflow.name].enabled=true, route to a goal loop where this
+	// workflow runs as the worker turn. Only for eligible builtins. When
+	// goal-wrap is unsafe for this workflow we fall through (never block the
+	// run the user asked for).
+	if (!directAgent && workflow.source === "builtin" && isGoalWrapEnabled(resolvedCtx.cwd, workflow.name)) {
+		const decision = shouldGoalWrap(resolvedCtx.cwd, workflow);
+		if (decision.enabled) {
+			if (analysisParam.text) {
+				console.warn(
+					`[team-tool.run] analysis param is ignored by goal-wrapped run (workflow=${workflow.name}). The analysis artifact will not be written.`,
+				);
+			}
+			return {
+				kind: "error",
+				result: await startGoalWrappedRun(params, ctx, workflow, goal),
+			};
+		}
+		if (decision.message) {
+			logInternalError(
+				"team-tool.run.goalWrapBypassed",
+				new Error(decision.message),
+				`workflow=${workflow.name} reason=${decision.reason}`,
+			);
+		}
+	}
+
+	// LAZY: dodge the jiti ESM/CJS interop TDZ race (issue #28, RFC 17).
+	const { validateWorkflowForTeam: validateWorkflow } = await import("../../workflows/validate-workflow.ts");
+	const validationErrors = validateWorkflow(workflow, team);
+	if (validationErrors.length > 0) {
+		return {
+			kind: "error",
+			result: result(
+				[
+					`Workflow '${workflow.name}' is not valid for team '${team.name}':`,
+					...validationErrors.map((error) => `- ${error}`),
+				].join("\n"),
+				{ action: "run", status: "error" },
+				true,
+			),
+		};
+	}
+
+	// LAZY: dodge the jiti ESM/CJS interop TDZ race (issue #28, RFC 17).
+	const { normalizeSkillOverride: normalizeSkill } = await import("../../runtime/skill-instructions.ts");
+	const skillOverride = normalizeSkill(params.skill);
+
+	return {
+		kind: "ok",
+		intent: {
+			goal,
+			intentPrefix,
+			resolvedCtx,
+			directAgent: !!directAgent,
+			team,
+			workflow,
+			agents,
+			analysisParam,
+			isDynamicWorkflow,
+			effectiveRunKind: isDynamicWorkflow ? params.runKind : undefined,
+			skillOverride,
+		},
+	};
+}