@fyeeme/pi-dynamic-workflows 0.1.1

package/src/determinism/ast-guard.ts

@@ -0,0 +1,196 @@
+/**
+ * Determinism AST guard — the load-time counterpart of CC.s vm-sandbox determinism ban.
+ *
+ * Workflow `.ts` files are loaded via jiti (a real module, not a vm-sandboxed
+ * script string), so we cannot sandbox at eval time the way CC does. Instead
+ * we parse the source BEFORE jiti loads it and reject any reference to the
+ * non-deterministic APIs: `Date.now`, `Math.random`, `new Date()`, `Date()`, and
+ * the Web Crypto randomness surface (`crypto.randomUUID`/`randomBytes`/
+ * `getRandomValues`), `performance.now`, and `process.hrtime`. Reading "now" or
+ * randomness inside a workflow body would make its output — and therefore the
+ * resume cache key derived from it — unstable across runs.
+ *
+ * Uses the typescript compiler's `createSourceFile` (pure parse, no type-check
+ * program) — the only reliable way to walk TypeScript syntax without a custom
+ * parser. Same patterns CC.s vm-sandbox flags (Date.now/Math.random), plus the `Date()`
+ * no-arg call (merged in from the alternative loader.ts implementation during
+ * Task 5 unification — that version caught this case, the original did not).
+ */
+import {
+	type CallExpression,
+	type ElementAccessExpression,
+	type Identifier,
+	type NewExpression,
+	type Node,
+	type NoSubstitutionTemplateLiteral,
+	type ParenthesizedExpression,
+	type PropertyAccessExpression,
+	type StringLiteral,
+	ScriptTarget,
+	SyntaxKind,
+	createSourceFile,
+} from "typescript";
+import { WorkflowError } from "../errors.ts";
+
+export type DeterminismViolationKind =
+	| "date_now"
+	| "math_random"
+	| "new_date"
+	| "date_call"
+	| "crypto_random"
+	| "performance_now"
+	| "process_hrtime";
+
+export interface DeterminismViolation {
+	readonly kind: DeterminismViolationKind;
+	readonly line: number;
+	readonly column: number;
+	readonly source: string;
+}
+
+export const BANNED_API_MESSAGE: Record<DeterminismViolationKind, string> = {
+	date_now: "Date.now() is non-deterministic — pass a timestamp into the runtime instead",
+	math_random: "Math.random() is non-deterministic — use a sequence counter or pass a seed in",
+	new_date: "new Date() with no args is non-deterministic — pass a timestamp explicitly",
+	date_call: "Date() with no args is non-deterministic — pass an explicit format or timestamp",
+	crypto_random:
+		"crypto.randomUUID/randomBytes/getRandomValues is non-deterministic — use a seeded RNG or pass randomness in",
+	performance_now: "performance.now() is non-deterministic — use the run's deterministic inception time",
+	process_hrtime: "process.hrtime() is non-deterministic — use the run's deterministic inception time",
+};
+
+/**
+ * Scan TypeScript source for non-deterministic API references.
+ * Returns one entry per offending node, with 1-based line:column.
+ */
+export function findDeterminismViolations(source: string, filename = "<workflow>"): DeterminismViolation[] {
+	const sf = createSourceFile(filename, source, ScriptTarget.Latest, /*setParentNodes*/ false);
+	const violations: DeterminismViolation[] = [];
+	walk(sf, (node) => {
+		const kind = classify(node);
+		if (kind !== null) {
+			const { line, character } = sf.getLineAndCharacterOfPosition(node.getStart(sf));
+			violations.push({ kind, line: line + 1, column: character + 1, source: node.getText(sf) });
+		}
+	});
+	return violations;
+}
+
+/**
+ * Assert source is deterministic; throw DeterminismError listing every
+ * violation. Loader calls this immediately before jiti-imports a workflow.
+ *
+ * Scope limitation (P1-3): scans ONLY the entry source passed in. Static
+ * imports (`import { now } from "./time-util.ts"`) whose helper calls
+ * Date.now / Math.random are NOT transitively scanned — keep workflows
+ * single-file, or guard imported helpers separately. Both dot and bracket
+ * access (`Date.now()` / `Date["now"]()`) are caught; destructuring aliases
+ * (`const {now} = Date; now()`) and `globalThis.Math.random()` still bypass.
+ * This is a single-file lint, not a full determinism proof.
+ */
+export function assertDeterministic(source: string, filename?: string): void {
+	const violations = findDeterminismViolations(source, filename);
+	if (violations.length === 0) return;
+	const label = filename ?? "<workflow>";
+	const detail = violations
+		.map((v) => `  ${label}:${v.line}:${v.column}  ${v.source}  — ${BANNED_API_MESSAGE[v.kind]}`)
+		.join("\n");
+	throw new DeterminismError(
+		`Workflow source is non-deterministic (${violations.length} violation(s)):\n${detail}`,
+	);
+}
+
+export class DeterminismError extends WorkflowError {
+	constructor(message: string) {
+		super(message, { category: "determinism" });
+		this.name = "DeterminismError";
+	}
+}
+
+function classify(node: Node): DeterminismViolationKind | null {
+	// Unwrap `(...)` so `(Date).now()` and `(crypto)['randomUUID']` cannot bypass
+	// the identifier checks below.
+	function unwrap(n: Node): Node {
+		let cur = n;
+		while (cur.kind === SyntaxKind.ParenthesizedExpression) cur = (cur as ParenthesizedExpression).expression;
+		return cur;
+	}
+
+	// Date.now / Math.random / crypto.* / performance.now / process.hrtime — a
+	// property access off the global identifier (covers `crypto.randomUUID()`,
+	// `performance.now()`, and `process.hrtime.bigint()` via its `process.hrtime`
+	// base access).
+	if (node.kind === SyntaxKind.PropertyAccessExpression) {
+		const pae = node as PropertyAccessExpression;
+		const base = unwrap(pae.expression);
+		if (base.kind === SyntaxKind.Identifier) {
+			return matchGlobal((base as Identifier).text, pae.name.text);
+		}
+		return null;
+	}
+	// Bracket access off a known non-deterministic global: Date["now"],
+	// crypto["randomUUID"], performance["now"], process["hrtime"]. Closes the
+	// bracket-aliasing bypass (review m3) and the template-literal subscript
+	// bypass Date[`now`] (a NoSubstitutionTemplateLiteral, not a StringLiteral).
+	// Destructuring aliases (`const {now} = Date; now()`) and local shadowing
+	// (`const Date = {now: () => 42}`) still bypass / false-positive: the former
+	// needs cross-scope alias tracking, the latter scope analysis — both out of
+	// scope for this guard, which targets direct global-API use.
+	if (node.kind === SyntaxKind.ElementAccessExpression) {
+		const eae = node as ElementAccessExpression;
+		const base = unwrap(eae.expression);
+		const arg = eae.argumentExpression;
+		if (base.kind === SyntaxKind.Identifier) {
+			const obj = (base as Identifier).text;
+			if (arg?.kind === SyntaxKind.StringLiteral) {
+				return matchGlobal(obj, (arg as StringLiteral).text);
+			}
+			if (arg?.kind === SyntaxKind.NoSubstitutionTemplateLiteral) {
+				return matchGlobal(obj, (arg as NoSubstitutionTemplateLiteral).text);
+			}
+		}
+		return null;
+	}
+	// Date() — a no-arg call expression returns the current-time string.
+	// Date.now() is a CallExpression too, but its callee is a PropertyAccess,
+	// not a bare Identifier, so it falls through here without matching.
+	if (node.kind === SyntaxKind.CallExpression) {
+		const ce = node as CallExpression;
+		if (
+			ce.expression.kind === SyntaxKind.Identifier &&
+			(ce.expression as Identifier).text === "Date" &&
+			(ce.arguments === undefined || ce.arguments.length === 0)
+		) {
+			return "date_call";
+		}
+		return null;
+	}
+	// new Date() with zero arguments. new Date(ts) / new Date(y, m, d) are allowed.
+	if (node.kind === SyntaxKind.NewExpression) {
+		const ne = node as NewExpression;
+		if (
+			ne.expression.kind === SyntaxKind.Identifier &&
+			(ne.expression as Identifier).text === "Date" &&
+			(ne.arguments === undefined || ne.arguments.length === 0)
+		) {
+			return "new_date";
+		}
+	}
+	return null;
+}
+
+/** Map a (globalObject, property) pair from a property/element access to a
+ *  violation kind, or null if neither side is a known non-deterministic API. */
+function matchGlobal(obj: string, prop: string): DeterminismViolationKind | null {
+	if (obj === "Date" && prop === "now") return "date_now";
+	if (obj === "Math" && prop === "random") return "math_random";
+	if (obj === "crypto" && (prop === "randomUUID" || prop === "randomBytes" || prop === "getRandomValues")) return "crypto_random";
+	if (obj === "performance" && prop === "now") return "performance_now";
+	if (obj === "process" && prop === "hrtime") return "process_hrtime";
+	return null;
+}
+
+function walk(node: Node, visit: (n: Node) => void): void {
+	visit(node);
+	node.forEachChild((child) => walk(child, visit));
+}

