pi-crew 0.8.14 → 0.9.1

package/src/utils/redaction.ts

@@ -6,6 +6,36 @@
 // Pattern for PEM private keys (possessive quantifier prevents backtracking)
 export const PEM_PRIVATE_KEY_PATTERN = /-----BEGIN [A-Z ]+PRIVATE KEY-----[\s\S]+?-----END [A-Z ]+PRIVATE KEY-----/g;
 
+// --- P1f (RFC §P1f / §6 STRIDE) — additional anchored, ReDoS-SAFE secret patterns. ---
+// All patterns below are LINEAR-TIME: each uses a single bounded quantifier on a
+// character class (fixed {N} or a plain +) with NO nested quantifiers and NO
+// overlapping alternation. Boundaries are zero-width lookarounds on simple char
+// classes, which are also linear. Do NOT introduce (a+)+-style nesting here.
+//
+// RESIDUAL (documented, Med-High per RFC §6): regex redaction is BEST-EFFORT
+// against an *adversarial* worker that can encode/split/transform secrets
+// (base64, line splits, novel formats, non-pattern env vars). This catches the
+// common/accidental leak; it is NOT a boundary against a determined exfiltrator.
+// Full mitigation ladder: (1) redaction here + at artifact-write; (2) Phase 1.5
+// sanitized-env verification; (3) sandbox (deferred).
+
+// JWT — three base64url segments separated by dots, distinctive "eyJ" headers.
+// Linear: single + on [A-Za-z0-9_-] per segment, no nesting.
+export const JWT_PATTERN = /(?<![A-Za-z0-9_-])eyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g;
+
+// GitHub PAT (classic + fine-grained prefixes) — fixed 36-char base62 tail.
+// Linear: fixed {36} count on a char class (constant time per match position).
+export const GITHUB_PAT_PATTERN = /(?<![A-Za-z0-9_])gh[pousr]_[A-Za-z0-9]{36}(?![A-Za-z0-9])/g;
+
+// AWS access key id — fixed 16-char uppercase-alphanumeric tail.
+// Linear: fixed {16} count on a char class.
+export const AWS_ACCESS_KEY_PATTERN = /(?<![A-Za-z0-9])AKIA[0-9A-Z]{16}(?![0-9A-Z])/g;
+
+// Optional extras (RFC OQ13) — same ReDoS-safe shape (fixed counts / single +).
+export const SLACK_TOKEN_PATTERN = /(?<![A-Za-z0-9_-])xox[baprs]-[A-Za-z0-9-]{10,}/g;
+export const GOOGLE_API_KEY_PATTERN = /(?<![A-Za-z0-9_-])AIza[0-9A-Za-z_-]{35}(?![0-9A-Za-z_-])/g;
+export const STRIPE_KEY_PATTERN = /(?<![A-Za-z0-9_])sk_live_[0-9a-zA-Z]{24}(?![0-9a-zA-Z])/g;
+
 // Linear-time secret key detection
 // IMPORTANT: This function must maintain linear-time guarantees.
 // The fast-path regex uses simple string alternatives with anchors only (no quantifiers),
