pi-crew 0.8.14 → 0.9.0

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

@@ -0,0 +1,405 @@
+/**
+ * team-tool/goal.ts — Handler for `team action='goal'` (P0 skeleton).
+ *
+ * Sub-actions (anchor sub-action pattern, team-tool.ts:1224):
+ *   - start   : create GoalLoopState + spawn background goal-loop process
+ *   - status  : show objective/state/turn/budget/last verdict
+ *   - pause   : cooperative pause (flip GoalLoopState.state)
+ *   - resume  : cooperative resume (re-spawn next turn) — P0: status-only stub
+ *   - stop    : cooperative cancel + handleCancel(currentRunId)
+ *   - step    : run exactly one more turn (debug) — P0: status-only stub
+ *   - clear   : remove GoalLoopState file
+ *
+ * Plan: 07-PLAN.md v3 §0c C10 (assertSafePathId, evaluatorModel required, ≤4000 chars),
+ *       §0c C11 (control path: cooperative flag + handleCancel(currentRunId) via abortOwned).
+ */
+
+import { result, type TeamContext } from "./context.ts";
+import { createRunPaths, saveRunManifest } from "../../state/state-store.ts";
+import { appendEvent } from "../../state/event-log.ts";
+import { spawnBackgroundTeamRun } from "../../subagents/async-entry.ts";
+import { GoalStore } from "../../runtime/goal-state-store.ts";
+import { logInternalError } from "../../utils/internal-error.ts";
+import { snapshotManifests } from "../../runtime/verification-integrity.ts";
+import { acquireWorkspaceLock, isWorkspaceBusy, type WorkspaceLockHandle } from "../../runtime/workspace-lock.ts";
+import type { GoalLoopState, GoalLoopStatus, TeamRunManifest } from "../../state/types.ts";
+import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
+
+const MAX_GOAL_OBJECTIVE_CHARS = 4000;
+
+interface GoalSubActionInput {
+	params: TeamToolParamsValue;
+	ctx: TeamContext;
+	store: GoalStore;
+}
+
+/** Extract a clean objective string from params (goalObjective || goal || task), validated. */
+function readObjective(params: TeamToolParamsValue): string {
+	const raw = (params.config?.objective as string | undefined) ?? params.goal ?? params.task ?? "";
+	const objective = typeof raw === "string" ? raw.trim() : "";
+	if (!objective) {
+		throw new Error("`goal start` requires a non-empty objective (config.objective, goal, or task).");
+	}
+	if (objective.length > MAX_GOAL_OBJECTIVE_CHARS) {
+		throw new Error(`Objective too long: ${objective.length} > ${MAX_GOAL_OBJECTIVE_CHARS} chars (Claude/Codex parity).`);
+	}
+	return objective;
+}
+
+/** Validate evaluatorModel is set (required per §0c C10 — no silent default). */
+function readEvaluatorModel(params: TeamToolParamsValue): string {
+	const model = (params.config?.evaluatorModel as string | undefined) ?? (params.config?.model as string | undefined) ?? params.model;
+	if (!model || typeof model !== "string") {
+		throw new Error("`goal start` requires config.evaluatorModel (the goal-judge model). No silent default.");
+	}
+	return model;
+}
+
+function formatGoalStatus(goal: GoalLoopState): string {
+	const last = goal.verdicts[goal.verdicts.length - 1];
+	const budgetPct = goal.budgetTotal ? `${Math.round((goal.budgetUsed / goal.budgetTotal) * 100)}%` : "n/a";
+	return [
+		`Goal ${goal.goalId} [${goal.state}]`,
+		`  objective: ${goal.objective.slice(0, 200)}${goal.objective.length > 200 ? "…" : ""}`,
+		`  turn: ${goal.turnsUsed}/${goal.maxTurns}   budget: ${goal.budgetUsed}/${goal.budgetTotal ?? "∞"} (${budgetPct})`,
+		`  evaluator: ${goal.evaluatorModel}   worker: ${goal.workerAgent ?? "executor"}`,
+		last ? `  last verdict (turn ${last.turn}): ${last.achieved ? "ACHIEVED" : "not-achieved"} — ${last.reason.slice(0, 300)}` : "  (no verdicts yet)",
+		goal.nextTurnFeedback ? `  next-turn feedback: ${goal.nextTurnFeedback.slice(0, 200)}` : "",
+		goal.currentRunId ? `  current turn runId: ${goal.currentRunId}` : "",
+	].filter(Boolean).join("\n");
+}
+
+/** `goal start` — create state + spawn background process (P0: writes state; spawn wiring TBD per host). */
+async function handleStart(input: GoalSubActionInput): Promise<ReturnType<typeof result>> {
+	const { params, ctx, store } = input;
+	try {
+		const objective = readObjective(params);
+		const evaluatorModel = readEvaluatorModel(params);
+		const cwd = ctx.cwd;
+		const goalId = store.createGoalId();
+		const ownerSessionId = ctx.sessionId ?? "unknown";
+		const now = new Date().toISOString();
+		const maxTurns = typeof params.config?.maxTurns === "number" && params.config.maxTurns > 0
+			? params.config.maxTurns
+			: 20; // Claude/Codex parity default
+		// P1d (RFC v0.5 §P1d): budget is REQUIRED. Either an explicit budgetTotal (>=1000, enforced
+		// by schema) OR an explicit budgetUnlimited:true opt-out (audit-logged). No silent unbounded
+		// default — without a cap the loop could spend unboundedly across many turns × workers.
+		const budgetUnlimited = params.config?.budgetUnlimited === true;
+		const hasBudgetTotal = typeof params.budgetTotal === "number" && params.budgetTotal >= 1000;
+		if (!budgetUnlimited && !hasBudgetTotal) {
+			throw new Error("`goal start` requires either config.budgetTotal (>=1000, schema-enforced) OR config.budgetUnlimited:true (audit-logged opt-out). No silent unbounded-spend default.");
+		}
+		// Cold-review #2 nit: reject the mutually-exclusive combination. If both are set the
+		// runner silently lets budgetUnlimited win, surprising the user.
+		if (budgetUnlimited && hasBudgetTotal) {
+			throw new Error("`goal start`: config.budgetTotal and config.budgetUnlimited are mutually exclusive. Set exactly one.");
+		}
+		// P1g (cold-review #2 BLOCKING fix): pre-check the workspace lock BEFORE spawning. If another
+		// goal already owns this cwd's lock, fail-fast with a clear error (the runner would otherwise
+		// queue silently inside the background process). isWorkspaceBusy peeks the lockfile without
+		// acquiring. The authoritative acquisition happens in runGoalLoop.
+		const busyOwner = isWorkspaceBusy(cwd);
+		if (busyOwner) {
+			throw new Error(`Workspace '${cwd}' is already locked by goal '${busyOwner}'. Concurrent goals on the same single-workspace cwd are serialized to prevent edit clobbering. Stop the other goal first, or use a separate workspace.`);
+		}
+		const verification = params.config?.verification as { commands: string[]; allowManualEvidence?: boolean; mode?: string } | undefined;
+		const isTextOnly = verification?.mode === "text-only";
+		// P1a (RFC v0.5 §P1a): take manifest-integrity snapshot at start IF verification.commands
+		// declared. For text-only mode (no objective oracle), mark "none-text-only" explicitly so
+		// the runner knows no snapshot guard applies. No auto-detect (B2: auto-detect is a confused
+		// deputy — the user MUST declare verification explicitly).
+		let verificationIntegrity: import("../../state/types.ts").GoalLoopState["verificationIntegrity"];
+		if (isTextOnly || !verification?.commands?.length) {
+			verificationIntegrity = "none-text-only";
+		} else {
+			try {
+				const snap = snapshotManifests(cwd);
+				verificationIntegrity = { snapshot: snap, takenAt: now };
+			} catch (error) {
+				logInternalError("goal.start.integritySnapshot", error, `goalId=${goalId}`);
+				// Non-fatal: proceed without integrity guard (downgraded to text-only behavior).
+				verificationIntegrity = "none-text-only";
+			}
+		}
+		const goalState: import("../../state/types.ts").GoalLoopState = {
+			goalId,
+			ownerSessionId,
+			objective,
+			scope: typeof params.config?.scope === "string" ? params.config.scope : undefined,
+			verification,
+			state: "running",
+			maxTurns,
+			turnsUsed: 0,
+			budgetTotal: hasBudgetTotal ? (params.budgetTotal as number) : undefined,
+			budgetUnlimited: budgetUnlimited || undefined,
+			budgetWarning: typeof params.budgetWarning === "number" ? params.budgetWarning : 0.8,
+			budgetAbort: typeof params.budgetAbort === "number" ? params.budgetAbort : 0.95,
+			budgetUsed: 0,
+			verificationIntegrity,
+			evaluatorModel,
+			workerModel: typeof params.model === "string" ? params.model : undefined,
+			workerAgent: typeof params.config?.workerAgent === "string" ? params.config.workerAgent : undefined,
+			team: typeof params.team === "string" ? params.team : undefined,
+			cwd,
+			verdicts: [],
+			history: [],
+			createdAt: now,
+			updatedAt: now,
+		};
+		store.save(goalState);
+
+		// ── Spawn the background goal-loop process (Fix P0-1 v2) ────────────────
+		// Convention: the goal-loop manifest's runId IS the goalId, so background-runner's
+		// `case "goal-loop"` can load GoalLoopState via `store.load(manifest.runId)`.
+		// Fix P0-1: build paths via createRunPaths(cwd, goalId) so ALL paths
+		// (stateRoot/artifactsRoot/eventsPath/tasksPath) are consistent with runId=goalId.
+		// The previous fix overrode runId AFTER createRunManifest (which used a random id),
+		// so the manifest was written to runs/<randomId>/ but background-runner looked for
+		// runs/<goalId>/ → "Run not found" → silent death. (Review #2 F1.)
+		const paths = createRunPaths(cwd, goalId);
+		const now2 = new Date().toISOString();
+		const goalLoopManifest: TeamRunManifest = {
+			schemaVersion: 1,
+			runId: goalId, // paths.runId === goalId by construction
+			sessionId: ownerSessionId,
+			team: `goal-${goalId}`,
+			workflow: "goal-loop",
+			goal: objective,
+			status: "queued",
+			workspaceMode: "single",
+			createdAt: now2,
+			updatedAt: now2,
+			cwd,
+			stateRoot: paths.stateRoot,
+			artifactsRoot: paths.artifactsRoot,
+			tasksPath: paths.tasksPath,
+			eventsPath: paths.eventsPath,
+			artifacts: [],
+			ownerSessionId,
+			runKind: "goal-loop",
+		};
+		saveRunManifest(goalLoopManifest);
+		appendEvent(paths.eventsPath, { type: "goal.loop_start", runId: goalId, data: { goalId, objective, maxTurns, statePath: `${cwd}/.crew/state/goals/${goalId}.json` } });
+
+		try {
+			const spawned = await spawnBackgroundTeamRun(goalLoopManifest);
+			const pid = spawned.pid ?? 0;
+			const withAsync = { ...goalState, async: { pid, logPath: spawned.logPath, spawnedAt: new Date().toISOString() } };
+			store.save(withAsync);
+			return result(
+				`Goal loop started (background pid=${pid}).\n${formatGoalStatus(withAsync)}\n\nNext: \`team action='goal' config.subAction='status' config.goalId='${goalId}'\`. The loop runs up to ${maxTurns} turns, judging each against the objective. Log: ${spawned.logPath}`,
+				{ action: "goal", status: "ok", data: { goalId, state: goalState.state, maxTurns, pid } },
+				false,
+			);
+		} catch (spawnError) {
+			const message = spawnError instanceof Error ? spawnError.message : String(spawnError);
+			store.setStatus(goalId, "blocked", paths.eventsPath);
+			return result(`goal start: state saved but background spawn failed: ${message}`, { action: "goal", status: "error", data: { goalId } }, true);
+		}
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		return result(`goal start failed: ${message}`, { action: "goal", status: "error" }, true);
+	}
+}
+
+/** `goal status` — show current state (and list goals if no goalId). */
+function handleStatus(input: GoalSubActionInput): ReturnType<typeof result> {
+	const { params, store } = input;
+	const goalId = (params.config?.goalId as string | undefined) ?? (params.config?.goalId as string | undefined);
+	if (goalId) {
+		const goal = store.load(goalId);
+		if (!goal) return result(`Goal '${goalId}' not found.`, { action: "goal", status: "error" }, true);
+		return result(formatGoalStatus(goal), { action: "goal", status: "ok", data: { goalId, state: goal.state, turnsUsed: goal.turnsUsed } }, false);
+	}
+	const goals = store.list();
+	if (goals.length === 0) return result("No goals found. Start one with `team action='goal' config.subAction='start' config.objective='...' config.evaluatorModel='...'`.", { action: "goal", status: "ok" }, false);
+	return result(`Goals (${goals.length}):\n\n${goals.map(formatGoalStatus).join("\n\n")}`, { action: "goal", status: "ok", data: { count: goals.length } }, false);
+}
+
+/** Cooperative pause/resume/stop/clear — flip GoalLoopState.state. */
+function assertGoalOwnership(goal: GoalLoopState, ctx: TeamContext, action: string): ReturnType<typeof result> | undefined {
+	// Fix round-6 A01: goal sub-actions must check session ownership (like handleCancel's abortOwned).
+	// status (read-only) is allowed for any session; mutating actions require ownership or force.
+	const owner = goal.ownerSessionId;
+	const current = ctx.sessionId;
+	// Fix round-7: ownership check must fire for running AND paused goals (paused still has
+	// an in-flight turn potentially). Previously only 'running' was gated — a paused goal
+	// with an active currentRunId could be stop/cancelled by a foreign session without force.
+	if (owner && current && owner !== current && (goal.state === "running" || goal.state === "paused")) {
+		return result(`Goal '${goal.goalId}' belongs to session '${owner}' (you are '${current}') and is still running. Use force:true to override.`, { action, status: "error", data: { goalId: goal.goalId, ownerSessionId: owner } }, true);
+	}
+	return undefined;
+}
+
+function handleStateFlip(input: GoalSubActionInput, nextState: GoalLoopStatus, label: string): ReturnType<typeof result> {
+	const { params, ctx, store } = input;
+	const goalId = params.config?.goalId as string | undefined;
+	if (!goalId) return result(`${label} requires config.goalId.`, { action: "goal", status: "error" }, true);
+	const existing = store.load(goalId);
+	if (!existing) return result(`Goal '${goalId}' not found.`, { action: "goal", status: "error" }, true);
+	if (params.force !== true) {
+		const denied = assertGoalOwnership(existing, ctx, "goal");
+		if (denied) return denied;
+	}
+	const eventsPath = createRunPaths(ctx.cwd, goalId).eventsPath;
+	const updated = store.setStatus(goalId, nextState, eventsPath);
+	if (!updated) return result(`Goal '${goalId}' not found.`, { action: "goal", status: "error" }, true);
+	return result(`Goal ${goalId} ${label} (state='${updated.state}').`, { action: "goal", status: "ok", data: { goalId, state: updated.state } }, false);
+}
+
+/**
+ * `goal stop`/`cancel`/`clear`/`reset` — cooperative flag + cancel the in-flight turn (H-5).
+ * Flips GoalLoopState.state='cancelled' so the loop exits at the next turn boundary,
+ * AND calls handleCancel(currentRunId) to kill a running turn immediately. §0c C11.
+ */
+async function handleStop(input: GoalSubActionInput): Promise<ReturnType<typeof result>> {
+	const { params, ctx, store } = input;
+	const goalId = params.config?.goalId as string | undefined;
+	if (!goalId) return result("stop requires config.goalId.", { action: "goal", status: "error" }, true);
+	const eventsPath = createRunPaths(ctx.cwd, goalId).eventsPath;
+	const before = store.load(goalId);
+	if (!before) return result(`Goal '${goalId}' not found.`, { action: "goal", status: "error" }, true);
+	if (params.force !== true) {
+		const denied = assertGoalOwnership(before, ctx, "goal");
+		if (denied) return denied;
+	}
+	const updated = store.setStatus(goalId, "cancelled", eventsPath)!;
+	// If a turn is mid-flight, cancel it now (not just at the next turn boundary).
+	let cancelMsg = "";
+	if (updated.currentRunId) {
+		try {
+			const { handleCancel } = await import("./cancel.ts");
+			const cancelResult = await handleCancel({ action: "cancel", runId: updated.currentRunId, force: true, config: { intent: "user requested goal stop" } }, ctx);
+			cancelMsg = ` In-flight turn ${updated.currentRunId} cancel: ${(cancelResult.content[0] as { text?: string } | undefined)?.text ?? "ok"}.`;
+		} catch (error) {
+			cancelMsg = ` (in-flight turn ${updated.currentRunId} cancel failed: ${error instanceof Error ? error.message : String(error)}; the loop will still exit at the next turn boundary.)`;
+		}
+	}
+	return result(`Goal ${goalId} stopped (state='cancelled').${cancelMsg}`, { action: "goal", status: "ok", data: { goalId, state: "cancelled", cancelledRunId: updated.currentRunId } }, false);
+}
+
+/**
+ * `goal resume` (P1b, RFC v0.5 §P1b): promote from P0 stub to real handler.
+ * Resumes a paused OR stuck goal via CAS (state -> "running") + injects the user's
+ * optional hint into nextTurnFeedback + re-spawns the background loop.
+ *
+ * No double-turn-execution: the loop is single-threaded per goal, and any in-flight
+ * turn (from before the pause) completes normally; nextTurnFeedback is read at turn
+ * N+1's composeGoalPrompt, so the hint applies to N+1, not the in-flight turn.
+ *
+ * `goal start`'s workspace-lock ownership is reused: a resumed goal does NOT re-acquire
+ * the lock (the lock was held for the goal's lifetime at start). If the original goal
+ * had released its lock (e.g. it crashed and the lock was reclaimed), the resumed
+ * loop will fail-fast at the first worker turn that needs it — surfaced via events.
+ */
+async function handleResume(input: GoalSubActionInput): Promise<ReturnType<typeof result>> {
+	const { params, ctx, store } = input;
+	const goalId = params.config?.goalId as string | undefined;
+	if (!goalId) return result("resume requires config.goalId.", { action: "goal", status: "error" }, true);
+	const existing = store.load(goalId);
+	if (!existing) return result(`Goal '${goalId}' not found.`, { action: "goal", status: "error" }, true);
+	if (params.force !== true) {
+		const denied = assertGoalOwnership(existing, ctx, "goal");
+		if (denied) return denied;
+	}
+	// Only paused/stuck goals are resumable. (running = already running; terminal states
+	// achieved/max_turns/blocked/cancelled/budget_exceeded are done.)
+	if (existing.state !== "paused" && existing.state !== "stuck") {
+		return result(`Goal '${goalId}' is in state '${existing.state}' — only 'paused' or 'stuck' goals can be resumed.`, { action: "goal", status: "error", data: { goalId, state: existing.state } }, true);
+	}
+	const hint = typeof params.config?.hint === "string" ? params.config.hint.trim() : undefined;
+	const eventsPath = createRunPaths(ctx.cwd, goalId).eventsPath;
+	// CAS: only resume if the state is still what we loaded. A concurrent stop/cancel wins.
+	const updated = store.compareAndSetStatus(goalId, existing.state, "running", eventsPath);
+	if (!updated) {
+		return result(`Goal '${goalId}' state changed concurrently (resume aborted; another actor won the race).`, { action: "goal", status: "error", data: { goalId } }, true);
+	}
+	// Inject the hint as next-turn feedback (applies to turn N+1's worker prompt).
+	let withHint = updated;
+	if (hint) {
+		withHint = store.patch(goalId, { nextTurnFeedback: hint }, eventsPath) ?? updated;
+	}
+	appendEvent(eventsPath, { type: "goal.resumed", runId: goalId, data: { goalId, fromState: existing.state, hint: hint?.slice(0, 200) } });
+	// Re-spawn the background loop. The loop checks goal.state === "running" before each
+	// turn; since we just set it to running, it proceeds.
+	try {
+		const manifest: TeamRunManifest = {
+			schemaVersion: 1,
+			runId: goalId,
+			sessionId: existing.ownerSessionId,
+			team: `goal-${goalId}`,
+			workflow: "goal-loop",
+			goal: existing.objective,
+			status: "queued",
+			workspaceMode: "single",
+			createdAt: existing.createdAt,
+			updatedAt: new Date().toISOString(),
+			cwd: existing.cwd,
+			stateRoot: createRunPaths(existing.cwd, goalId).stateRoot,
+			artifactsRoot: createRunPaths(existing.cwd, goalId).artifactsRoot,
+			tasksPath: createRunPaths(existing.cwd, goalId).tasksPath,
+			eventsPath,
+			artifacts: [],
+			ownerSessionId: existing.ownerSessionId,
+			runKind: "goal-loop",
+		};
+		const spawned = await spawnBackgroundTeamRun(manifest);
+		return result(`Goal ${goalId} resumed from '${existing.state}' (background pid=${spawned.pid ?? 0}).${hint ? ` Hint injected for next turn.` : ""}`, { action: "goal", status: "ok", data: { goalId, state: "running", fromState: existing.state, pid: spawned.pid } }, false);
+	} catch (spawnError) {
+		const msg = spawnError instanceof Error ? spawnError.message : String(spawnError);
+		// Cold-review #2 nit: roll back to the PRIOR state (paused/stuck) so the user can retry
+		// '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, { type: "goal.resume_spawn_failed", runId: goalId, data: { goalId, error: msg, rolledBackTo: existing.state } });
+		return result(`Goal ${goalId} background re-spawn failed: ${msg}. State rolled back to '${existing.state}'. Retry 'goal resume' to re-attempt.`, { action: "goal", status: "error", data: { goalId, spawnFailed: true, state: existing.state } }, true);
+	}
+}
+
+/** `team action='goal'` dispatch. */
+export async function handleGoal(params: TeamToolParamsValue, ctx: TeamContext): Promise<ReturnType<typeof result>> {
+	const store = new GoalStore(ctx.cwd);
+	const subAction = typeof params.config?.subAction === "string" ? params.config.subAction : "status";
+	const input: GoalSubActionInput = { params, ctx, store };
+	switch (subAction) {
+		case "start":
+			return handleStart(input);
+		case "status":
+			return handleStatus(input);
+		case "pause":
+			return handleStateFlip(input, "paused", "paused");
+		case "resume":
+			return await handleResume(input);
+		case "stop":
+		case "cancel":
+		case "reset":
+			return await handleStop(input);
+		case "clear": {
+			// Fix P1-3 + round-5 P2: remove the goal file. But refuse if the loop is still
+			// running (would leave a zombie background process). Require stop first.
+			const clearGoalId = params.config?.goalId as string | undefined;
+			if (!clearGoalId) return result("clear requires config.goalId.", { action: "goal", status: "error" }, true);
+			const existing = store.load(clearGoalId);
+			if (!existing) return result(`Goal '${clearGoalId}' not found (already cleared?).`, { action: "goal", status: "error" }, true);
+			if (params.force !== true) {
+				const denied = assertGoalOwnership(existing, ctx, "goal");
+				if (denied) return denied;
+			}
+			if (existing.state === "running" || existing.state === "paused") {
+				return result(`Goal '${clearGoalId}' is still ${existing.state}. Stop it first (team action='goal' subAction='stop' goalId='${clearGoalId}'), then clear.`, { action: "goal", status: "error", data: { goalId: clearGoalId, state: existing.state } }, true);
+			}
+			const removed = store.remove(clearGoalId);
+			if (!removed) return result(`Goal '${clearGoalId}' could not be removed.`, { action: "goal", status: "error" }, true);
+			return result(`Goal '${clearGoalId}' cleared (file removed).`, { action: "goal", status: "ok", data: { goalId: clearGoalId, cleared: true } }, false);
+		}
+		case "step":
+			// P0: step is a status-only stub — single-turn execution lands with P1.
+			return handleStatus(input);
+		default:
+			return result(`Unknown goal subAction '${subAction}'. Known: start, status, pause, resume, stop, step, clear.`, { action: "goal", status: "error" }, true);
+	}
+}
+
+// Touch logInternalError so the import is not tree-shaken in type-only builds (defensive).
+void logInternalError;

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

