pi-crew 0.8.13 → 0.9.0

package/src/runtime/dynamic-workflow-context.ts

@@ -0,0 +1,450 @@
+/**
+ * dynamic-workflow-context.ts — WorkflowCtx facade for dynamic-workflow scripts (P2).
+ *
+ * Spec: research-findings/goal-workflow/00-SPEC.md §3.2
+ * Plan: 07-PLAN.md v3 P2 + §0b G4 + §0c C4/C5/C7.
+ *
+ * The `ctx` object passed to a `.dwf.ts` script's `export default async function(ctx)`.
+ * Capability-locked: exposes ONLY the documented methods (no raw manifest/process/require).
+ * The script host (dynamic-workflow-runner.ts) loads the script via jiti in plain module
+ * scope with a FROZEN WorkflowCtx. v1 has NO vm sandbox (review H-2): the script CAN
+ * reach `process`/`require`/`import` directly — the frozen ctx is a contract surface,
+ * not a security boundary. `.dwf.ts` = postinstall-equivalent trust. isolated-vm v1.5.
+ *
+ * `agent()` resolution (§0b G4): 4-tier precedence
+ *   1. opts.agent (explicit name) — bypasses team lookup
+ *   2. team.roles.find(r => r.name === role)?.agent → allAgents lookup
+ *   3. allAgents(discoverAgents(cwd)).find(a => a.name === role)  (role name == agent name)
+ *   4. synthesize minimal AgentConfig (source:"dynamic", systemPrompt:"You are {role}.")
+ *
+ * Isolation (§0b G3 / report 05 §C.4): worker output → artifact file; `agent()` returns
+ * structured data + writes a side artifact. The script holds results in JS vars; only
+ * `setResult()` reaches the main context.
+ */
+
+import { runChildPi } from "./child-pi.ts";
+import { parsePiJsonOutput } from "./pi-json-output.ts";
+import { extractStructuredResult } from "./result-extractor.ts";
+import { mapConcurrent } from "./parallel-utils.ts";
+import { Semaphore } from "./semaphore.ts";
+import { executeWithRetry } from "./retry-executor.ts";
+import { allAgents, discoverAgents } from "../agents/discover-agents.ts";
+import { writeArtifact } from "../state/artifact-store.ts";
+import { appendMailboxMessage, readMailbox } from "../state/mailbox.ts";
+import { renderPlanTemplate } from "./plan-templates.ts";
+import { logInternalError } from "../utils/internal-error.ts";
+import { randomBytes } from "node:crypto";
+import type { AgentConfig } from "../agents/agent-config.ts";
+import type { TeamConfig } from "../teams/team-config.ts";
+import type { TeamRunManifest } from "../state/types.ts";
+
+export interface AgentCallOpts {
+	prompt: string;
+	/** Role name (resolved via G4 4-tier chain) OR explicit agent name. */
+	role?: string;
+	/** Explicit agent name — bypasses team-role lookup (tier 1). */
+	agent?: string;
+	description?: string;
+	model?: string;
+	skill?: string[] | false;
+	maxTurns?: number;
+	graceTurns?: number;
+	/** Dependency artifact paths injected into the agent prompt. */
+	inputs?: string[];
+	/** Disable ALL tools for this call (Pi `--no-tools`, §0c C6). Use for pure-judgment /
+	 *  verdict steps where the agent must answer directly without exploring, e.g.
+	 *  `ctx.review()`'s JSON-verdict call. Without this, role-based tools (read/grep/bash)
+	 *  apply and the model may loop exploring instead of answering. */
+	disableTools?: boolean;
+	/** Override the resolved agent's system prompt. Use when the call needs a different
+	 *  persona/output-format than the role's defined agent — e.g. `ctx.review()` needs a
+	 *  JSON-verdict judge, but the user's reviewer.md agent is a markdown code-reviewer.
+	 *  When set, the resolved agent's systemPrompt is replaced entirely. */
+	systemPrompt?: string;
+}
+
+export interface AgentResult {
+	ok: boolean;
+	text: string;
+	structured?: unknown;
+	usage?: { input?: number; output?: number; cost?: number; turns?: number };
+	runId?: string;
+	taskId?: string;
+	artifactPath?: string;
+	error?: string;
+	durationMs?: number;
+}
+
+export interface WorkflowCtx {
+	cwd: string;
+	runId: string;
+	goal?: string;
+	/** Spawn one agent, await result. Concurrency enforced by ctx.semaphore. */
+	agent(opts: AgentCallOpts): Promise<AgentResult>;
+	/** Bounded fan-out preserving order (wraps mapConcurrent). */
+	fanOut<T>(items: T[], limit: number, fn: (item: T, i: number) => Promise<AgentResult>): Promise<AgentResult[]>;
+	/** Run a reviewer agent over an artifact; parse {outcome, feedback}. §3.2. */
+	review(taskId: string, reviewerRole?: string, opts?: { content?: string; artifactPath?: string; disableTools?: boolean }): Promise<{ outcome: "accept" | "reject" | "changes_requested"; feedback: string }>;
+	/** Re-run a task with feedback (wraps executeWithRetry). */
+	retry(taskId: string, opts?: { feedback?: string }): Promise<AgentResult>;
+	/** Send a mailbox message to another agent/leader. */
+	mail(to: string, body: string, opts?: { kind?: string; taskId?: string; replyTo?: string; replyDeadline?: number }): string;
+	/** Block until N mailbox replies arrive or deadline. ~10 LOC net-new (report 05 §G.4). */
+	gatherReplies(messageIds: string[], deadlineMs: number): Promise<unknown[]>;
+	/** Render a built-in plan template (full-implementation / standard-review). */
+	renderTemplate(name: string, vars: Record<string, string>): unknown;
+	/** Persistent variables (revived intermediate-store). */
+	vars: Record<string, unknown>;
+	/** Mark the final result. ONLY this artifact reaches the main context. */
+	setResult(artifactPath: string, meta?: Record<string, unknown>): void;
+	semaphore: Semaphore;
+	/** Abort signal (cancel/stop). */
+	signal: AbortSignal;
+}
+
+export interface MakeWorkflowCtxOptions {
+	concurrency?: number;
+	signal: AbortSignal;
+	team?: TeamConfig;
+	modelOverride?: string;
+}
+
+/**
+ * Resolve a role/agent name to a full AgentConfig (§0b G4 4-tier precedence).
+ * Module-local — NOT promoted to a shared module (keeps P2 isolated from the
+ * load-bearing team-runner path).
+ */
+export function resolveAgentForRole(
+	roleName: string | undefined,
+	opts: { explicitAgent?: string; team?: TeamConfig; cwd: string },
+): AgentConfig {
+	const cwd = opts.cwd;
+	// Tier 1: explicit agent name.
+	if (opts.explicitAgent) {
+		const found = allAgents(discoverAgents(cwd)).find((a) => a.name === opts.explicitAgent);
+		if (found) return found;
+		// Fall through to synthesize if the named agent doesn't exist (P2-friendly).
+	}
+	// Tier 2: team.roles[].agent lookup.
+	if (opts.team) {
+		const role = opts.team.roles.find((r) => r.name === roleName);
+		if (role) {
+			const byAgentName = allAgents(discoverAgents(cwd)).find((a) => a.name === role.agent);
+			if (byAgentName) return byAgentName;
+		}
+	}
+	// Tier 3: discoverAgents by role name (role name == agent name).
+	if (roleName) {
+		const byRoleName = allAgents(discoverAgents(cwd)).find((a) => a.name === roleName);
+		if (byRoleName) return byRoleName;
+	}
+	// Tier 4: synthesize a minimal AgentConfig.
+	const name = opts.explicitAgent ?? roleName ?? "executor";
+	return synthesizeAgentConfig(name);
+}
+
+/** Synthesize a minimal AgentConfig (§0c C7: source:"dynamic", not "synthetic"). */
+export function synthesizeAgentConfig(name: string, model?: string): AgentConfig {
+	return {
+		name,
+		description: `Synthesized agent for dynamic workflow (${name}).`,
+		source: "dynamic",
+		filePath: `<dynamic-workflow>`,
+		systemPrompt: `You are ${name}.`,
+		model,
+		tools: [],
+		inheritProjectContext: false,
+		inheritSkills: false,
+	};
+}
+
+/** Build the WorkflowCtx facade. Capability-locked: only documented methods exposed. */
+export function makeWorkflowCtx(manifest: TeamRunManifest, opts: MakeWorkflowCtxOptions): WorkflowCtx {
+	const concurrency = Math.max(1, opts.concurrency ?? 4);
+	const semaphore = new Semaphore(concurrency);
+	let finalResult: { artifactPath: string; meta?: Record<string, unknown> } | undefined;
+
+	const ctx: WorkflowCtx = {
+		cwd: manifest.cwd,
+		runId: manifest.runId,
+		goal: manifest.goal,
+		signal: opts.signal,
+		semaphore,
+		async agent(call: AgentCallOpts): Promise<AgentResult> {
+			await semaphore.acquire();
+			const started = Date.now();
+			try {
+				const agentConfig = resolveAgentForRole(call.role, {
+					explicitAgent: call.agent,
+					team: opts.team,
+					cwd: manifest.cwd,
+				});
+				// §0c C6: per-call disableTools override. When set, force Pi `--no-tools` so the
+				// agent answers directly without exploring. Applied AFTER role resolution so it
+				// wins over any role-defined tools.
+				let effectiveAgent = call.disableTools === true ? { ...agentConfig, disableTools: true, tools: [] } : agentConfig;
+				// Per-call systemPrompt override (replaces the resolved agent's persona/output-format).
+				// Used by ctx.review() to force a JSON-verdict judge instead of the role's markdown reviewer.
+				if (call.systemPrompt !== undefined) {
+					effectiveAgent = { ...effectiveAgent, systemPrompt: call.systemPrompt };
+				}
+				const task = composeAgentTask(call);
+				const childResult = await runChildPi({
+					cwd: manifest.cwd,
+					task,
+					agent: effectiveAgent,
+					model: call.model ?? opts.modelOverride ?? agentConfig.model,
+					skillPaths: undefined, // skills resolved via agent config + team-role plumbing
+					maxTurns: call.maxTurns,
+					graceTurns: call.graceTurns,
+					signal: opts.signal,
+					artifactsRoot: manifest.artifactsRoot,
+					runId: manifest.runId,
+					role: call.role ?? call.agent,
+				});
+				if (childResult.exitCode !== 0 || childResult.error) {
+					return { ok: false, text: "", error: childResult.error ?? `exit ${childResult.exitCode}`, durationMs: Date.now() - started };
+				}
+				const parsed = parsePiJsonOutput(childResult.stdout);
+				let text = parsed.finalText ?? "";
+				// Round-11 test fix: parsePiJsonOutput only extracts text from pi event stream
+				// ({type:"message_end", message:{role:"assistant", content:[...]}}). When the
+				// agent emits plain JSON, plain text, or a different format, finalText is empty.
+				// Fallback to a more permissive extraction that handles multiple output shapes.
+				if (!text.trim()) {
+					text = extractTextFallback(childResult.stdout);
+				}
+				const extracted = extractStructuredResult(text);
+				// Write a side artifact for audit/isolation (§0b G3).
+				const rel = `wf/${Date.now()}-${randomBytes(4).toString("hex")}.md`;
+				const artifact = writeArtifact(manifest.artifactsRoot, {
+					kind: "result",
+					relativePath: rel,
+					content: text,
+					producer: "dynamic-workflow",
+				});
+				return {
+					ok: true,
+					text,
+					structured: extracted.structured ? extracted.data : undefined,
+					usage: parsed.usage,
+					artifactPath: artifact.path,
+					durationMs: Date.now() - started,
+				};
+			} catch (error) {
+				logInternalError("dynamic-workflow-context.agent", error, `runId=${manifest.runId}`);
+				return { ok: false, text: "", error: error instanceof Error ? error.message : String(error), durationMs: Date.now() - started };
+			} finally {
+				semaphore.release();
+			}
+		},
+		async fanOut<T>(items: T[], limit: number, fn: (item: T, i: number) => Promise<AgentResult>): Promise<AgentResult[]> {
+			return mapConcurrent(items, Math.max(1, limit), fn);
+		},
+		async review(taskId: string, reviewerRole = "reviewer", reviewOpts?: { content?: string; artifactPath?: string; disableTools?: boolean }): Promise<{ outcome: "accept" | "reject" | "changes_requested"; feedback: string }> {
+			// review() is a VERDICT step: it must produce a parseable JSON {outcome, feedback}, not a
+			// free-form markdown review. The resolved reviewer agent (e.g. ~/.pi/agent/agents/reviewer.md)
+			// has tools (read/grep/bash) + a markdown-output system prompt. Without disableTools, the
+			// reviewer explores the repo looking for the task's work, loops, and gets killed (exit 143)
+			// before producing JSON — leaving text="" and the fallback verdict. Default: disableTools so
+			// the reviewer judges the provided content (or taskId context) directly.
+			const disableTools = reviewOpts?.disableTools !== false; // default true
+			const workContext = reviewOpts?.content
+				? `\n\nWork to review:\n"""\n${reviewOpts.content}\n"""`
+				: reviewOpts?.artifactPath
+					? `\n\nRead the work from artifact: ${reviewOpts.artifactPath}`
+					: "";
+			const res = await ctx.agent({
+				role: reviewerRole,
+				prompt: `You are reviewing the work for task '${taskId}'.${workContext}\n\nEvaluate the work and respond with ONLY a single JSON object, no prose, no markdown:\n{"outcome":"accept|reject|changes_requested","feedback":"<one-paragraph explanation>"}\n\n- "accept": work is complete and correct.\n- "reject": work is fundamentally wrong.\n- "changes_requested": work needs revision (explain what in feedback).`,
+				maxTurns: 3,
+				disableTools,
+				systemPrompt: "You are a JSON verdict judge. You output ONLY a single JSON object with keys \"outcome\" (one of accept/reject/changes_requested) and \"feedback\" (a concise explanation). Never output prose, markdown, or code fences. Begin your response with { and end with }.",
+			});
+			const extracted = res.structured as { outcome?: string; feedback?: string } | undefined;
+			if (extracted && typeof extracted.outcome === "string" && typeof extracted.feedback === "string") {
+				const outcome = (extracted.outcome === "accept" || extracted.outcome === "reject" || extracted.outcome === "changes_requested")
+					? extracted.outcome
+					: "changes_requested";
+				return { outcome, feedback: extracted.feedback };
+			}
+			// Fallback (round-11 runtime): many models (e.g. MiniMax-M3) ignore JSON-output
+			// instructions and produce a prose review instead. Rather than report an
+			// unparseable verdict, run a tiny judge call that converts the prose review into a
+			// JSON verdict. This guarantees ctx.review() always returns a structured verdict
+			// regardless of the reviewer's output format. Skipped when the reviewer produced
+			// no text at all (genuine failure).
+			if (res.text.trim()) {
+				const judge = await ctx.agent({
+					role: reviewerRole,
+					prompt: `Convert the following code review into a verdict JSON. Read the review and decide the outcome.\n\nREVIEW:\n"""\n${res.text.slice(0, 4000)}\n"""\n\nRespond with ONLY a JSON object:\n{"outcome":"accept|reject|changes_requested","feedback":"<concise summary>"}\n- accept: review found no real issues.\n- reject: review found critical/fundamental problems.\n- changes_requested: review found issues that need fixing.`,
+					maxTurns: 1,
+					disableTools: true,
+					systemPrompt: "You output ONLY a single JSON object with keys outcome and feedback. Begin with { and end with }. Never output prose.",
+				});
+				const judged = judge.structured as { outcome?: string; feedback?: string } | undefined;
+				if (judged && typeof judged.outcome === "string" && typeof judged.feedback === "string") {
+					const outcome = (judged.outcome === "accept" || judged.outcome === "reject" || judged.outcome === "changes_requested")
+						? judged.outcome
+						: "changes_requested";
+					return { outcome, feedback: judged.feedback };
+				}
+			}
+			// Tier-3 sentiment fallback (round-11): when neither the reviewer nor the judge
+			// produced JSON (common with MiniMax-M3, GLM, which ignore JSON-output
+			// instructions), classify the outcome from the REVIEWER's prose sentiment. We use
+			// the reviewer's text (not the judge's terse output) because the original review is
+			// the richest sentiment signal. This keeps outcome ACCURATE (accept vs reject vs
+			// changes_requested) even when no JSON is ever produced — without it, outcome was
+			// always the hardcoded 'changes_requested' default (e.g. correct code was
+			// misclassified as needing changes).
+			if (res.text.trim()) {
+				return { outcome: classifyReviewOutcome(res.text), feedback: res.text };
+			}
+			return { outcome: "changes_requested", feedback: res.text || "(reviewer produced no parseable verdict)" };
+		},
+		async retry(taskId: string, retryOpts?: { feedback?: string }): Promise<AgentResult> {
+			return executeWithRetry(
+				async () => ctx.agent({
+					role: "executor",
+					prompt: `Re-do task '${taskId}'.${retryOpts?.feedback ? ` Feedback: ${retryOpts.feedback}` : ""}`,
+				}),
+				{ maxAttempts: 3, backoffMs: 0, jitterRatio: 0, exponentialFactor: 1 },
+			);
+		},
+		mail(to: string, body: string, mailOpts?: { kind?: string; taskId?: string; replyTo?: string; replyDeadline?: number }): string {
+			const msg = appendMailboxMessage(manifest, {
+				direction: "outbox",
+				from: "dynamic-workflow",
+				to,
+				body,
+				kind: (mailOpts?.kind as never) ?? "message",
+				taskId: mailOpts?.taskId,
+				replyTo: mailOpts?.replyTo,
+				replyDeadline: mailOpts?.replyDeadline,
+			});
+			return msg.id;
+		},
+		async gatherReplies(messageIds: string[], deadlineMs: number): Promise<unknown[]> {
+			const deadline = Date.now() + deadlineMs;
+			while (Date.now() < deadline) {
+				const inbox = readMailbox(manifest, "inbox");
+				const got = inbox.filter((m) => m.replyTo && messageIds.includes(m.replyTo));
+				if (got.length >= messageIds.length) return got;
+				await new Promise((r) => setTimeout(r, 500));
+				if (opts.signal.aborted) return inbox.filter((m) => m.replyTo && messageIds.includes(m.replyTo));
+			}
+			return readMailbox(manifest, "inbox").filter((m) => m.replyTo && messageIds.includes(m.replyTo));
+		},
+		renderTemplate(name: string, vars: Record<string, string>): unknown {
+			return renderPlanTemplate(name, vars);
+		},
+		vars: {} as Record<string, unknown>,
+		setResult(artifactPath: string, meta?: Record<string, unknown>): void {
+			finalResult = { artifactPath, meta };
+		},
+	};
+
+	// Attach the final-result slot via a non-enumerable getter so the runner can read it
+	// without exposing a mutation surface on the ctx the script sees.
+	Object.defineProperty(ctx, "__finalResult", {
+		get: () => finalResult,
+		enumerable: false,
+	});
+	return ctx;
+}
+
+/** Read the final result set by the script (runner-only; not part of the public ctx surface). */
+export function getWorkflowFinalResult(ctx: WorkflowCtx): { artifactPath: string; meta?: Record<string, unknown> } | undefined {
+	return (ctx as unknown as { __finalResult?: { artifactPath: string; meta?: Record<string, unknown> } }).__finalResult;
+}
+
+/** Compose the agent task: prompt + optional dependency-input context block. */
+function composeAgentTask(call: AgentCallOpts): string {
+	if (!call.inputs?.length) return call.prompt;
+	const block = call.inputs.map((p) => `- ${p}`).join("\n");
+	return `${call.prompt}\n\n## Inputs (artifact paths)\n${block}`;
+}
+
+/**
+ * Classify a review outcome from prose when no JSON was produced (round-11 tier-3/4 fallback).
+ * Scans the reviewer's prose for sentiment signals to decide accept / reject / changes_requested.
+ * This keeps the outcome ACCURATE for models that ignore JSON-output instructions.
+ *
+ * Decision order: reject (critical issues) → accept (explicit approval) → changes_requested (default).
+ * reject is checked first because a review can mention both "correctly" (describing existing code)
+ * AND "critical bug" (the verdict) — the verdict signal must win.
+ */
+export function classifyReviewOutcome(prose: string): "accept" | "reject" | "changes_requested" {
+	const text = prose.toLowerCase();
+	// Strong negative signals → reject. These indicate fundamental/critical problems.
+	const rejectSignals = [
+		"\breject\b", "fundamentally", "completely broken", "totally broken",
+		"critical bug", "critical issue", "critical flaw", "security vulnerability",
+		"does not work", "doesn't work", "will not work", "fails to",
+		"unacceptable", "must not be merged", "do not merge", "wrong approach",
+		"logically incorrect", "incorrectly implements", "returns the opposite",
+		"subtraction instead of addition", "opposite of its intended",
+	];
+	// Acceptance signals → accept. These indicate explicit approval with no real issues.
+	const acceptSignals = [
+		"\baccept\b", "looks good", "well done", "no issues", "no real issues",
+		"no problems", "no concerns", "nothing to change", "ready to merge",
+		"lgtm", "ship it", "correctly implements", "correctly returns",
+		"works as expected", "works correctly", "no bugs", "no defects",
+		"meets all requirements", "all requirements met", "passes all",
+		"is correct", "are correct", "no changes needed", "no changes required",
+		"no further changes", "nothing more to", "complete and correct", "sound implementation",
+	];
+	const hasReject = rejectSignals.some((sig) => new RegExp(sig).test(text));
+	const hasAccept = acceptSignals.some((sig) => new RegExp(sig).test(text));
+	if (hasReject) return "reject";
+	if (hasAccept) return "accept";
+	return "changes_requested";
+}
+
+/**
+ * Round-11 test fix: permissive text extraction for ctx.agent().
+ * parsePiJsonOutput only handles the canonical pi event stream. When the child emits
+ * a different shape, finalText is empty. This fallback walks the JSON tree looking
+ * for any text-shaped string at any depth, then returns the longest one (typically
+ * the final assistant response).
+ */
+export function extractTextFallback(stdout: string): string {
+	const trimmed = stdout.trim();
+	if (!trimmed) return "";
+	const candidates: string[] = [];
+	const collect = (value: unknown): void => {
+		if (typeof value === "string") {
+			const t = value.trim();
+			// Skip very short strings and JSON-ish strings
+			if (t.length >= 2 && !t.startsWith("{") && !t.startsWith("[") && !/^[\d.]+$/.test(t)) {
+				candidates.push(t);
+			}
+		} else if (Array.isArray(value)) {
+			for (const item of value) collect(item);
+		} else if (value && typeof value === "object") {
+			for (const v of Object.values(value as Record<string, unknown>)) collect(v);
+		}
+	};
+	// 1. Try parsing each line as JSON, walk tree
+	for (const line of trimmed.split("\n")) {
+		const lineTrim = line.trim();
+		if (!lineTrim.startsWith("{")) continue;
+		try {
+			const obj = JSON.parse(lineTrim);
+			collect(obj);
+		} catch { /* skip */ }
+	}
+	// 2. If nothing from JSON, try plain text (longest non-empty line that's not JSON)
+	if (candidates.length === 0) {
+		for (const line of trimmed.split("\n")) {
+			const l = line.trim();
+			if (l.length >= 3 && !l.startsWith("{") && !l.startsWith("[") && !l.startsWith("=")) candidates.push(l);
+		}
+	}
+	// 3. Return the longest candidate (typically the final answer)
+	if (candidates.length === 0) return "";
+	candidates.sort((a, b) => b.length - a.length);
+	return candidates[0];
+}