package/src/errors.ts

@@ -0,0 +1,55 @@
+/**
+ * Categorized workflow errors (A5 taxonomy).
+ *
+ * A single `WorkflowError` class carries a `category` discriminator so retry
+ * policy and callers can distinguish recoverable from terminal failures
+ * without a subclass per category (design D6). The pre-existing
+ * `BudgetExceededError` and `DeterminismError` are retrofitted to extend this
+ * class so they gain the discriminator without breaking their exported identity.
+ *
+ * Retry policy keys off `category`: only `dispatch-error` and `unexpected-state`
+ * auto-retry by default; the rest are terminal (size-limit, determinism,
+ * control-chars, policy-gate, compile, killed, budget-exceeded).
+ */
+
+export type ErrorCategory =
+	| "budget-exceeded"
+	| "determinism"
+	| "size-limit"
+	| "control-chars"
+	| "compile"
+	| "policy-gate"
+	| "killed"
+	| "dispatch-error"
+	| "unexpected-state";
+
+/** Structured detail attached to a categorized error (limit hit, byte count,
+ *  offending source location, underlying message, …). */
+export type ErrorDetail = Readonly<Record<string, unknown>>;
+
+export interface WorkflowErrorOptions {
+	readonly category?: ErrorCategory;
+	readonly detail?: ErrorDetail;
+	readonly cause?: unknown;
+}
+
+export class WorkflowError extends Error {
+	readonly category: ErrorCategory;
+	readonly detail?: ErrorDetail;
+
+	constructor(message: string, opts: WorkflowErrorOptions = {}) {
+		super(message, opts.cause !== undefined ? { cause: opts.cause } : undefined);
+		this.name = "WorkflowError";
+		this.category = opts.category ?? "unexpected-state";
+		this.detail = opts.detail;
+	}
+}
+
+/** Categories that are eligible for automatic retry by default. All others are
+ *  treated as terminal (retrying a size-limit or determinism violation just
+ *  wastes budget). */
+export const RETRYABLE_CATEGORIES: readonly ErrorCategory[] = ["dispatch-error", "unexpected-state"];
+
+export function isRetryable(err: unknown): boolean {
+	return err instanceof WorkflowError && RETRYABLE_CATEGORIES.includes(err.category);
+}