@@ -46,8 +46,17 @@ import { expandParallelResearchWorkflow } from "../../runtime/parallel-research.
  * module body evaluates exactly once regardless of fanout. Same pattern as
  * runtime-warmup.ts / the v0.8.1 peer-dep latch, applied to this specific
  * dynamic-import race site.
+ *
+ * IMPORTANT: must be `var` (not `let`) — when this module is loaded via
+ * `jiti.import()` (the pi extension loader) wrapped in an async function,
+ * `let` causes a Temporal Dead Zone error because the function declaration
+ * below is hoisted and can be called before this `let` line executes under
+ * certain microtask schedules. `var` is hoisted with `undefined`, avoiding
+ * the TDZ. Round-11 cold review reproduction:
+ *   `team action='run' workflow='<dynamic>'` → "Cannot access 'crewInitPromise'
+ *    before initialization" at run.ts load. See RFC 17 + commit fixing this.
  */
-let crewInitPromise: Promise<typeof import("../../state/crew-init.ts")> | undefined;
+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");
@@ -62,6 +71,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import type { PiTeamsToolResult } from "../tool-result.ts";
 import { buildParentContext, result, type TeamContext } from "./context.ts";
+import { isGoalWrapEnabled, shouldGoalWrap, startGoalWrappedRun } from "./goal-wrap.ts";
 import { effectiveRunConfig } from "./config-patch.ts";
 
 function tailFile(filePath: string, maxBytes = 4096): string | undefined {
@@ -186,7 +196,33 @@ export async function handleRun(params: TeamToolParamsValue, ctx: TeamContext):
 		steps: [{ id: "01_agent", role: params.role ?? "agent", task: "{goal}", model: params.model }],
 	} : workflows.find((item) => item.name === workflowName);
 	if (!baseWorkflow) return result(`Workflow '${workflowName}' not found.`, { action: "run", status: "error" }, true);
