pi-crew 0.9.5 → 0.9.8

package/docs/troubleshooting.md

@@ -155,3 +155,79 @@ code + a help hint inline. Common ones:
 - `team action='summary' runId=…` — includes common failure-pattern detection
   ("4 of 5 failures share 2 root causes").
 - `team action='events' runId=…` — full event timeline for forensics.
+
+## Stuck / orphaned sub-agent processes ("zombies")
+
+A pi-crew sub-agent whose parent crashed may linger as an orphaned process.
+**Do NOT kill `pi` processes by eye** (uptime/RSS heuristics will match your
+own interactive main session — that is unrecoverable). Use the safe scanner:
+
+```
+team action='doctor' focus='zombies'
+```
+
+This is **read-only**. It matches ONLY processes carrying the authoritative
+`PI_CREW_KIND=subagent` env marker (set by every child-pi spawn) whose
+`PI_CREW_PARENT_PID` is no longer alive. Your main session never carries the
+marker, so it can never appear in the list. (The marker is an env var, not an
+argv flag — pi's strict option parser rejects unknown flags, so we can't use
+a `--crew-subagent` CLI flag.)
+
+To kill a confirmed zombie: `kill <PID>` (the OS reaps it). The scanner never
+kills on your behalf.
+
+### Why the marker exists
+
+Before `PI_CREW_KIND`, a heuristic zombie "cleanup" killed a live main session
+by accident. The marker makes sub-agent identity authoritative rather than
+guessed. See `src/runtime/zombie-scanner.ts` and `.crew/knowledge.md`.
+
+## `ctx.agent({disableTools: true})` — historical `exit null` (FIXED)
+
+Previously, `ctx.agent({disableTools: true, maxTurns: 1})` could return
+`exit null` because the steer-injection code mis-treated normal Node stdin
+backpressure (`write() === false`) as a fatal failure and `killProcessTree`'d
+the worker mid-answer. **Fixed**: steer injection is now advisory — a
+backpressure return or non-writable stdin is logged, not fatal; the
+hard-abort at `maxTurns + graceTurns` remains the safety net for genuine
+runaways. The `disableTools` correlation was a red herring — the real trigger
+was `maxTurns:1` hitting on the first turn. See CHANGELOG "Real-world smoke
+testing findings" and `test/unit/child-pi-steer-backpressure.test.ts`.
+
+## Running the real-binary smoke suite (HB-004)
+
+The default `npm test` mocks child-pi (`PI_TEAMS_MOCK_CHILD_PI`), so it cannot
+catch bugs that only manifest against the real `pi` binary. The smoke suite
+shells out to real pi + makes real LLM calls, so it bills tokens and is gated
+behind `PI_CREW_SMOKE=1`.
+
+### Run locally
+
+```bash
+# All smoke tests (~5 tests, ~1 min, bills tokens):
+PI_CREW_SMOKE=1 npm run test:smoke
+
+# One smoke test in isolation:
+PI_CREW_SMOKE=1 npx tsx --test test/smoke/agent-disabletools.smoke.ts
+```
+
+Smoke tests live in `test/smoke/*.smoke.ts` and are NOT picked up by the default
+`npm test` glob (`test/unit/*` + `test/integration/*`). Each test self-skips
+unless `PI_CREW_SMOKE=1`.
+
+### What each covers
+
+| File | Feature family | Catches |
+|---|---|---|
+| `argv-flags.smoke.ts` | buildPiWorkerArgs argv | unknown-flag rejection (e.g. `--crew-subagent`) |
+| `agent-plain.smoke.ts` | ctx.agent() baseline | spawn-path breakage |
+| `agent-schema.smoke.ts` | ctx.agent({schema, systemPrompt}) | persona-leak / schema-validation failures |
+| `agent-disabletools.smoke.ts` | ctx.agent({disableTools, maxTurns:1}) ×5 | HB-003a steer-backpressure exit-null (flaky → 5×) |
+| `dwf-workflow.smoke.ts` | full DWF end-to-end | phase/log/args/budget/pipeline/agent/setResult integration |
+
+### Run in CI (manual dispatch)
+
+GitHub Actions → "Smoke (real-binary, manual)" → Run workflow → pick OS.
+Requires the `PI_AUTH_JSON` repo secret (the contents of `~/.pi/agent/auth.json`)
+so the spawned `pi` can authenticate with the model provider. If unset, the
+LLM-calling smoke tests fail with a clear auth error.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-crew",
-  "version": "0.9.5",
+  "version": "0.9.8",
   "description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
   "author": "baphuongna",
   "license": "MIT",