package/src/format.ts

@@ -0,0 +1,27 @@
+/**
+ * src/format.ts — shared display/parsing helpers (progress widget + /wf-inspect + runner).
+ *
+ * fmtTokens + ANSI color helpers: used by `buildProgressWidget` (index.ts) and
+ * `WorkflowInspect` (src/inspect.ts) — one copy so the two UIs cannot drift.
+ * stepIdOf: callId → step-id attribution, used by the runner (degraded-step
+ * accounting) and the widget (grouping by step). Extracted from the verbatim
+ * duplicates that used to live in each file.
+ */
+export const GREEN = (s: string): string => `\x1b[32m${s}\x1b[0m`;
+export const RED = (s: string): string => `\x1b[31m${s}\x1b[0m`;
+export const YELLOW = (s: string): string => `\x1b[33m${s}\x1b[0m`;
+export const DIM = (s: string): string => `\x1b[2m${s}\x1b[0m`;
+export const CYAN = (s: string): string => `\x1b[36m${s}\x1b[0m`;
+export const BOLD = (s: string): string => `\x1b[1m${s}\x1b[0m`;
+
+export function fmtTokens(n: number): string {
+	return n >= 1000 ? `${(n / 1000).toFixed(1)}k` : String(n);
+}
+
+/** Extract the step id from a callId of the form `${stepId}#${n}` (e.g.
+ *  "fan#2", "adv#produce", "cr#classify"). Falls back to the whole callId when
+ *  there is no '#'. Used to attribute null-degraded calls to their step. */
+export function stepIdOf(callId: string): string {
+	const sep = callId.lastIndexOf("#");
+	return sep >= 0 ? callId.slice(0, sep) : callId;
+}