-	const workflow = directAgent ? baseWorkflow : expandParallelResearchWorkflow(baseWorkflow, resolvedCtx.cwd);
+	// LAZY: dodge the jiti ESM/CJS interop TDZ race on the static `import { expandParallelResearchWorkflow }` above (issue #28, RFC 17). At call time the module body has fully evaluated, so the dynamic import returns a live binding.
+	const { expandParallelResearchWorkflow: expandParallelResearch } = await import("../../runtime/parallel-research.ts");
+	const workflow = directAgent ? baseWorkflow : expandParallelResearch(baseWorkflow, resolvedCtx.cwd);
+
+	// 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 (judge → feedback → redo
+	// until achieved). Only for eligible builtins (implementation, fast-fix, default). Per-workflow
+	// toggle; OFF by default. See goal-wrap.ts.
+	//
+	// SAFETY (commit b57bad3): multi-step workflows crash non-deterministically
+	// in the background goal-loop process (V8/libuv race in team-runner batch
+	// transition). When goal-wrap is unsafe for this workflow, we do NOT error
+	// out — we fall through to the normal team-run path so the user still gets
+	// the run they asked for. The disabled reason is logged for traceability.
+	if (!directAgent && workflow.source === "builtin" && isGoalWrapEnabled(resolvedCtx.cwd, workflow.name)) {
+		const decision = shouldGoalWrap(resolvedCtx.cwd, workflow);
+		if (decision.enabled) {
+			return await startGoalWrappedRun(params, ctx, workflow, goal);
+		}
+		// goal-wrap disabled for this workflow — fall through silently to normal
+		// team-run path. Log the reason so it's discoverable in events.jsonl and
+		// debug logs. This preserves the trace of WHY goal-wrap was bypassed for
+		// a given run (vs. just disappearing without explanation).
+		if (decision.message) {
+			logInternalError("team-tool.run.goalWrapBypassed", new Error(decision.message), `workflow=${workflow.name} reason=${decision.reason}`);
+		}
+	}
 
 	// Check if this is a pipeline workflow - special handling for multi-stage execution
 	const isPipelineWorkflow = workflowName === "pipeline" && !directAgent;