package/src/runtime/dynamic-workflow-runner.ts

@@ -0,0 +1,180 @@
+/**
+ * dynamic-workflow-runner.ts — Script-driven workflow runtime (P2).
+ *
+ * Spec: research-findings/goal-workflow/00-SPEC.md §3.3
+ * Plan: 07-PLAN.md v3 P2 + §0c C5 (resolveRealContainedPath).
+ *
+ * Loads a `.dwf.ts` script's default export, transpiles it via jiti (the existing
+ * TS loader used by async-runner.ts), and executes it with a FROZEN WorkflowCtx.
+ *
+ * HONEST v1 TRUST MODEL (review H-2): vm.runInNewContext is NOT used in v1 — the
+ * script runs in plain module scope with full access to require/import/process.
+ * The 'capability-locked WorkflowCtx' is the documented contract surface, NOT a
+ * sandbox. A script can reach process/require via constructor walking or direct
+ * import. `.dwf.ts` files MUST be commit-reviewed (postinstall-equivalent trust).
+ * The path-allowlist (resolveRealContainedPath) limits WHERE scripts load from,
+ * not WHAT they can do. isolated-vm (real V8 isolate) is planned for v1.5.
+ * See docs/dynamic-workflows.md for the full threat model.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { resolveRealContainedPath } from "../utils/safe-paths.ts";
+import { appendEvent } from "../state/event-log.ts";
+import { writeArtifact } from "../state/artifact-store.ts";
+import { logInternalError } from "../utils/internal-error.ts";
+import { makeWorkflowCtx, getWorkflowFinalResult } from "./dynamic-workflow-context.ts";
+import { projectCrewRoot, userPiRoot, packageRoot } from "../utils/paths.ts";
+import type { DynamicWorkflowConfig } from "../workflows/workflow-config.ts";
+import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
+
+export interface RunDynamicWorkflowInput {
+	manifest: TeamRunManifest;
+	workflow: DynamicWorkflowConfig;
+	/** Optional team for role resolution (G4 tier 2). */
+	team?: import("../teams/team-config.ts").TeamConfig;
+	signal: AbortSignal;
+	concurrency?: number;
+	modelOverride?: string;
+}
+
+export interface RunDynamicWorkflowResult {
+	manifest: TeamRunManifest;
+	tasks: TeamTaskState[];
+}
+
+/** The signature a .dwf.ts default export must satisfy. */
+export type DynamicWorkflowScript = (ctx: import("./dynamic-workflow-context.ts").WorkflowCtx) => Promise<void> | void;
+
+/**
+ * Resolve + validate the script path against the allowlist of workflow dirs (§0c C5).
+ * Returns the real contained path or throws.
+ */
+function resolveScriptPath(workflow: DynamicWorkflowConfig, cwd: string): string {
+	const crewRoot = projectCrewRoot(cwd);
+	// Allowlist: the script must resolve inside one of the workflow discovery dirs.
+	// (discover-workflows.ts only reads from packageRoot/workflows, userPiRoot/workflows,
+	//  and projectCrewRoot/workflows — so the script already came from an allowed dir,
+	//  but we still validate containment to defeat symlink traversal.)
+	// Fix round-5 P1: the round-4 P2-5 fix over-corrected to a SINGLE base (crewRoot/workflows).
+	// But discoverWorkflows() reads from THREE dirs (builtin, user, project). Use the same bases
+	// so user/builtin dynamic workflows aren't rejected.
+	const allowedBases = [
+		join(projectCrewRoot(cwd), "workflows"),
+		join(userPiRoot(), "workflows"),
+		join(packageRoot(), "workflows"),
+	];
+	for (const base of allowedBases) {
+		try {
+			const real = resolveRealContainedPath(base, workflow.filePath);
+			if (real) return real;
+		} catch {
+			// not contained in this base — try next
+		}
+	}
+	// Not contained in any allowed base — refuse (do NOT fall back to the raw path).
+	throw new Error(`Dynamic workflow '${workflow.filePath}' is outside the allowed workflows directories (${allowedBases.join(", ")}). Refusing to load.`);
+}
+
+/**
+ * Transpile + load the .dwf.ts default export. Uses jiti (already a dep) for TS→JS.
+ * Returns the default export function or throws.
+ */
+async function loadWorkflowModule(scriptPath: string): Promise<DynamicWorkflowScript> {
+	// jiti is the same loader async-runner.ts uses (resolveTypeScriptLoader). We require it
+	// lazily so this module stays importable in environments without jiti (type-only consumers).
+	// Fix round-4: use createRequire(import.meta.url) so `require` works under the strip-types
+	// loader fallback (Node ≥ 22.6) where bare `require` is not defined in ESM scope.
+	const { createRequire } = await import("node:module");
+	const require = createRequire(import.meta.url);
+	// eslint-disable-next-line @typescript-eslint/no-require-imports
+	const createJiti = require("jiti").default ?? require("jiti");
+	const jiti = createJiti(import.meta.url, { interopDefault: true });
+	const mod = await jiti(scriptPath);
+	const fn = (mod as { default?: unknown }).default ?? mod;
+	if (typeof fn !== "function") {
+		throw new Error(`Dynamic workflow '${scriptPath}' must export a default async function(ctx).`);
+	}
+	return fn as DynamicWorkflowScript;
+}
+
+/**
+ * Run the dynamic workflow script. Loads it, builds the ctx, executes, and returns
+ * {manifest, tasks} with the manifest updated to a terminal status + result artifact.
+ */
+export async function runDynamicWorkflow(input: RunDynamicWorkflowInput): Promise<RunDynamicWorkflowResult> {
+	const { manifest, workflow, signal } = input;
+	const eventsPath = manifest.eventsPath;
+	const scriptPath = resolveScriptPath(workflow, manifest.cwd);
+
+	appendEvent(eventsPath, { type: "dwf.started", runId: manifest.runId, data: { workflow: workflow.name, script: scriptPath } });
+
+	const ctx = makeWorkflowCtx(manifest, {
+		concurrency: input.concurrency ?? workflow.maxConcurrency ?? 4,
+		signal,
+		team: input.team,
+		modelOverride: input.modelOverride,
+	});
+
+	// Freeze the ctx so the script cannot add/override capability methods (§0c C4).
+	const frozenCtx = Object.freeze(ctx);
+
+	try {
+		const script = await loadWorkflowModule(scriptPath);
+		// Round-11 test fix (runtime): hard timeout on script execution.
+		// Without this, scripts that spawn long-running child processes (e.g., `spawn("pi", ...)`)
+		// hang forever. The ctx.signal.timeout is cooperative only — it fires AbortSignal,
+		// it does NOT kill the script. Promise.race with a hard timeout at least returns an
+		// error so the runner doesn't hang. The spawned child process is leaked, but the
+		// dynamic-workflow returns failure promptly. (v1.5: use Worker threads to actually kill.)
+		const SCRIPT_TIMEOUT_MS = Number.parseInt(process.env.PI_CREW_DWF_SCRIPT_TIMEOUT_MS ?? "", 10) || 600_000; // 10 min default
+		let timeoutHandle: NodeJS.Timeout | undefined;
+		const timeoutPromise = new Promise<never>((_, reject) => {
+			timeoutHandle = setTimeout(() => {
+				reject(new Error(`Dynamic workflow script timed out after ${SCRIPT_TIMEOUT_MS}ms. The script may have spawned a child process that did not exit. Check for spawn/exec calls without proper stdio handling.`));
+			}, SCRIPT_TIMEOUT_MS);
+			timeoutHandle.unref?.();
+		});
+		try {
+			await Promise.race([script(frozenCtx), timeoutPromise]);
+		} finally {
+			if (timeoutHandle) clearTimeout(timeoutHandle);
+		}
+	} catch (error) {
+		logInternalError("dynamic-workflow-runner.run", error, `runId=${manifest.runId}, workflow=${workflow.name}`);
+		appendEvent(eventsPath, { type: "dwf.failed", runId: manifest.runId, data: { error: error instanceof Error ? error.message : String(error) } });
+		// Re-throw so background-runner's error handling marks the run failed.
+		throw error;
+	}
+
+	const final = getWorkflowFinalResult(ctx);
+	const finalText = final ? readFinalArtifact(final.artifactPath) : `(dynamic workflow '${workflow.name}' completed without calling ctx.setResult())`;
+
+	// Write a summary artifact mirroring the static-workflow summary.md contract (run.ts reads this).
+	const summary = writeArtifact(manifest.artifactsRoot, {
+		kind: "result",
+		relativePath: "summary.md",
+		content: finalText,
+		producer: "dynamic-workflow",
+	});
+
+	appendEvent(eventsPath, { type: "dwf.completed", runId: manifest.runId, data: { workflow: workflow.name, summaryArtifact: summary.path } });
+
+	const updatedManifest: TeamRunManifest = {
+		...manifest,
+		status: "completed",
+		summary: finalText.slice(0, 2000),
+		updatedAt: new Date().toISOString(),
+		artifacts: [...manifest.artifacts, summary],
+	};
+	return { manifest: updatedManifest, tasks: [] };
+}
+
+function readFinalArtifact(artifactPath: string): string {
+	try {
+		return readFileSync(artifactPath, "utf-8");
+	} catch (error) {
+		logInternalError("dynamic-workflow-runner.readFinal", error, `artifactPath=${artifactPath}`);
+		return `(failed to read final artifact ${artifactPath})`;
+	}
+}