package/src/index.ts

@@ -0,0 +1,28 @@
+/**
+ * Public API barrel for @fyeeme/pi-dynamic-workflows.
+ *
+ * Import the workflow engine from here:
+ *   import { defineWorkflow, runWorkflow, collect, heuristicallyPlan } from "@fyeeme/pi-dynamic-workflows/src/index.ts";
+ */
+export * from "./types.ts";
+export { runWorkflow, type RunWorkflowOptions } from "./runner/index.ts";
+export { type AgentDispatch, type StepExecContext } from "./runner/stage-executor.ts";
+export { loadWorkflowModule, type LoadWorkflowOptions } from "./loader.ts";
+export {
+	collect,
+	parseFirstJson,
+	urlCollector,
+	filePathCollector,
+	jsonCollector,
+	type OutputSpec,
+	type Collector,
+} from "./outcomes.ts";
+export { heuristicallyPlan, type HeuristicPlanOptions } from "./planner.ts";
+export {
+	WorkflowError,
+	isRetryable,
+	RETRYABLE_CATEGORIES,
+	type ErrorCategory,
+	type ErrorDetail,
+	type WorkflowErrorOptions,
+} from "./errors.ts";

package/src/inspect.ts

@@ -0,0 +1,237 @@
+/**
+ * WorkflowInspect — fullscreen overlay viewer with a master-detail split.
+ *
+ * Opened via `/wf-inspect` as an overlay (`ctx.ui.custom(..., { overlay: true })`)
+ * sized to ~90% × 80% of the terminal. The body is split into two panes that
+ * fill the wide overlay instead of wasting it on a single narrow column:
+ *
+ *   ┌─ STEPS (left ~30%) ──────┬─ DETAIL (right ~70%) ──────────────┐
+ *   │ ✓ gather   · 1.2k tok    │ collected 3 sources on topic X     │
+ *   │▸✓ fan      · 8.4k tok    │ [fan#1] Research alpha.            │
+ *   │ ○ refine   · pending     │ 8.4k tok · 3 agent(s) · 1240ms     │
+ *   └──────────────────────────┴────────────────────────────────────┘
+ *
+ * Left: compact step list (always visible, ↑↓/j/k selects, auto-scrolls).
+ * Right: the selected step's full results + stats (PgUp/PgDn/Shift+↑↓/Home/End
+ * scrolls the detail). No toggle — detail is always shown for the selection.
+ * esc/q exits.
+ */
+import { matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import type { RunResult, StepResult } from "./types.ts";
+import { buildRenderGroups, type PhaseDef } from "./ui-groups.ts";
+import { BOLD, CYAN, DIM, GREEN, RED, YELLOW, fmtTokens } from "./format.ts";
+
+/** Overlay maxHeight percentage — keep in sync with the index.ts overlayOptions. */
+const VIEWPORT_HEIGHT_PCT = 80;
+/** header(1) + sep(1) + col-header(1) + sep(1) + [body] + sep(1) + footer(1). */
+const CHROME_LINES = 6;
+const MIN_VIEWPORT = 3;
+/** Left pane share of the width (rest goes to the detail pane + separator). */
+const LEFT_PCT = 0.3;
+const MIN_LEFT = 16;
+
+/** Minimal TUI surface WorkflowInspect needs. Narrower than full `TUI`. */
+export interface InspectTUI {
+	requestRender(): void;
+	terminal: { readonly rows: number };
+}
+
+function statusIcon(status: StepResult["status"]): string {
+	switch (status) {
+		case "done":
+			return GREEN("✓");
+		case "failed":
+			return RED("✗");
+		case "skipped":
+			return YELLOW("⏭");
+		default:
+			return YELLOW("⏳");
+	}
+}
+
+/** Fit a (possibly ANSI-colored) string into exactly `w` visible columns:
+ *  truncate with … if too long, pad with spaces if too short. */
+function field(s: string, w: number): string {
+	return truncateToWidth(s, w, "…", true);
+}
+
+export class WorkflowInspect {
+	private readonly result: RunResult;
+	private readonly tui: InspectTUI;
+	private readonly close: () => void;
+	private readonly phases?: readonly PhaseDef[];
+	private selected = 0;
+	/** Right-pane (detail) scroll offset; reset to 0 whenever selection changes. */
+	private detailScroll = 0;
+	/** Left-pane scroll offset; auto-adjusted to keep the selection visible. */
+	private leftScroll = 0;
+	/** Last known detail content height (set during render). Lets PgUp/PgDn
+	 *  clamp an Infinity detailScroll (set by End) before arithmetic, so
+	 *  End→PgUp is not swallowed by Infinity - vp = Infinity. */
+	private lastMaxDetailScroll = 0;
+	/** step index → row index within buildLeftLines() (phase title lines shift
+	 *  step rows past their raw array index — selection must scroll by row). */
+	private rowOfStep = new Map<number, number>();
+
+	constructor(result: RunResult, tui: InspectTUI, close: () => void, phases?: readonly PhaseDef[]) {
+		this.result = result;
+		this.tui = tui;
+		this.close = close;
+		this.phases = phases;
+	}
+
+	private viewportHeight(): number {
+		const rows = this.tui.terminal.rows > 0 ? this.tui.terminal.rows : 24;
+		return Math.max(MIN_VIEWPORT, Math.floor((rows * VIEWPORT_HEIGHT_PCT) / 100) - CHROME_LINES);
+	}
+
+	handleInput(data: string): void {
+		if (matchesKey(data, "escape") || data === "q" || data === "Q") {
+			this.close();
+			return;
+		}
+		const n = this.result.steps.length;
+		if (n === 0) return;
+		const vp = this.viewportHeight();
+		// Right-pane (detail) scroll.
+		if (matchesKey(data, "pageUp") || matchesKey(data, "shift+up")) {
+			// End may have left detailScroll as the Infinity sentinel (clamped to a
+			// finite value only on the next render) — clamp before arithmetic so
+			// Infinity - vp stays Infinity and PgUp appears dead.
+			const cur = Math.min(this.detailScroll, this.lastMaxDetailScroll);
+			this.detailScroll = Math.max(0, cur - vp);
+			this.tui.requestRender();
+			return;
+		}
+		if (matchesKey(data, "pageDown") || matchesKey(data, "shift+down")) {
+			const cur = Math.min(this.detailScroll, this.lastMaxDetailScroll);
+			this.detailScroll = cur + vp;
+			this.tui.requestRender();
+			return;
+		}
+		if (matchesKey(data, "home")) {
+			this.detailScroll = 0;
+			this.tui.requestRender();
+			return;
+		}
+		if (matchesKey(data, "end")) {
+			this.detailScroll = Number.POSITIVE_INFINITY;
+			this.tui.requestRender();
+			return;
+		}
+		// Selection moves — reset the detail pane to the top of the new step.
+		if (matchesKey(data, "up") || data === "k") {
+			this.selected = (this.selected - 1 + n) % n;
+			this.detailScroll = 0;
+			this.tui.requestRender();
+		} else if (matchesKey(data, "down") || data === "j") {
+			this.selected = (this.selected + 1) % n;
+			this.detailScroll = 0;
+			this.tui.requestRender();
+		}
+	}
+
+	invalidate(): void {
+		// No cached render state.
+	}
+
+	render(width: number): string[] {
+		const r = this.result;
+		const w = Math.max(width, 40);
+		const leftW = Math.max(MIN_LEFT, Math.floor(w * LEFT_PCT));
+		const rightW = Math.max(20, w - leftW - 1); // -1 for the "│" separator
+		const sep = DIM("│");
+		const hr = DIM("─".repeat(w));
+		const out: string[] = [];
+
+		// --- Header (full width) ---
+		const degraded = r.degradedSteps?.length ? ` · ${r.degradedSteps.length} degraded` : "";
+		const errTag = r.errorCategory ? ` [${r.errorCategory}]` : "";
+		const head = `${BOLD(`workflow ${CYAN(r.runId)} → ${r.status}`)}  ${DIM(`${r.stats.agents} agents · ${fmtTokens(r.stats.tokens)} tok · ${(r.stats.durationMs / 1000).toFixed(1)}s${degraded}`)}`;
+		out.push(field(r.error ? RED(`${head}  ${r.error}${errTag}`) : head, w));
+		out.push(hr);
+
+		// --- Column header ---
+		const selStep = r.steps[this.selected];
+		const colLeft = BOLD("STEPS");
+		const colRight = DIM(`DETAIL${selStep ? ` · ${selStep.id} (${selStep.type})` : ""}`);
+		out.push(field(colLeft, leftW) + sep + field(colRight, rightW));
+		out.push(hr);
+
+		// --- Body: two panes zipped row-by-row ---
+		const vp = this.viewportHeight();
+		const leftLines = this.buildLeftLines(leftW);
+		// Keep the selected step visible in the left pane. leftLines may start
+		// with phase title rows, so the selection's ROW (not its raw step index)
+		// drives the window — otherwise phases push the selected step off-screen.
+		const selRow = this.rowOfStep.get(this.selected) ?? this.selected;
+		if (selRow < this.leftScroll) this.leftScroll = selRow;
+		else if (selRow >= this.leftScroll + vp) this.leftScroll = selRow - vp + 1;
+		this.leftScroll = Math.max(0, Math.min(this.leftScroll, Math.max(0, leftLines.length - vp)));
+
+		const rightLines = selStep ? this.buildRightLines(selStep) : [DIM("(no step)")];
+		const maxDetailScroll = Math.max(0, rightLines.length - vp);
+		this.lastMaxDetailScroll = maxDetailScroll;
+		this.detailScroll = Math.max(0, Math.min(this.detailScroll, maxDetailScroll));
+
+		for (let i = 0; i < vp; i++) {
+			const l = field(leftLines[this.leftScroll + i] ?? "", leftW);
+			const rr = field(rightLines[this.detailScroll + i] ?? "", rightW);
+			out.push(l + sep + rr);
+		}
+
+		// --- Footer ---
+		out.push(hr);
+		const footL = DIM("↑↓/j/k select · PgUp/PgDn/Shift+↑↓ scroll detail · Home/End · esc exit");
+		const dPct = rightLines.length <= vp ? "all" : `${Math.round(((this.detailScroll + vp) / rightLines.length) * 100)}%`;
+		const footR = DIM(`${this.detailScroll}/${rightLines.length} (${dPct}) · ${this.selected + 1}/${r.steps.length} steps`);
+		out.push(field(footL, leftW) + sep + field(footR, rightW));
+		return out;
+	}
+
+	/** Left pane: one compact line per step (status · id · type · tokens). */
+	private buildLeftLines(w: number): string[] {
+		const idxOf = new Map(this.result.steps.map((s, i) => [s.id, i]));
+		const groups = buildRenderGroups(this.result.steps, (s) => s.id, this.phases);
+		const lines: string[] = [];
+		const rowOf = new Map<number, number>();
+		// Every phase group renders its header (a phase interrupted by ungrouped
+		// items produces two groups; deduplicating the second header would leave
+		// an indented, header-less orphan row).
+		for (const g of groups) {
+			if (g.kind === "phase" && g.title) {
+				lines.push(field(BOLD(g.title), w));
+			}
+			for (const s of g.items) {
+				const i = idxOf.get(s.id) ?? 0;
+				rowOf.set(i, lines.length);
+				const sel = i === this.selected;
+				const tok = s.stats.tokens > 0 ? ` · ${fmtTokens(s.stats.tokens)} tok` : "";
+				const body = `${statusIcon(s.status)} ${s.id} ${DIM(`(${s.type})${tok}`)}`;
+				lines.push(field(sel ? `${CYAN("▸")}${BOLD(body)}` : ` ${body}`, w));
+			}
+		}
+		this.rowOfStep = rowOf;
+		return lines;
+	}
+
+	/** Right pane: the selected step's full results + a stats footer line.
+	 *  `results === undefined` means a live snapshot with nothing settled yet —
+	 *  show an honest "in progress" marker instead of JSON.stringify(undefined). */
+	private buildRightLines(s: StepResult): string[] {
+		const lines: string[] = [];
+		if (s.results === undefined) {
+			lines.push(DIM("(in progress — no agent output settled yet)"));
+		} else {
+			const body = typeof s.results === "string" ? s.results : JSON.stringify(s.results, null, 2);
+			for (const ln of body.split("\n")) lines.push(DIM(ln));
+		}
+		lines.push("");
+		lines.push(DIM(`${fmtTokens(s.stats.tokens)} tok · ${s.stats.agents} agent(s) · ${s.stats.durationMs}ms · ${s.stats.failures} fail`));
+		return lines;
+	}
+
+	dispose(): void {
+		// Nothing to release.
+	}
+}

package/src/lifecycle.ts

@@ -0,0 +1,75 @@
+/**
+ * Agent-level lifecycle events (Task 5 surface).
+ *
+ * Minimal: the four agent events. `retryAgent`/`skipAgent` fire onAgentRetry/
+ * onAgentSkip. onAgentStart/onAgentEnd are reserved for the spawn path to wire
+ * later — onAgentEnd takes a boolean `ok` rather than the full AgentSpawnResult
+ * so this module has no `src/agent/dispatch` import (avoids a circular type
+ * dependency: dispatch imports lifecycle for the listener type).
+ *
+ * Workflow/stage-level events (onWorkflowStart/onStageStart/...) join here
+ * when the runner module lands. Mirrors CC's LifecycleListeners shape: a
+ * per-call optional bundle; a throwing listener is caught and warned, never
+ * blocks the abort/retry path.
+ */
+
+import type { StepStats } from "./types.ts";
+
+export interface AgentLifecycleListeners {
+	onAgentStart?(callId: string): void;
+	/** `stats` carries per-call tokens/cost/duration so progress UIs can show spend live. */
+	onAgentEnd?(callId: string, ok: boolean, stats?: StepStats, model?: string, output?: string): void;
+	onAgentSkip?(callId: string): void;
+	onAgentRetry?(callId: string): void;
+	/** Fired when an agent call hits the journal cache (zero-dispatch resume). */
+	onAgentCacheHit?(callId: string): void;
+	/** Fired when a `log` step runs, with the step id and resolved message. */
+	onLog?(stepId: string, message: string): void;
+	/** Fired on each streamed `message_update` partial for an in-flight agent call. */
+	onUpdate?(callId: string, partial: string): void;
+}
+
+export function notifySkip(listeners: AgentLifecycleListeners | undefined, callId: string): void {
+	try {
+		listeners?.onAgentSkip?.(callId);
+	} catch (e) {
+		warn("onAgentSkip", e);
+	}
+}
+
+export function notifyRetry(listeners: AgentLifecycleListeners | undefined, callId: string): void {
+	try {
+		listeners?.onAgentRetry?.(callId);
+	} catch (e) {
+		warn("onAgentRetry", e);
+	}
+}
+
+export function notifyCacheHit(listeners: AgentLifecycleListeners | undefined, callId: string): void {
+	try {
+		listeners?.onAgentCacheHit?.(callId);
+	} catch (e) {
+		warn("onAgentCacheHit", e);
+	}
+}
+
+export function notifyLog(listeners: AgentLifecycleListeners | undefined, stepId: string, message: string): void {
+	try {
+		listeners?.onLog?.(stepId, message);
+	} catch (e) {
+		warn("onLog", e);
+	}
+}
+
+export function notifyUpdate(listeners: AgentLifecycleListeners | undefined, callId: string, partial: string): void {
+	try {
+		listeners?.onUpdate?.(callId, partial);
+	} catch (e) {
+		warn("onUpdate", e);
+	}
+}
+
+function warn(event: string, e: unknown): void {
+	const msg = e instanceof Error ? e.message : String(e);
+	console.warn(`[pi-dynamic-workflows] lifecycle ${event} listener threw: ${msg}`);
+}

package/src/loader.ts

@@ -0,0 +1,50 @@
+/**
+ * Workflow-file loader — the bridge from the deterministic sandbox (Task 3) to
+ * runtime execution: read a `.ts` workflow file, reject it via the ast-guard if
+ * it smuggles in non-deterministic APIs (Date.now / Math.random / new Date()),
+ * then load it as a module via jiti (the same loader pi uses for extensions).
+ *
+ * Guarding BEFORE jiti-import is what makes cache-key resume (Task 4) sound: a
+ * workflow body that read "now" would change its cache key every run, so resume
+ * could never hit. Rejecting such source at load time makes determinism
+ * enforceable rather than hoped-for. jiti loads a real module (not a vm-sandboxed
+ * string), so the guard runs on the raw source text first.
+ *
+ * Scope limit: the guard scans ONLY the entry file's source. A helper module
+ * imported by the workflow that calls Date.now()/Math.random() is not caught
+ * here, and would silently destabilize cache keys. For full determinism keep
+ * workflows single-file, or guard imported helpers separately. (Walking jiti's
+ * transitive imports pre-load is not exposed by the loader API.)
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { createJiti } from "jiti/static";
+import { assertDeterministic } from "./determinism/ast-guard.ts";
+
+export interface LoadWorkflowOptions {
+	/** Absolute (or baseUrl-relative) path to the `.ts` workflow file. */
+	readonly filePath: string;
+	/** jiti base URL; defaults to this module so relative imports resolve from here. */
+	readonly baseUrl?: string;
+}
+
+/**
+ * Read `filePath`, reject it if non-deterministic, then load it via jiti.
+ * Returns the module namespace — callers extract the workflow export
+ * (e.g. `mod.workflow` or `mod.default`, a WorkflowDefinition).
+ */
+export async function loadWorkflowModule<T = unknown>(opts: LoadWorkflowOptions): Promise<T> {
+	const baseUrl = opts.baseUrl ?? import.meta.url;
+	// Resolve the path ONCE so readFile and jiti.import load the same file. A
+	// relative path is baseUrl-relative (per LoadWorkflowOptions); previously
+	// readFile resolved it against cwd while jiti resolved it against baseUrl,
+	// so the guard could scan one file while jiti executed another.
+	const resolved = path.isAbsolute(opts.filePath)
+		? opts.filePath
+		: path.resolve(path.dirname(fileURLToPath(baseUrl)), opts.filePath);
+	const source = await fs.promises.readFile(resolved, "utf-8");
+	assertDeterministic(source, opts.filePath);
+	const jiti = createJiti(baseUrl, { moduleCache: false });
+	return (await jiti.import(resolved)) as T;
+}