@@ -39,6 +39,7 @@
     "docs/",
     "tsconfig.json",
     "schema.json",
+    "types/",
     "CHANGELOG.md",
     "LICENSE",
     "NOTICE.md"
@@ -52,6 +53,7 @@
     "test:unit": "node scripts/test-runner.mjs --test-concurrency=4 --test-timeout=180000 --test-force-exit test/unit/*.test.ts",
     "test:watch": "tsx --watch --test --test-concurrency=4 --test-timeout=30000 --test-force-exit test/unit/*.test.ts",
     "test:integration": "node scripts/test-runner.mjs --test-concurrency=1 --test-timeout=120000 test/integration/*.test.ts",
+    "test:smoke": "node scripts/test-runner.mjs --test-concurrency=1 --test-timeout=180000 test/smoke/*.smoke.ts",
     "build:bundle": "node scripts/build-bundle.mjs",
     "bench": "node scripts/run-bench.mjs",
     "bench:check": "node scripts/bench-check.mjs",
@@ -63,7 +65,10 @@
     "smoke:release": "node scripts/release-smoke.mjs"
   },
   "exports": {
-    "./schema.json": "./schema.json"
+    "./schema.json": "./schema.json",
+    "./workflow": {
+      "types": "./types/dwf.d.ts"
+    }
   },
   "pi": {
     "extensions": [
@@ -81,10 +86,12 @@
   },
   "dependencies": {
     "@sinclair/typebox": "^0.34.49",
+    "acorn": "^8.17.0",
     "ajv": "^8.20.0",
     "cli-highlight": "^2.1.11",
     "diff": "^5.2.0",
-    "jiti": "^2.7.0"
+    "jiti": "^2.7.0",
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.15",

package/src/config/defaults.ts

@@ -16,10 +16,14 @@ export const DEFAULT_CHILD_PI: Readonly<{
 	// Keep this as a coarse stuck-worker guard rather than a short per-message latency budget.
 	responseTimeoutMs: 5 * 60_000,
 	maxCaptureBytes: 256 * 1024,
-	maxAssistantTextChars: 8192,
-	maxToolResultChars: 1024,
-	maxToolInputChars: 2048,
-	maxCompactContentChars: 4096,
+	// L4 output-handling: thresholds sized from real worker-output data
+	// (27 result artifacts measured: max 9226 bytes, median 8272, 100% < 16KB).
+	// Previous values (8192/1024/4096) truncated 62% of real results.
+	// See .crew/research/worker-output-handling.md + source/deer-flow/.research/.
+	maxAssistantTextChars: 16_384,
+	maxToolResultChars: 8_192,
+	maxToolInputChars: 4_096,
+	maxCompactContentChars: 8_192,
 };
 
 export const DEFAULT_LIVE_SESSION = {

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

@@ -10,6 +10,7 @@ import { DEFAULT_PATHS } from "../../config/defaults.ts";
 import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
 import { getPiSpawnCommand } from "../../runtime/pi-spawn.ts";
 import { getRuntimeWarmupStatus } from "../../runtime/runtime-warmup.ts";
+import { scanZombieSubagents, formatZombieReport } from "../../runtime/zombie-scanner.ts";
 import { validateResources } from "../validate-resources.ts";
 import { detectDrift, formatDriftReport, type DriftReport } from "../../config/drift-detector.ts";
 import { TeamToolParams } from "../../schema/team-tool-schema.ts";
@@ -237,6 +238,19 @@ export function buildTeamDoctorReport(input: TeamDoctorReportInput): TeamDoctorR
 }
 
 export function handleDoctor(ctx: TeamContext, params: TeamToolParamsValue = {}): PiTeamsToolResult {
+	// Sub-focus: zombie sub-agent scan. READ-ONLY — never kills. Returns a table of
+	// orphaned pi-crew sub-agents identified by the authoritative PI_CREW_KIND=subagent
+	// marker. The user's main session never carries that marker, so it can never appear.
+	if (params.focus === "zombies") {
+		const scan = scanZombieSubagents();
+		const text = formatZombieReport(scan);
+		return result(text, {
+			action: "doctor",
+			status: "ok",
+			data: { zombies: scan.zombies.length, live: scan.live.length, errors: scan.errors.length },
+		}, false);
+	}
+
 	const loadedConfig = loadConfig(ctx.cwd);
 	let smokeChildPi: { ok: boolean; detail: string } | undefined;
 	if (configRecord(params.config).smokeChildPi === true) {

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

@@ -281,6 +281,7 @@ export async function handleRun(params: TeamToolParamsValue, ctx: TeamContext):
 		workspaceMode: params.workspaceMode,
 		ownerSessionId: ctx.sessionId,
 		runKind: params.runKind,
+		args: params.args,
 	});
 	const goalArtifact = writeArtifact(paths.artifactsRoot, {
 		kind: "prompt",
@@ -323,6 +324,7 @@ export async function handleRun(params: TeamToolParamsValue, ctx: TeamContext):
 					team: dwfTeam,
 					signal: ctx.signal ?? AbortSignal.timeout(3_600_000),
 					modelOverride: params.model,
+					tokenBudget: params.tokenBudget ?? (workflow as import("../../workflows/workflow-config.ts").DynamicWorkflowConfig).maxTokenBudget,
 				});
 			} catch (runnerError) {
 				// Round-11 runtime fix: persist manifest with status=failed when runner throws

package/src/runtime/background-runner.ts

@@ -602,7 +602,7 @@ async function main(): Promise<void> {
 				const { allWorkflows, discoverWorkflows } = await import("../workflows/discover-workflows.ts");
 				const wf = allWorkflows(discoverWorkflows(manifest.cwd)).find((w) => w.name === manifest.workflow);
 				if (!wf || wf.runtime !== "dynamic" || !wf.dynamicScript) throw new Error(`runKind="dynamic-workflow" but workflow '${manifest.workflow}' is not dynamic (runId=${manifest.runId})`);
-				const dwfResult = await runDynamicWorkflow({ manifest, workflow: wf as import("../workflows/workflow-config.ts").DynamicWorkflowConfig, signal: abortController.signal });
+				const dwfResult = await runDynamicWorkflow({ manifest, workflow: wf as import("../workflows/workflow-config.ts").DynamicWorkflowConfig, signal: abortController.signal, tokenBudget: wf.maxTokenBudget });
 				saveRunManifest(dwfResult.manifest);
 				earlyResult = dwfResult;
 			}

package/src/runtime/capability-inventory.ts

@@ -2,7 +2,8 @@ import type { AgentConfig, ResourceSource } from "../agents/agent-config.ts";
 import { discoverAgents } from "../agents/discover-agents.ts";
 import { discoverTeams } from "../teams/discover-teams.ts";
 import { discoverWorkflows } from "../workflows/discover-workflows.ts";
-import { discoverSkills } from "../skills/discover-skills.ts";
+import { discoverSkills, getLastDiscoveryDiagnostics } from "../skills/discover-skills.ts";
+import type { SkillValidationError } from "../skills/validate.ts";
 import type { PiTeamsConfig } from "../config/config.ts";
 
 export type CapabilityKind = "team" | "workflow" | "agent" | "skill" | "tool" | "runtime";
@@ -114,3 +115,21 @@ export function buildCapabilityInventory(cwd: string, config?: PiTeamsConfig): C
 
 	return items.sort((a, b) => a.id.localeCompare(b.id));
 }
+
+/**
+ * L3: surface skill-validation diagnostics from the most recent
+ * `discoverSkills()` call. Skills that fail HARD validation are silently
+ * excluded from `buildCapabilityInventory()`; this function exposes the
+ * underlying errors so users see WHY a skill is missing instead of just
+ * noticing the absence.
+ *
+ * Soft warnings (unknown props, derived-name fallback) are also returned so
+ * skill authors can clean up their frontmatter over time.
+ *
+ * IMPORTANT: `discoverSkills()` is internally cached for 30s, so this
+ * function returns diagnostics from whichever call last populated the cache.
+ * Call `buildCapabilityInventory(cwd)` first to ensure a fresh pass.
+ */
+export function buildSkillValidationDiagnostics(): SkillValidationError[] {
+	return getLastDiscoveryDiagnostics();
+}

package/src/runtime/child-pi.ts

@@ -95,6 +95,17 @@ export function killProcessPid(pid: number): void {
 }
 
 function killProcessTree(pid: number | undefined, child?: ChildProcess): void {
+	// Phase-0 diagnostic (HB-003a): capture who invoked killProcessTree so the
+	// exit-null race has a provenance trail. .stack is best-effort (may be undefined
+	// under deep async), so we take a snapshot lazily.
+	try {
+		const callerStack = new Error("killProcessTree caller").stack ?? "(no stack)";
+		logInternalError(
+			"child-pi.kill-process-tree-invoked",
+			new Error(`pid=${pid} called from:\n${callerStack.split("\n").slice(0, 8).join("\n")}`),
+			`pid=${pid}`,
+		);
+	} catch { /* diagnostic best-effort */ }
 	if (!pid || !Number.isInteger(pid) || pid <= 0) return;
 	if (child && child.exitCode !== null) return;
 	killProcessPid(pid);
@@ -124,6 +135,18 @@ export interface ChildPiLifecycleEvent {
 	stderrExcerpt?: string;
 	/** Timestamp (ISO). */
 	ts: string;
+	/** Phase-0 diagnostic (HB-003a): the signal that killed the child (when
+	 *  available). Was previously discarded after building the error string. */
+	signal?: string;
+	/** Phase-0 diagnostic (HB-003a): final-drain race timing, present only on
+	 *  exit events where a drain timer was armed. Surfaces the exit-null race. */
+	diagnostic?: {
+		finalDrainArmed: boolean;
+		forcedFinalDrain: boolean;
+		finalDrainFiredMonotonicMs?: number;
+		finalAssistantEventMonotonicMs?: number;
+		exitMonotonicMs: number;
+	};
 }
 
 export interface ChildPiRunInput {
@@ -267,6 +290,9 @@ export function buildChildPiSpawnOptions(cwd: string, env: NodeJS.ProcessEnv): S
 			"PI_CREW_MAX_DEPTH",
 			"PI_CREW_INHERIT_PROJECT_CONTEXT",
 			"PI_CREW_INHERIT_SKILLS",
+			// PI_CREW_KIND marks this process as a crew sub-agent (vs the user's main session).
+			// doctor --zombies matches it to safely list orphaned sub-agents only.
+			"PI_CREW_KIND",
 			// PI_CREW_PARENT_PID is needed by child-pi's parent-guard (uses
 			// process.kill(pid, 0) liveness check). The PID is not a secret.
 			"PI_CREW_PARENT_PID",
@@ -354,7 +380,14 @@ function appendTranscript(input: ChildPiRunInput, line: string): void {
 
 function compactString(value: string, maxChars = MAX_COMPACT_CONTENT_CHARS): string {
 	if (value.length <= maxChars) return value;
-	return `${value.slice(0, maxChars)}\n[pi-crew compacted ${value.length - maxChars} chars]`;
+	// L4: head + tail instead of head-only. Keeps closing markdown structure
+	// (code fences, headings, list tails) instead of dropping them — the old
+	// head-only slice left unclosed ``` fences that downstream parsers and
+	// output-validator.ts flagged as "output may be truncated". Head gets 75%
+	// (opening structure + bulk of content); tail gets 25% (closing structure).
+	const head = Math.floor(maxChars * 0.75);
+	const tail = maxChars - head;
+	return `${value.slice(0, head)}\n...[pi-crew compacted ${value.length - maxChars} chars, head+tail preserved]...\n${value.slice(-tail)}`;
 }
 
 function compactValue(value: unknown): unknown {
@@ -577,6 +610,15 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 			let noResponseTimer: NodeJS.Timeout | undefined;
 			const finalDrainMs = input.finalDrainMs ?? FINAL_DRAIN_MS;
 			const hardKillMs = input.hardKillMs ?? HARD_KILL_MS;
+			// Phase-0 diagnostic (HB-003a): track the final-drain race that produces
+			// `exit null` for ctx.agent({disableTools:true}). These vars are READ-ONLY
+			// instrumentation — no behavior change. finalDrainArmed lets the close
+			// handler know a drain timer existed even after clearFinalDrainTimers() ran;
+			// spawnMonotonicMs gives us relative timing to distinguish a race from a crash.
+			let finalDrainArmed = false;
+			let finalDrainFiredMonotonicMs: number | undefined;
+			const spawnMonotonicMs = performance.now();
+			let finalAssistantEventMonotonicMs: number | undefined;
 			// FIX (Round 14): Bound the env-controlled response timeout to
 			// [1_000ms, 3_600_000ms] (1s–1h) so a hostile or accidental value
 			// (e.g. 1, or 999_999_999) cannot disable the timeout or cause
@@ -680,20 +722,27 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 								if (maxTurns !== undefined && !softLimitReached && turnCount >= maxTurns) {
 									softLimitReached = true;
 									// Inject steer via stdin to tell child to wrap up.
-									// If stdin is not writable or the write fails (backpressure/closed),
-									// the steer cannot be injected and the agent could run indefinitely.
-									// Kill the process tree in that case to enforce the turn limit.
+									// Steer injection is ADVISORY: it asks the worker to wrap up. The real
+									// enforcement is the hard-abort at maxTurns + graceTurns (below). So a
+									// failed/non-writable stdin must NOT kill the worker — that destroys a
+									// valid answer already in stdout (Phase-0 root cause of the
+									// disableTools/maxTurns:1 exit-null bug). Just log + let the hard-abort
+									// path handle a genuinely runaway worker.
 									if (child.stdin?.writable) {
 										const steerPayload = JSON.stringify({ type: "steer", message: "You have reached your turn limit. Wrap up immediately — provide your final answer now." }) + "\n";
 										const writeSucceeded = child.stdin.write(steerPayload);
 										if (!writeSucceeded) {
-											logInternalError("child-pi.steer-backpressure", new Error("stdin write returned false during steer injection; buffer full"), `pid=${child.pid}`);
-											steerInjectionFailed = true;
-											killProcessTree(child.pid, child);
+											// Normal Node backpressure: the payload is buffered and will flush on
+											// 'drain'. NOT a failure — do NOT kill the worker. The steer is
+											// advisory; if the worker ignores it and runs past maxTurns +
+											// graceTurns, the hard-abort below terminates it.
+											logInternalError("child-pi.steer-backpressure", new Error("stdin write returned false (normal backpressure); steer buffered, worker NOT killed"), `pid=${child.pid}`);
 										}
 									} else {
-										logInternalError("child-pi.steer-not-writable", new Error("stdin not writable when attempting steer injection"), `pid=${child.pid}`);
-										killProcessTree(child.pid, child);
+										// stdin closed (worker already finished) or otherwise unwritable.
+										// Also advisory — the worker is done or nearly done; let it exit
+										// naturally. Hard-abort remains the safety net for true runaways.
+										logInternalError("child-pi.steer-not-writable", new Error("stdin not writable when attempting steer injection (worker may be done); worker NOT killed"), `pid=${child.pid}`);
 									}
 								} else if (maxTurns !== undefined && softLimitReached && turnCount >= maxTurns + (graceTurns ?? 5)) {
 									// Hard abort — terminate after grace turns
@@ -708,9 +757,12 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 					}
 					input.onJsonEvent?.(event);
 					if (!isFinalAssistantEvent(event) || childExited || settled || finalDrainTimer) return;
+					finalAssistantEventMonotonicMs = performance.now();
+					finalDrainArmed = true; // Phase-0 diagnostic: track that a drain timer was created.
 					finalDrainTimer = setTimeout(() => {
 						if (settled || childExited) return;
 						forcedFinalDrain = true;
+						finalDrainFiredMonotonicMs = performance.now(); // Phase-0 diagnostic: race timing.
 						input.onLifecycleEvent?.({ type: "final_drain", pid: child.pid, ts: new Date().toISOString() });
 						try {
 							child.kill(process.platform === "win32" ? undefined : "SIGTERM");
@@ -765,7 +817,27 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 				}
 				// Catch all errors from settle to prevent unhandled rejection from propagating
 				try {
-					resolve({ ...result, exitStatus: result.exitStatus ?? { exitCode: result.exitCode, cancelled: abortRequested, timedOut: responseTimeoutHit, killed: hardKilled, cleanupErrors, finalDrainMs } });
+					resolve({
+						...result,
+						exitStatus: result.exitStatus ?? {
+							exitCode: result.exitCode,
+							cancelled: abortRequested,
+							timedOut: responseTimeoutHit,
+							killed: hardKilled,
+							// Phase-0 diagnostic (HB-003a): surface the final-drain race state.
+							// finalDrainArmed lets Phase 1 decide whether a signal-death (exitCode=null)
+							// should be treated as a forced final drain. READ-ONLY for now.
+							...(finalDrainArmed || forcedFinalDrain
+								? {
+										finalDrainArmed,
+										forcedFinalDrain,
+										finalDrainFiredMonotonicMs,
+								  }
+								: {}),
+							cleanupErrors,
+							finalDrainMs,
+						},
+					});
 				} catch (resolveError) {
 					logInternalError("child-pi.settle-resolve", resolveError, `result=${JSON.stringify({ exitCode: result.exitCode })}`);
 				}
@@ -866,7 +938,30 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 					rejectPendingOperations(exitError);
 				}
 				try {
-					input.onLifecycleEvent?.({ type: "exit", pid: child.pid, exitCode: code, ts: new Date().toISOString(), error: exitError?.message, stderrExcerpt: isUnexpectedExit ? stderr.slice(-1000) || undefined : undefined });
+					// Phase-0 diagnostic (HB-003a): capture signal + drain timing in the
+					// exit lifecycle event so the exit-null race is diagnosable instead of
+					// opaque. `signal` was previously discarded after building the error msg.
+					input.onLifecycleEvent?.({
+						type: "exit",
+						pid: child.pid,
+						exitCode: code,
+						ts: new Date().toISOString(),
+						error: exitError?.message,
+						stderrExcerpt: isUnexpectedExit ? stderr.slice(-1000) || undefined : undefined,
+						// Phase-0 diagnostic fields (kept optional — no type change required).
+						...(signal ? { signal } : {}),
+						...(finalDrainArmed || forcedFinalDrain
+							? {
+									diagnostic: {
+										finalDrainArmed,
+										forcedFinalDrain,
+										finalDrainFiredMonotonicMs,
+										finalAssistantEventMonotonicMs,
+										exitMonotonicMs: performance.now() - spawnMonotonicMs,
+									},
+							  }
+							: {}),
+					});
 				} catch (err) {
 					logInternalError("child-pi.on-lifecycle-event", err, `event=exit, pid=${child.pid}`);
 				}
@@ -902,6 +997,9 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 			const finalExitCode = forcedFinalDrain && !timeoutError ? 0 : exitCode;
 				const wasGraceAborted = softLimitReached && turnCount >= (maxTurns ?? 0) + (graceTurns ?? 5);
 				const wasParentAborted = abortDueToParentSignal && !wasGraceAborted;
+				// steerInjectionFailed is now always false (Phase-1 fix: steer backpressure
+				// is logged, not fatal). The steerError branch is retained for safety in
+				// case a future change reintroduces a fatal steer path.
 				const steerError = steerInjectionFailed ? "Steer injection failed due to stdin backpressure; process killed" : undefined;
 				settle({ exitCode: finalExitCode, stdout, stderr, ...(timeoutError ? { error: timeoutError.error } : {}), ...(steerError ? { error: steerError } : {}), aborted: wasGraceAborted || wasParentAborted, steered: softLimitReached && !wasGraceAborted, exitStatus: { exitCode: finalExitCode, cancelled: abortRequested, timedOut: responseTimeoutHit, killed: hardKilled, cleanupErrors, finalDrainMs } });
 			});

package/src/runtime/deterministic-ast.ts

@@ -0,0 +1,161 @@
+/**
+ * deterministic-ast.ts — AST-based determinism enforcement for dynamic-workflow scripts (round-13 P0-2).
+ *
+ * Rejects `Date.now()`, `Math.random()`, and `new Date()` at workflow-load time
+ * using a true AST walk (not regex) so that:
+ *   - Prompts mentioning "Date.now()" as string literals are accepted.
+ *   - Comments containing "Date.now()" are accepted.
+ *   - `Date.parse()`, `Date.UTC()`, `Math.floor()`, etc. are accepted (only `now` and `random` are blocked).
+ *
+ * Adapted from pi-dynamic-workflows/src/workflow.ts (MIT) — see NOTICE.md.
+ *
+ * The walker uses acorn's parse() with permissive flags (allowAwaitOutsideFunction,
+ * allowReturnOutsideFunction) so we don't reject perfectly valid workflow scripts
+ * that contain top-level `await` or `return`.
+ *
+ * On parse error, this function returns silently: jiti will surface a clearer
+ * parse error downstream. We don't double-report parse errors.
+ */
+
+import { parse } from "acorn";
+
+const NONDETERMINISM_ERROR =
+	"Workflow scripts must be deterministic: Date.now()/Math.random()/new Date() are unavailable. These introduce non-reproducible behavior across runs. Use ctx.vars for cached state, or pass a fixed seed via ctx.setArgs(). To bypass this check (escape hatch), set PI_CREW_DWF_SKIP_DETERMINISM_CHECK=1.";
+
+export class DeterminismError extends Error {
+	constructor() {
+		super(NONDETERMINISM_ERROR);
+		this.name = "DeterminismError";
+	}
+}
+
+/**
+ * Parse `script` and walk the AST looking for non-deterministic calls.
+ * Throws DeterminismError on the first hit. Silently returns on parse error
+ * (jiti will produce a clearer message downstream).
+ */
+export function assertDeterministicScript(script: string): void {
+	let ast: AstNode;
+	try {
+		ast = parse(script, {
+			ecmaVersion: "latest",
+			sourceType: "module",
+			allowAwaitOutsideFunction: true,
+			allowReturnOutsideFunction: true,
+			ranges: false,
+		}) as unknown as AstNode;
+	} catch {
+		// Parse errors are handled by jiti downstream — don't double-report.
+		return;
+	}
+	assertDeterministicAst(ast);
+}
+
+/**
+ * Escape hatch: when PI_CREW_DWF_SKIP_DETERMINISM_CHECK=1 the check is bypassed.
+ * Power users may need this when a workflow legitimately depends on time/random
+ * (e.g. randomized benchmark scripts).
+ */
+export function isDeterminismCheckEnabled(): boolean {
+	return process.env.PI_CREW_DWF_SKIP_DETERMINISM_CHECK !== "1";
+}
+
+// ---------------------------------------------------------------------------
+// AST walker
+// ---------------------------------------------------------------------------
+
+interface AstNode {
+	type: string;
+	[key: string]: unknown;
+}
+
+function asAstNode(value: unknown): AstNode | undefined {
+	if (!value || typeof value !== "object") return undefined;
+	const obj = value as Record<string, unknown>;
+	if (typeof obj.type !== "string") return undefined;
+	return obj as AstNode;
+}
+
+function astChildren(node: AstNode): AstNode[] {
+	const out: AstNode[] = [];
+	for (const value of Object.values(node)) {
+		if (Array.isArray(value)) {
+			for (const item of value) {
+				const child = asAstNode(item);
+				if (child) out.push(child);
+			}
+		} else {
+			const child = asAstNode(value);
+			if (child) out.push(child);
+		}
+	}
+	return out;
+}
+
+function assertDeterministicAst(node: AstNode): void {
+	if (isDateNowCall(node) || isMathRandomCall(node) || isNewDateExpression(node)) {
+		throw new DeterminismError();
+	}
+	for (const child of astChildren(node)) assertDeterministicAst(child);
+}
+
+function isDateNowCall(node: AstNode): boolean {
+	return node.type === "CallExpression" && isMemberExpression(node, "callee", "Date", "now");
+}
+
+function isMathRandomCall(node: AstNode): boolean {
+	return node.type === "CallExpression" && isMemberExpression(node, "callee", "Math", "random");
+}
+
+function isNewDateExpression(node: AstNode): boolean {
+	if (node.type !== "NewExpression") return false;
+	const callee = asAstNode(node.callee);
+	return callee?.type === "Identifier" && callee.name === "Date";
+}
+
+/**
+ * Test whether `node[childKey]` is a MemberExpression of shape `objectName.propertyName`,
+ * where the property is either a static Identifier or a resolvable static string.
+ * `childKey` is the property name on `node` (usually "callee" for CallExpression).
+ */
+function isMemberExpression(node: AstNode, childKey: string, objectName: string, propertyName: string): boolean {
+	const child = asAstNode(node[childKey]);
+	if (!child || child.type !== "MemberExpression") return false;
+	const object = asAstNode(child.object);
+	if (!object || object.type !== "Identifier" || object.name !== objectName) return false;
+	return propertyNameOf(child) === propertyName;
+}
+
+function propertyNameOf(node: AstNode): string | undefined {
+	const computed = node.computed === true;
+	const property = asAstNode(node.property);
+	if (!property) return undefined;
+	if (!computed && property.type === "Identifier") {
+		return property.name as string | undefined;
+	}
+	return staticStringOf(property);
+}
+
+function staticStringOf(node: AstNode | undefined): string | undefined {
+	if (!node) return undefined;
+	if (node.type === "Literal" && typeof node.value === "string") return node.value;
+	if (node.type === "TemplateLiteral") {
+		const expressions = node.expressions;
+		if (Array.isArray(expressions) && expressions.length > 0) return undefined;
+		const quasis = node.quasis;
+		if (!Array.isArray(quasis)) return undefined;
+		return quasis
+			.map((q) => {
+				const quasi = asAstNode(q);
+				const value = quasi?.value as { cooked?: string; raw?: string } | undefined;
+				return value?.cooked ?? value?.raw ?? "";
+			})
+			.join("");
+	}
+	if (node.type === "BinaryExpression" && node.operator === "+") {
+		const left = staticStringOf(asAstNode(node.left));
+		const right = staticStringOf(asAstNode(node.right));
+		if (left !== undefined && right !== undefined) return left + right;
+	}
+	return undefined;
+}