@@ -18,23 +48,52 @@ export function isSecretKey(keyName: string): boolean {
 	if (/^(token|apikey|api_key|password|secret|credential|authorization|privatekey|private_key)$/.test(lower)) {
 		return true;
 	}
-	// Linear scan for prefix characters followed by keywords
+	// Linear scan for prefix characters followed by keywords.
+	// FIX (cold-review #1 of Phase 1): use `lower.startsWith(kw, i+1)` + `lower.charAt(...)` to
+	// avoid allocating substring+toLowerCase inside the O(n) loop (was O(n^2) — adversarial
+	// worker emitting `_`×N+`=` stalled 200KB→29s, 500KB→216s). Now O(n).
 	const prefixes = "_.-";
 	const keywords = ["token", "api", "key", "password", "passwd", "secret", "credential", "authorization", "private"];
-	
+
 	for (let i = 0; i < keyName.length; i++) {
 		if (prefixes.includes(keyName[i])) {
-			const remaining = keyName.substring(i + 1).toLowerCase();
 			for (const kw of keywords) {
-				if (remaining.startsWith(kw)) {
-					const afterKw = remaining.substring(kw.length);
-					if (afterKw === "" || prefixes.includes(afterKw[0]) || /[a-zA-Z0-9]/.test(afterKw[0])) {
+				if (lower.startsWith(kw, i + 1)) {
+					const afterCh = lower.charAt(i + 1 + kw.length);
+					if (afterCh === "" || prefixes.includes(afterCh) || /[a-zA-Z0-9]/.test(afterCh)) {
 						return true;
 					}
 				}
 			}
 		}
 	}
+	// FIX (P1f, surfaced by notification-sink test): also match camelCase
+	// boundaries (e.g. `apiToken`, `clientSecret`, `authKey`) — the separator
+	// scan above requires `_-.` between prefix and keyword and MISSES the very
+	// common camelCase pattern. Scan: a keyword matches if it appears with a
+	// word boundary (start of string, end of string, camelCase lowercase->upper
+	// transition, or one of `_-.` separators). Linear: one forward pass.
+	for (const kw of keywords) {
+		let from = 0;
+		while (true) {
+			const idx = lower.indexOf(kw, from);
+			if (idx === -1) break;
+			const before = idx === 0 ? "" : lower.charAt(idx - 1);
+			const afterIdx = idx + kw.length;
+			const afterCh = afterIdx >= lower.length ? "" : lower.charAt(afterIdx);
+			const atStart = idx === 0;
+			const atEnd = afterIdx === lower.length;
+			const camelBoundary = /[A-Z]/.test(keyName.charAt(afterIdx)); // lowercase->uppercase in original
+			const sepBoundary = prefixes.includes(before) || prefixes.includes(afterCh);
+			if (atStart || atEnd || camelBoundary || sepBoundary) {
+				// Require non-empty chars before/after to avoid matching `api` inside `capitalize`
+				const hasBefore = idx > 0;
+				const hasAfter = afterIdx < lower.length;
+				if (hasBefore || hasAfter) return true;
+			}
+			from = idx + 1;
+		}
+	}
 	return false;
 }
 
@@ -124,9 +183,20 @@ export function redactSecretString(value: string): string {
 	// Replace Authorization headers (non-Bearer format)
 	result = redactAuthHeader(result);
 	
-	// Replace Bearer tokens
+	// Replace Bearer tokens (run before structured-token patterns so a
+	// "Bearer <jwt>" pair is collapsed first; bare tokens are caught below).
 	result = redactBearerTokens(result);
 	
+	// P1f: structured secret tokens (JWT / GitHub PAT / AWS keys + optional
+	// Slack/Google/Stripe). Best-effort vs adversarial workers (see note above).
+	result = result
+		.replace(JWT_PATTERN, "***")
+		.replace(GITHUB_PAT_PATTERN, "***")
+		.replace(AWS_ACCESS_KEY_PATTERN, "***")
+		.replace(SLACK_TOKEN_PATTERN, "***")
+		.replace(GOOGLE_API_KEY_PATTERN, "***")
+		.replace(STRIPE_KEY_PATTERN, "***");
+	
 	// Replace inline secrets: key=value or key:value patterns
 	result = redactInlineSecrets(result);
 	
@@ -134,51 +204,61 @@ export function redactSecretString(value: string): string {
 }
 
 // Linear-time inline secret redaction: token=xxx, api_key=xxx, etc.
+// FIX (P1f): previously O(n^2) — after a non-secret alphanumeric run, the loop did
+// i++ (advance 1 char) and re-scanned from i+1, so a long run was rescanned O(n)
+// times = O(n^2). The P1f ReDoS test (300KB no-dot input) surfaced this pre-existing
+// bug. Now advances past the whole run when it isn't a redactable secret -> O(n).
 function redactInlineSecrets(value: string): string {
 	const result: string[] = [];
 	let i = 0;
-	
+
 	while (i < value.length) {
-		// Look for pattern: word_chars + = or : + non-whitespace_value
-		// Check for secret key followed by = or :
+		// Collect a run of key characters (alphanumeric, underscore, hyphen).
 		let j = i;
-		let keyLen = 0;
-		
-		// Collect key characters (alphanumeric, underscore, hyphen)
 		while (j < value.length && /[a-zA-Z0-9_-]/.test(value[j])) {
 			j++;
-			keyLen++;
 		}
-		
+		const keyLen = j - i;
+
+		let redacted = false;
 		if (keyLen > 0 && j < value.length && (value[j] === '=' || value[j] === ':')) {
-			const key = value.substring(i, i + keyLen);
-			
+			const key = value.substring(i, j);
+
 			// Check if this is a secret key
 			if (isSecretKey(key)) {
 				// Find the value (everything after = or : until space, comma, or end)
 				const sep = value[j];
 				let k = j + 1;
 				let valLen = 0;
-				while (k < value.length && valLen < 500 && value[k] !== ' ' && value[k] !== ',' && value[k] !== ';' && value[k] !== '"' && value[k] !== '"' && value[k] !== '\r' && value[k] !== '\n') {
+				while (k < value.length && valLen < 500 && value[k] !== ' ' && value[k] !== ',' && value[k] !== ';' && value[k] !== '"' && value[k] !== '\r' && value[k] !== '\n') {
 					k++;
 					valLen++;
 				}
-				
+
 				// Only redact if there's actual content
 				if (valLen > 0) {
 					result.push(key);
 					result.push(sep);
 					result.push("***");
 					i = k;
-					continue;
+					redacted = true;
 				}
 			}
 		}
-		
-		result.push(value[i]);
-		i++;
+
+		if (!redacted) {
+			if (keyLen > 0) {
+				// Not a redactable secret — push the WHOLE run and advance past it (O(n)).
+				result.push(value.substring(i, j));
+				i = j;
+			} else {
+				// Single non-key character (space, punctuation, etc.)
+				result.push(value[i]);
+				i++;
+			}
+		}
 	}
-	
+
 	return result.join("");
 }
 

package/src/utils/safe-paths.ts

@@ -16,32 +16,73 @@ export function resolveContainedPath(baseDir: string, targetPath: string): strin
 	}
 	const base = path.resolve(baseDir);
 	const resolved = path.isAbsolute(targetPath) ? path.resolve(targetPath) : path.resolve(base, targetPath);
-	// On Windows, paths are case-insensitive and short-name (8.3) aliases may
-	// differ from long-name forms (e.g. C:\Users\RUNNER~1 vs C:\Users\runneradmin).
-	// We normalize both paths to their canonical form by resolving through
-	// realpathSync, walking up ancestors for non-existent paths.
-	const baseNorm = process.platform === "win32" ? resolveWindowsCanonical(base) : base;
-	const resolvedNorm = process.platform === "win32" ? resolveWindowsCanonical(resolved) : resolved;
+	// Normalize BOTH paths to canonical form on ALL platforms. This resolves
+	// symlinks so that a base and target that refer to the same physical dir
+	// via different paths (Windows 8.3 short-name; macOS /var → /private/var)
+	// compare equal. Without this, a legitimately-contained target under an
+	// OS-managed symlink is wrongly rejected as "outside" the base.
+	const baseNorm = resolveCanonicalPath(base);
+	const resolvedNorm = resolveCanonicalPath(resolved);
 	const relative = process.platform === "win32"
 		? path.relative(baseNorm.toLowerCase(), resolvedNorm.toLowerCase())
-		: path.relative(base, resolved);
+		: path.relative(baseNorm, resolvedNorm);
 	if (relative.startsWith("..") || path.isAbsolute(relative)) throw new Error(`Path is outside ${baseDir}: ${targetPath}`);
 	return resolved;
 }
 
+/**
+ * Platform-agnostic canonical path resolution. Resolves symlinks (via
+ * realpathSync) to normalize paths so the same physical location always
+ * yields the same string regardless of how it was referenced.
+ *
+ * - Windows: delegates to resolveWindowsCanonical (canonical LONG-NAME form,
+ *   resolving 8.3 short-name aliases like RUNNER~1 → runneradmin).
+ * - POSIX: uses realpathSync, which resolves system symlinks such as the
+ *   macOS /var → /private/var mapping.
+ *
+ * For non-existent paths (write targets), walks up to the deepest existing
+ * ancestor and joins the remaining components, so the canonical prefix is
+ * still comparable.
+ */
+function resolveCanonicalPath(p: string): string {
+	if (process.platform === "win32") return resolveWindowsCanonical(p);
+	try {
+		return fs.realpathSync(p);
+	} catch {
+		const parts: string[] = [];
+		let current = p;
+		while (current !== path.dirname(current)) {
+			try {
+				const real = fs.realpathSync(current);
+				let acc = real;
+				for (let i = parts.length - 1; i >= 0; i--) acc = path.join(acc, parts[i]);
+				return acc;
+			} catch { /* keep walking up */ }
+			parts.push(path.basename(current));
+			current = path.dirname(current);
+		}
+		return p;
+	}
+}
+
 /**
  * On Windows, resolve a path to its canonical (long-name) form.
  * Walks up ancestors until finding one that exists, then joins back down.
  * This handles paths where intermediate directories don't exist yet but
  * their ancestors do (and may use short-name aliases).
+ *
+ * Uses fs.realpathSync.native (canonical long-name form) as the primary
+ * resolver, falling back to non-native realpathSync if .native fails.
  */
 function resolveWindowsCanonical(p: string): string {
 	try {
-		// Use regular realpathSync (not .native) to preserve the input path form.
-		// On Windows CI, .native always returns long-name (runneradmin) while
-		// non-native preserves short-name (RUNNER~1). Using non-native ensures
-		// the returned form matches what os.tmpdir() and mkdtempSync produce.
-		let real = fs.realpathSync(p);
+		// Use the NATIVE realpath to resolve to canonical LONG-NAME form.
+		// On Windows, fs.realpathSync.native resolves 8.3 short-name aliases
+		// (e.g. RUNNER~1) to long-name (runneradmin). This is essential for
+		// containment checks: base (from cwd, often long-name) and target
+		// (from os.tmpdir()/mkdtempSync, often short-name) must normalize to
+		// the SAME form or a contained target is wrongly rejected as "outside".
+		let real = fs.realpathSync.native(p);
 		// Guard against NTFS internal paths (e.g. C:\$Extend\$Deleted)
 		if (real.includes("$Extend") || real.includes("$Deleted")) throw new Error("NTFS internal path");
 		return real;
@@ -56,8 +97,8 @@ function resolveWindowsCanonical(p: string): string {
 		let current = p;
 		while (current !== path.dirname(current)) {
 			try {
-				// Use non-native to preserve input path form
-				let real = fs.realpathSync(current);
+				let real: string;
+				try { real = fs.realpathSync.native(current); } catch { real = fs.realpathSync(current); }
 				// Guard against NTFS internal paths
 				if (real.includes("$Extend") || real.includes("$Deleted")) throw new Error("NTFS internal path");
 				// Found existing ancestor — join with remaining parts in reverse order

package/src/workflows/discover-workflows.ts

@@ -120,11 +120,35 @@ function parseWorkflowFile(filePath: string, source: ResourceSource): WorkflowCo
 
 function readWorkflowDir(dir: string, source: ResourceSource): WorkflowConfig[] {
 	if (!fs.existsSync(dir)) return [];
-	return fs.readdirSync(dir)
+	const staticWorkflows = fs.readdirSync(dir)
 		.filter((entry) => entry.endsWith(".workflow.md"))
 		.map((entry) => parseWorkflowFile(path.join(dir, entry), source))
 		.filter((workflow): workflow is WorkflowConfig => workflow !== undefined)
 		.sort((a, b) => a.name.localeCompare(b.name));
+	// P2: also discover dynamic workflows (*.dwf.ts). A .dwf.ts's default export is a JS orchestrator.
+	const dynamicWorkflows = fs.readdirSync(dir)
+		.filter((entry) => entry.endsWith(".dwf.ts"))
+		.map((entry) => parseDynamicWorkflowFile(path.join(dir, entry), source))
+		.filter((workflow): workflow is WorkflowConfig => workflow !== undefined);
+	return [...staticWorkflows, ...dynamicWorkflows].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/** P2: a .dwf.ts is a dynamic workflow. Name = filename stem; script = the file itself. */
+function parseDynamicWorkflowFile(filePath: string, source: ResourceSource): WorkflowConfig | undefined {
+	try {
+		const basename = path.basename(filePath, ".dwf.ts");
+		return {
+			name: basename,
+			description: `Dynamic workflow script (${basename}.dwf.ts).`,
+			source,
+			filePath,
+			steps: [],
+			runtime: "dynamic",
+			dynamicScript: filePath,
+		};
+	} catch {
+		return undefined;
+	}
 }
 
 export function discoverWorkflows(cwd: string): WorkflowDiscoveryResult {

package/src/workflows/workflow-config.ts

@@ -39,4 +39,17 @@ export interface WorkflowConfig {
 	filePath: string;
 	steps: WorkflowStep[];
 	maxConcurrency?: number;
+	/** P2 dynamic-workflow discriminator. Default "static" (the .workflow.md step-list model).
+	 *  "dynamic" = the workflow is a JS/TS script (.dwf.ts) run via dynamic-workflow-runner.
+	 *  Backward-compatible: absent = "static". */
+	runtime?: "static" | "dynamic";
+	/** For runtime:"dynamic" — relative/absolute path to the .dwf.ts script. Unused for static. */
+	dynamicScript?: string;
+}
+
+/** A dynamic workflow (runtime === "dynamic"). steps is empty — the script is the source of truth. */
+export interface DynamicWorkflowConfig extends WorkflowConfig {
+	runtime: "dynamic";
+	dynamicScript: string;
+	steps: [];
 }

package/src/worktree/cleanup.ts

@@ -1,6 +1,7 @@
 import { execFileSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { WINDOWS_ESSENTIAL_ENV_VARS } from "../utils/env-allowlist.ts";
 import type { TeamRunManifest } from "../state/types.ts";
 import { writeArtifact } from "../state/artifact-store.ts";
 import { projectCrewRoot } from "../utils/paths.ts";
@@ -18,7 +19,7 @@ export interface WorktreeCleanupResult {
 
 // SECURITY: PI_* and PI_CREW_* wildcards removed — they could match secret vars like PI_PASSWORD.
 // Git operations do not need PI_CREW_* execution-control vars.
-const GIT_SAFE_ENV = { ...sanitizeEnvSecrets(process.env, { allowList: ["PATH", "HOME", "USER", "USERPROFILE", "SHELL", "TERM", "LANG", "LC_ALL", "LC_COLLATE", "LC_CTYPE", "LC_MESSAGES", "XDG_CONFIG_HOME", "XDG_DATA_HOME", "XDG_CACHE_HOME", "NVM_BIN", "NVM_DIR", "NODE_PATH", "GIT_CONFIG_GLOBAL", "GIT_CONFIG_SYSTEM", "GIT_AUTHOR_NAME", "GIT_AUTHOR_EMAIL", "GIT_COMMITTER_NAME", "GIT_COMMITTER_EMAIL"] }), LANG: "C", LC_ALL: "C" };
+const GIT_SAFE_ENV = { ...sanitizeEnvSecrets(process.env, { allowList: ["PATH", "HOME", "USER", ...WINDOWS_ESSENTIAL_ENV_VARS, "SHELL", "TERM", "LANG", "LC_ALL", "LC_COLLATE", "LC_CTYPE", "LC_MESSAGES", "XDG_CONFIG_HOME", "XDG_DATA_HOME", "XDG_CACHE_HOME", "NVM_BIN", "NVM_DIR", "NODE_PATH", "GIT_CONFIG_GLOBAL", "GIT_CONFIG_SYSTEM", "GIT_AUTHOR_NAME", "GIT_AUTHOR_EMAIL", "GIT_COMMITTER_NAME", "GIT_COMMITTER_EMAIL"] }), LANG: "C", LC_ALL: "C" };
 
 function sanitizeBranchPart(value: string): string {
 	return value.toLowerCase().replace(/[^a-z0-9._/-]+/g, "-").replace(/^-+|-+$/g, "") || "task";

package/src/worktree/worktree-manager.ts

@@ -1,6 +1,7 @@
 import { execFileSync, spawnSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { WINDOWS_ESSENTIAL_ENV_VARS } from "../utils/env-allowlist.ts";
 import { loadConfig } from "../config/config.ts";
 import { projectCrewRoot } from "../utils/paths.ts";
 import { DEFAULT_PATHS } from "../config/defaults.ts";
@@ -27,7 +28,7 @@ export interface WorktreeDiffStat {
 function git(cwd: string, args: string[]): string {
 	// SECURITY: PI_* and PI_CREW_* wildcards removed — they could match secret vars like PI_PASSWORD.
 // Git operations do not need PI_CREW_* execution-control vars.
-return execFileSync("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], env: { ...sanitizeEnvSecrets(process.env, { allowList: ["PATH", "HOME", "USER", "USERPROFILE", "SHELL", "TERM", "LANG", "LC_ALL", "LC_COLLATE", "LC_CTYPE", "LC_MESSAGES", "XDG_CONFIG_HOME", "XDG_DATA_HOME", "XDG_CACHE_HOME", "NVM_BIN", "NVM_DIR", "NODE_PATH", "GIT_CONFIG_GLOBAL", "GIT_CONFIG_SYSTEM", "GIT_AUTHOR_NAME", "GIT_AUTHOR_EMAIL", "GIT_COMMITTER_NAME", "GIT_COMMITTER_EMAIL"] }), LANG: "en_US.UTF-8", LC_ALL: "en_US.UTF-8" }, windowsHide: true }).trim();
+return execFileSync("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], env: { ...sanitizeEnvSecrets(process.env, { allowList: ["PATH", "HOME", "USER", ...WINDOWS_ESSENTIAL_ENV_VARS, "SHELL", "TERM", "LANG", "LC_ALL", "LC_COLLATE", "LC_CTYPE", "LC_MESSAGES", "XDG_CONFIG_HOME", "XDG_DATA_HOME", "XDG_CACHE_HOME", "NVM_BIN", "NVM_DIR", "NODE_PATH", "GIT_CONFIG_GLOBAL", "GIT_CONFIG_SYSTEM", "GIT_AUTHOR_NAME", "GIT_AUTHOR_EMAIL", "GIT_COMMITTER_NAME", "GIT_COMMITTER_EMAIL"] }), LANG: "en_US.UTF-8", LC_ALL: "en_US.UTF-8" }, windowsHide: true }).trim();
 }
 
 // Dots are removed from branch names since they are used in path construction,
@@ -182,7 +183,7 @@ function runSetupHook(manifest: TeamRunManifest, task: TeamTaskState, repoRoot:
 			timeout: cfg.setupHookTimeoutMs ?? 30_000,
 			shell: false,  // cmd.exe /c handles batch files safely
 			env: sanitizeEnvSecrets(process.env, {
-				allowList: ["PATH", "HOME", "USERPROFILE", "TEMP", "TMP", "TMPDIR", "LANG", "LC_ALL"],
+				allowList: ["PATH", "HOME", ...WINDOWS_ESSENTIAL_ENV_VARS, "TMPDIR", "LANG", "LC_ALL"],
 			}),
 			windowsHide: true,
 		})
@@ -193,7 +194,7 @@ function runSetupHook(manifest: TeamRunManifest, task: TeamTaskState, repoRoot:
 			timeout: cfg.setupHookTimeoutMs ?? 30_000,
 			shell: false,
 			env: sanitizeEnvSecrets(process.env, {
-				allowList: ["PATH", "HOME", "USERPROFILE", "TEMP", "TMP", "TMPDIR", "LANG", "LC_ALL"],
+				allowList: ["PATH", "HOME", ...WINDOWS_ESSENTIAL_ENV_VARS, "TMPDIR", "LANG", "LC_ALL"],
 			}),
 			windowsHide: true,
 		});

package/teams/parallel-research.team.md

@@ -4,7 +4,7 @@ description: Parallel research team for multi-project/source audits
 workspaceMode: single
 defaultWorkflow: parallel-research
 maxConcurrency: 4
-triggers: đọc sâu, deep read, deep research, source audit, multiple projects, parallel research, pi-*
+triggers: deep reading, deep read, deep research, source audit, multiple projects, parallel research, pi-*
 category: research
 cost: cheap
 ---

package/workflows/examples/hello.dwf.ts

@@ -0,0 +1,24 @@
+/**
+ * hello.dwf.ts — Minimal reference dynamic-workflow script (P2).
+ *
+ * Usage: place under `.crew/workflows/hello.dwf.ts`, then
+ *   team action='run' workflow='hello' goal='Greet the user warmly.'
+ *
+ * Demonstrates the WorkflowCtx surface: one ctx.agent() call + ctx.setResult().
+ * See 07-PLAN.md v3 §3.1 and 00-SPEC.md §3.2.
+ */
+import type { WorkflowCtx } from "../src/runtime/dynamic-workflow-context.ts";
+
+export default async function (ctx: WorkflowCtx): Promise<void> {
+	const greeting = await ctx.agent({
+		role: "executor",
+		prompt: `Compose a single-line warm greeting. Context: ${ctx.goal ?? "(no goal)"}`,
+		maxTurns: 2,
+	});
+	// Only ctx.setResult() reaches the main context.
+	ctx.setResult("results/greeting.txt", { ok: greeting.ok, model: "executor" });
+	// Note: in this trivial example the artifact path is illustrative; production scripts
+	// would use ctx.agent()'s returned artifactPath. Here we just surface the agent's text
+	// via the summary (runDynamicWorkflow reads the final artifact or falls back).
+	void greeting;
+}