pi-crew 0.9.5 → 0.9.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-crew",
-  "version": "0.9.5",
+  "version": "0.9.7",
   "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,6 +86,7 @@
   },
   "dependencies": {
     "@sinclair/typebox": "^0.34.49",
+    "acorn": "^8.17.0",
     "ajv": "^8.20.0",
     "cli-highlight": "^2.1.11",
     "diff": "^5.2.0",

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/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",
@@ -577,6 +603,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 +715,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 +750,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 +810,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 +931,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 +990,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;
+}

package/src/runtime/dwf-state-store.ts

@@ -0,0 +1,97 @@
+/**
+ * dwf-state-store.ts — Persistent checkpoint state for dynamic-workflow runs (P2-3, round-18).
+ *
+ * Modeled on GoalStore (goal-state-store.ts) and FileCheckpointStore (checkpoint.ts),
+ * but scoped to a single run's stateRoot (which is already <crewRoot>/state/runs/<runId>).
+ *
+ * Stores DwfCheckpointState as atomic JSON at <stateRoot>/dwf-checkpoint.json.
+ * atomicWriteJson (temp + rename + fsync) guarantees either the old or the new file,
+ * never a partial write — safe across crashes.
+ *
+ * Resume semantics (round-18): the runner loads a checkpoint on run start and hydrates
+ * ctx.vars/phases/logs from it; on clean completion the runner deletes it. A missing or
+ * corrupt checkpoint is treated as a fresh run (load() returns undefined). If a crash
+ * happens mid-agent, that agent simply re-runs from scratch on resume — agent results
+ * are expected to be idempotent-ish.
+ */
+
+import { mkdirSync, existsSync, readFileSync, unlinkSync } from "node:fs";
+import { dirname } from "node:path";
+import { atomicWriteJson } from "../state/atomic-write.ts";
+import { logInternalError } from "../utils/internal-error.ts";
+
+export interface DwfCheckpointState {
+	runId: string;
+	vars: Record<string, unknown>;
+	phases: string[];
+	currentPhase: string | undefined;
+	logs: string[]; // capped copy (≤1000); the events log (dwf.log) is the durable source of truth
+	spent: number; // budget accumulator (round-14 P1-2)
+	agentCount: number;
+	updatedAt: string;
+}
+
+/**
+ * DwfStore — atomic CRUD for a single run's DWF checkpoint.
+ *
+ * Concurrency: writes are atomic (atomicWriteJson). The DWF runner is the sole
+ * writer during a run; `team resume` loads the checkpoint read-only before the
+ * script re-executes. No file-lock is needed here because only one runner owns a
+ * run's stateRoot at a time (run locks protect manifest transitions elsewhere).
+ *
+ * Note: the constructor takes the run's stateRoot directly (NOT cwd + runId) to
+ * avoid a double-nesting bug — stateRoot is already <crewRoot>/state/runs/<runId>,
+ * so the checkpoint lands at <crewRoot>/state/runs/<runId>/dwf-checkpoint.json.
+ * This mirrors FileCheckpointStore (checkpoint.ts: constructor(stateRoot)).
+ */
+export class DwfStore {
+	private readonly stateRoot: string;
+
+	constructor(stateRoot: string) {
+		this.stateRoot = stateRoot;
+	}
+
+	private get path(): string {
+		return `${this.stateRoot}/dwf-checkpoint.json`;
+	}
+
+	/** Load the checkpoint for this run's stateRoot. Returns undefined if missing or corrupt (fresh run). */
+	load(): DwfCheckpointState | undefined {
+		const path = this.path;
+		try {
+			if (!existsSync(path)) return undefined;
+			const raw = readFileSync(path, "utf-8");
+			const parsed = JSON.parse(raw);
+			// Corrupt-guard: a valid checkpoint must be an object with a string runId
+			// (mirrors GoalStore.load's typeof parsed.goalId !== "string" check).
+			if (!parsed || typeof parsed !== "object" || typeof parsed.runId !== "string") return undefined;
+			return parsed as DwfCheckpointState;
+		} catch {
+			return undefined;
+		}
+	}
+
+	/** Atomically persist a checkpoint state. Stamps `updatedAt` (callers need not set it). */
+	save(state: DwfCheckpointState): void {
+		const path = this.path;
+		const next = { ...state, updatedAt: new Date().toISOString() };
+		try {
+			mkdirSync(dirname(path), { recursive: true });
+			atomicWriteJson(path, next);
+		} catch (error) {
+			logInternalError("dwf-state-store.save", error, `runId=${state.runId}`);
+			throw error;
+		}
+	}
+
+	/** Remove the checkpoint file (after a clean completion). Best-effort; never throws. */
+	delete(): void {
+		const path = this.path;
+		try {
+			if (!existsSync(path)) return;
+			unlinkSync(path);
+		} catch (error) {
+			logInternalError("dwf-state-store.delete", error);
+		}
+	}
+}