@@ -225,12 +261,16 @@ export async function handleRun(params: TeamToolParamsValue, ctx: TeamContext):
 		].join("\n"), { action: "run", status: "ok" }, false);
 	}
 
-	const validationErrors = validateWorkflowForTeam(workflow, team);
+	// LAZY: dodge the jiti ESM/CJS interop TDZ race on the static `import { validateWorkflowForTeam }` above (issue #28, RFC 17).
+	const { validateWorkflowForTeam: validateWorkflow } = await import("../../workflows/validate-workflow.ts");
+	const validationErrors = validateWorkflow(workflow, team);
 	if (validationErrors.length > 0) {
 		return result([`Workflow '${workflow.name}' is not valid for team '${team.name}':`, ...validationErrors.map((error) => `- ${error}`)].join("\n"), { action: "run", status: "error" }, true);
 	}
 
-	const skillOverride = normalizeSkillOverride(params.skill);
+	// LAZY: dodge the jiti ESM/CJS interop TDZ race on the static `import { normalizeSkillOverride }` above (issue #28, RFC 17).
+	const { normalizeSkillOverride: normalizeSkill } = await import("../../runtime/skill-instructions.ts");
+	const skillOverride = normalizeSkill(params.skill);
 	const { manifest, tasks, paths } = createRunManifest({
 		cwd: resolvedCtx.cwd,
 		team,
@@ -238,6 +278,7 @@ export async function handleRun(params: TeamToolParamsValue, ctx: TeamContext):
 		goal,
 		workspaceMode: params.workspaceMode,
 		ownerSessionId: ctx.sessionId,
+		runKind: params.runKind,
 	});
 	const goalArtifact = writeArtifact(paths.artifactsRoot, {
 		kind: "prompt",
@@ -249,6 +290,64 @@ export async function handleRun(params: TeamToolParamsValue, ctx: TeamContext):
 	atomicWriteJson(paths.manifestPath, updatedManifest);
 	registerActiveRun(updatedManifest);
 
+	// P2: dynamic-workflow dispatch — when the resolved workflow is a .dwf.ts (runtime:"dynamic"),
+	// run it via runDynamicWorkflow instead of the static executeTeamRun path. The script
+	// orchestrates subagents via ctx.agent(); only ctx.setResult() reaches the main context.
+	// Placed AFTER manifest creation so runId/paths/artifactsRoot are available.
+	if (!directAgent && (workflow as import("../../workflows/workflow-config.ts").DynamicWorkflowConfig).runtime === "dynamic") {
+		const { runDynamicWorkflow } = await import("../../runtime/dynamic-workflow-runner.ts");
+		// Re-synthesize a dynamic-team (§0c C9) for role resolution.
+		const dwfTeam: import("../../teams/team-config.ts").TeamConfig = {
+			name: `dwf-${manifest.runId.slice(-12)}`,
+			description: `Dynamic workflow run for ${workflow.name}`,
+			source: "dynamic",
+			filePath: "<dynamic-workflow>",
+			roles: [{ name: "worker", agent: params.agent ?? "executor" }],
+			workspaceMode: "single",
+		};
+		const dwfManifest: import("../../state/types.ts").TeamRunManifest = {
+			...updatedManifest,
+			runKind: "dynamic-workflow",
+			team: dwfTeam.name,
+		};
+		atomicWriteJson(paths.manifestPath, dwfManifest);
+		try {
+			let dwfResult: import("../../runtime/dynamic-workflow-runner.ts").RunDynamicWorkflowResult | undefined;
+			try {
+				dwfResult = await runDynamicWorkflow({
+					manifest: dwfManifest,
+					workflow: workflow as import("../../workflows/workflow-config.ts").DynamicWorkflowConfig,
+					team: dwfTeam,
+					signal: ctx.signal ?? AbortSignal.timeout(3_600_000),
+					modelOverride: params.model,
+				});
+			} catch (runnerError) {
+				// Round-11 runtime fix: persist manifest with status=failed when runner throws
+				// (e.g., script timeout, script syntax error, async failure). Previously the
+				// manifest stayed at 'queued' indefinitely, leaving an orphan state file.
+				const failureReason = runnerError instanceof Error ? runnerError.message : String(runnerError);
+				const failedManifest = { ...dwfManifest, status: "failed" as const, summary: `Dynamic workflow '${workflow.name}' failed: ${failureReason}`.slice(0, 2000), updatedAt: new Date().toISOString() };
+				atomicWriteJson(paths.manifestPath, failedManifest);
+				return result(
+					`Dynamic workflow '${workflow.name}' failed: ${failureReason}`,
+					{ action: "run", status: "error", runId: failedManifest.runId, artifactsRoot: failedManifest.artifactsRoot },
+					true,
+				);
+			}
+			// Round-10 runtime-test fix: persist the updated manifest with status=completed
+			// so status queries / cancel / cleanup see the real state. Previously run.ts
+			// returned the result without atomicWriteJson, leaving manifest at 'queued' forever.
+			atomicWriteJson(paths.manifestPath, dwfResult.manifest);
+			return result(
+				`Dynamic workflow '${workflow.name}' completed.\n${dwfResult.manifest.summary ?? ""}`,
+				{ action: "run", status: dwfResult.manifest.status === "failed" ? "error" : "ok", runId: dwfResult.manifest.runId, artifactsRoot: dwfResult.manifest.artifactsRoot },
+				dwfResult.manifest.status === "failed",
+			);
+		} finally {
+			unregisterActiveRun(dwfManifest.runId);
+		}
+	}
+
 	const loadedConfig = loadConfig(resolvedCtx.cwd);
 	// DX (Round 16 F4): surface config errors/warnings instead of silently
 	// proceeding with defaults. Non-blocking: emit a config.warning event so