@bastani/atomic 0.9.11-alpha.9 → 0.9.11

package/dist/builtin/workflows/src/shared/graph-store-snapshot.ts

@@ -0,0 +1,144 @@
+import { flattenTruncatedString } from "./flat-string.js";
+import type {
+	PendingPrompt,
+	RunSnapshot,
+	StageInputRequest,
+	StageSnapshot,
+	StoreSnapshot,
+	ToolEvent,
+	ToolNodeSnapshot,
+	WorkflowChildReplaySnapshot,
+	WorkflowNotice,
+} from "./store-types.js";
+import type { WorkflowOutputValues, WorkflowSerializableValue } from "./types.js";
+
+export const COMPACT_RESULT_FIELD_LIMIT = 1024;
+
+function compactResultField(value: WorkflowSerializableValue | undefined): string | undefined {
+	if (typeof value !== "string") return undefined;
+	if (value.length <= COMPACT_RESULT_FIELD_LIMIT) return value;
+	// Flattened, not just sliced: `graphSnapshot()` memoizes this projection, so a
+	// SlicedString here would keep the whole run result alive inside the store.
+	return flattenTruncatedString(value.slice(0, COMPACT_RESULT_FIELD_LIMIT));
+}
+
+function compactRunResult(result: WorkflowOutputValues | undefined): WorkflowOutputValues | undefined {
+	if (result === undefined) return undefined;
+	const status = compactResultField(result.status);
+	const summary = compactResultField(result.summary);
+	const remainingWork = compactResultField(result.remaining_work);
+	const resultText = compactResultField(result.result);
+	const compact: WorkflowOutputValues = {
+		...(status !== undefined ? { status } : {}),
+		...(summary !== undefined ? { summary } : {}),
+		...(remainingWork !== undefined ? { remaining_work: remainingWork } : {}),
+		...(resultText !== undefined ? { result: resultText } : {}),
+	};
+	return Object.keys(compact).length === 0 ? undefined : compact;
+}
+
+// Both cloners are called only from a `!== undefined` guard at their call sites,
+// so they take and return a concrete value; an internal undefined branch here
+// would be unreachable and would only weaken the type for every caller.
+function clonePrompt(prompt: PendingPrompt): PendingPrompt {
+	return {
+		...prompt,
+		...(prompt.choices !== undefined ? { choices: [...prompt.choices] } : {}),
+	};
+}
+
+function cloneInputRequest(request: StageInputRequest): StageInputRequest {
+	return {
+		...request,
+		questions: request.questions.map((question) => ({
+			...question,
+			options: question.options.map((option) => ({ ...option })),
+		})),
+	};
+}
+
+function compactToolEvents(events: readonly ToolEvent[]): ToolEvent[] {
+	const event = events.at(-1);
+	return event === undefined ? [] : [{ name: event.name }];
+}
+
+function compactWorkflowChild(child: WorkflowChildReplaySnapshot): WorkflowChildReplaySnapshot {
+	return {
+		...child,
+		outputs: {},
+		outputCount: child.outputCount ?? Object.keys(child.outputs).length,
+	};
+}
+
+function compactStage(stage: StageSnapshot): StageSnapshot {
+	const {
+		toolEvents,
+		workflowChild,
+		workflowChildRun,
+		pendingPrompt,
+		promptFootprint,
+		inputRequest,
+		notices,
+		mcpScope: _mcpScope,
+		attemptedModels: _attemptedModels,
+		modelAttempts: _modelAttempts,
+		// Agent-stage results can be unbounded and graph cards do not render
+		// them. Durable tool cards use ToolNodeSnapshot.resultSummary instead.
+		result: _result,
+		...metadata
+	} = stage;
+	return {
+		...metadata,
+		parentIds: [...stage.parentIds],
+		toolEvents: compactToolEvents(toolEvents),
+		...(workflowChild !== undefined ? { workflowChild: compactWorkflowChild(workflowChild) } : {}),
+		...(workflowChildRun !== undefined ? { workflowChildRun: { ...workflowChildRun } } : {}),
+		...(pendingPrompt !== undefined ? { pendingPrompt: clonePrompt(pendingPrompt) } : {}),
+		...(promptFootprint !== undefined ? { promptFootprint: clonePrompt(promptFootprint) } : {}),
+		...(inputRequest !== undefined ? { inputRequest: cloneInputRequest(inputRequest) } : {}),
+		...(notices !== undefined ? { notices: notices.map((notice) => ({ ...notice })) } : {}),
+	};
+}
+
+function compactToolNode(node: ToolNodeSnapshot): ToolNodeSnapshot {
+	return { ...node, parentIds: [...node.parentIds] };
+}
+
+function compactRun(run: RunSnapshot): RunSnapshot {
+	const { inputs: _inputs, result: sourceResult, stages, toolNodes, pendingPrompt, ...metadata } = run;
+	const result = compactRunResult(sourceResult);
+	return {
+		...metadata,
+		inputs: {},
+		stages: stages.map(compactStage),
+		...(toolNodes !== undefined ? { toolNodes: toolNodes.map(compactToolNode) } : {}),
+		...(pendingPrompt !== undefined ? { pendingPrompt: clonePrompt(pendingPrompt) } : {}),
+		...(result !== undefined ? { result } : {}),
+	};
+}
+
+export function createGraphStoreSnapshot(
+	runs: readonly RunSnapshot[],
+	notices: readonly WorkflowNotice[],
+	version: number,
+): StoreSnapshot {
+	const snapshot: StoreSnapshot = {
+		runs: runs.map(compactRun),
+		notices: notices.map((notice) => ({ ...notice })),
+		version,
+	};
+	deepFreezeGraphValue(snapshot);
+	return snapshot;
+}
+
+function deepFreezeGraphValue(value: unknown): void {
+	if (value === null || typeof value !== "object" || Object.isFrozen(value)) return;
+	Object.freeze(value);
+	if (Array.isArray(value)) {
+		for (const item of value) deepFreezeGraphValue(item);
+		return;
+	}
+	for (const key of Object.keys(value as Record<string, unknown>)) {
+		deepFreezeGraphValue((value as Record<string, unknown>)[key]);
+	}
+}

package/dist/builtin/workflows/src/shared/persistence-session-entries.ts

@@ -139,7 +139,7 @@ export interface RunBlockedPayload {
 
 /**
  * Appends a `workflow.run.start` entry and labels it for /tree filtering.
- * Label format: `wf:<name>:<short-id>` (first 8 chars of runId).
+ * Label format: `wf:<name>:<full-run-id>`.
  */
 export function appendRunStart(api: PersistenceAPI, payload: RunStartPayload): void {
 	if (typeof api.appendEntry !== "function") return;
@@ -156,8 +156,7 @@ export function appendRunStart(api: PersistenceAPI, payload: RunStartPayload): v
 		ts: payload.ts,
 	});
 	if (entryId && typeof api.setLabel === "function") {
-		const shortId = payload.runId.slice(0, 8);
-		api.setLabel(entryId, `wf:${payload.name}:${shortId}`);
+		api.setLabel(entryId, `wf:${payload.name}:${payload.runId}`);
 	}
 }
 

package/dist/builtin/workflows/src/shared/run-id.ts

@@ -0,0 +1,36 @@
+/**
+ * The run identifier contract.
+ *
+ * A run id is a bare `crypto.randomUUID()` value (see `extension/dispatcher.ts`),
+ * and the durable DBOS `workflowId` is that same value. Every user-facing surface
+ * renders it in full, so every resolver accepts it only in full: there is no
+ * unique-prefix fallback and no truncated form that addresses a run.
+ *
+ * This lives in `shared/` because both the extension resolvers and the durable
+ * catalog need it, and `durable/` must not import from `extension/`.
+ */
+
+/** Canonical rendered length of a run id, dashes included. */
+export const RUN_ID_LENGTH = 36;
+
+const RUN_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * True only for a full 8-4-4-4-12 hex UUID.
+ *
+ * Rejects a prefix, a 32-character dashless form, and a 36-character string that
+ * is the right length but not hex — a transposed or truncated paste should fail
+ * loudly here rather than silently miss during lookup.
+ */
+export function isFullRunId(value: string): boolean {
+	return RUN_ID_PATTERN.test(value);
+}
+
+/**
+ * Reported instead of "not found" so a truncated paste is diagnosable as
+ * truncated. A well-formed id that no run happens to carry is a different
+ * failure and keeps the not-found message.
+ */
+export function malformedRunIdMessage(target: string): string {
+	return `Run id must be a full ${RUN_ID_LENGTH}-character UUID; got "${target}" (${target.length} chars).`;
+}

package/dist/builtin/workflows/src/shared/store-internal.ts

@@ -1,3 +1,4 @@
+import { createGraphStoreSnapshot } from "./graph-store-snapshot.js";
 import type { PromptAnswerRecord, RunEndMetadata } from "./store-public-types.js";
 import type {
 	PendingPrompt,
@@ -42,6 +43,7 @@ export interface StoreState {
 	readonly runs: RunSnapshot[];
 	readonly notices: WorkflowNotice[];
 	readonly listeners: Set<(snap: StoreSnapshot) => void>;
+	readonly invalidationListeners: Set<() => void>;
 	readonly resolvers: Map<string, ResolverEntry>;
 	readonly stagePromptAnswers: Map<string, PromptAnswerRecord>;
 	readonly stagePromptDrafts: Map<string, string>;
@@ -51,6 +53,7 @@ export interface StoreState {
 export interface StoreContext {
 	readonly state: StoreState;
 	snapshot(): StoreSnapshot;
+	graphSnapshot(): StoreSnapshot;
 	notify(): void;
 	bumpAndNotify(): void;
 	findRun(runId: string): RunSnapshot | undefined;
@@ -128,6 +131,7 @@ export function createStoreState(): StoreState {
 		runs: [],
 		notices: [],
 		listeners: new Set(),
+		invalidationListeners: new Set(),
 		resolvers: new Map(),
 		stagePromptAnswers: new Map(),
 		stagePromptDrafts: new Map(),
@@ -136,16 +140,40 @@ export function createStoreState(): StoreState {
 }
 
 export function createStoreContext(state: StoreState = createStoreState()): StoreContext {
+	let cachedGraphVersion = -1;
+	let cachedGraphSnapshot: StoreSnapshot | undefined;
+
 	function snapshot(): StoreSnapshot {
 		return JSON.parse(
 			JSON.stringify({ runs: state.runs, notices: state.notices, version: state.version }),
 		) as StoreSnapshot;
 	}
 
+	function graphSnapshot(): StoreSnapshot {
+		if (cachedGraphSnapshot === undefined || cachedGraphVersion !== state.version) {
+			cachedGraphSnapshot = createGraphStoreSnapshot(state.runs, state.notices, state.version);
+			cachedGraphVersion = state.version;
+		}
+		return cachedGraphSnapshot;
+	}
+
 	function notify(): void {
-		const snap = snapshot();
-		for (const fn of state.listeners) {
-			fn(snap);
+		for (const fn of state.invalidationListeners) {
+			try {
+				fn();
+			} catch {
+				// One observer must not starve later observers or the snapshot channel.
+			}
+		}
+		if (state.listeners.size > 0) {
+			const snap = snapshot();
+			for (const fn of state.listeners) {
+				try {
+					fn(snap);
+				} catch {
+					// Store mutations remain authoritative when a consumer fails.
+				}
+			}
 		}
 	}
 
@@ -209,6 +237,7 @@ export function createStoreContext(state: StoreState = createStoreState()): Stor
 	return {
 		state,
 		snapshot,
+		graphSnapshot,
 		notify,
 		bumpAndNotify,
 		findRun,

package/dist/builtin/workflows/src/shared/store-observation.ts

@@ -0,0 +1,10 @@
+import type { Store } from "./store-public-types.js";
+import type { StoreSnapshot } from "./store-types.js";
+
+export function readGraphStoreSnapshot(store: Store): StoreSnapshot {
+	return store.graphSnapshot();
+}
+
+export function subscribeStoreInvalidation(store: Store, listener: () => void): () => void {
+	return store.subscribeInvalidation(listener);
+}

package/dist/builtin/workflows/src/shared/store-public-types.ts

@@ -228,5 +228,13 @@ export interface Store {
 	/** Drop every run and notice. */
 	clear(): void;
 	snapshot(): StoreSnapshot;
+	/**
+	 * Return one immutable payload-free graph projection per store version.
+	 * Graph-visible state may change only through a version-bumping store method;
+	 * direct mutation of values returned by `runs()` would leave this cache stale.
+	 */
+	graphSnapshot(): StoreSnapshot;
 	subscribe(fn: (snap: StoreSnapshot) => void): () => void;
+	/** Subscribe synchronously to store invalidation without constructing a full snapshot. */
+	subscribeInvalidation(fn: () => void): () => void;
 }

package/dist/builtin/workflows/src/shared/store-run-methods.ts

@@ -27,7 +27,9 @@ type RunStoreMethods = Pick<
 	| "recordRunResumed"
 	| "clear"
 	| "snapshot"
+	| "graphSnapshot"
 	| "subscribe"
+	| "subscribeInvalidation"
 >;
 
 export function createRunStoreMethods(context: StoreContext): RunStoreMethods {
@@ -179,6 +181,7 @@ export function createRunStoreMethods(context: StoreContext): RunStoreMethods {
 			if (!run) return false;
 			if (TERMINAL_STATUSES.has(run.status)) return false;
 			const wasPaused = run.status === "paused";
+			const enteringQuit = metadata?.exitReason === "quit" && run.exitReason !== "quit";
 			if (!wasPaused) {
 				run.status = "paused";
 				run.pausedAt = pausedAt ?? Date.now();
@@ -186,6 +189,7 @@ export function createRunStoreMethods(context: StoreContext): RunStoreMethods {
 			}
 			if (metadata?.resumable !== undefined) run.resumable = metadata.resumable;
 			if (metadata?.exitReason !== undefined) run.exitReason = metadata.exitReason;
+			if (enteringQuit) run.quitAt = Date.now();
 			if (wasPaused && metadata === undefined) return false;
 			context.bumpAndNotify();
 			return true;
@@ -201,6 +205,7 @@ export function createRunStoreMethods(context: StoreContext): RunStoreMethods {
 			run.pausedDurationMs = accumulatePausedDurationMs(run.pausedDurationMs, run.pausedAt, resumedTs);
 			run.resumedAt = resumedTs;
 			run.pausedAt = undefined;
+			delete run.quitAt;
 			delete run.exitReason;
 			context.bumpAndNotify();
 			return true;
@@ -230,12 +235,21 @@ export function createRunStoreMethods(context: StoreContext): RunStoreMethods {
 			return context.snapshot();
 		},
 
+		graphSnapshot(): StoreSnapshot {
+			return context.graphSnapshot();
+		},
+
 		subscribe(fn: (snap: StoreSnapshot) => void): () => void {
 			state.listeners.add(fn);
 			return () => {
 				state.listeners.delete(fn);
 			};
 		},
+
+		subscribeInvalidation(fn: () => void): () => void {
+			state.invalidationListeners.add(fn);
+			return () => state.invalidationListeners.delete(fn);
+		},
 	};
 }
 

package/dist/builtin/workflows/src/shared/store-types.ts

@@ -153,6 +153,8 @@ export interface WorkflowChildReplaySnapshot {
 	/** True when the child reached this terminal status through ctx.exit(). */
 	readonly exited?: boolean;
 	readonly outputs: WorkflowOutputValues;
+	/** Payload-free output count used by compact graph projections. */
+	readonly outputCount?: number;
 	readonly exitReason?: string;
 }
 
@@ -282,6 +284,8 @@ export interface RunSnapshot {
 	pausedDurationMs?: number;
 	/** Timestamp set when a controlled pause begins; cleared on resume. */
 	pausedAt?: number;
+	/** Timestamp when the run entered resumable quit state; display-only expiry marker. */
+	quitAt?: number;
 	/** Timestamp recorded on the most recent resume from a paused state. */
 	resumedAt?: number;
 	result?: WorkflowOutputValues;

package/dist/builtin/workflows/src/shared/types.ts

@@ -392,6 +392,8 @@ export interface WorkflowRunContext<
 > {
 	/** Typed inputs provided by the caller, validated against the input schema. */
 	readonly inputs: TInputs;
+	/** Stable owning workflow-run id for durable run-scoped artifacts. */
+	readonly runId?: string;
 	/** Invocation working directory for workflow-owned artifacts. Defaults to the host process cwd when omitted. */
 	readonly cwd?: string;
 	/** Intentionally end this workflow run from any call depth. */

package/dist/builtin/workflows/src/shared/workflow-artifacts.ts

@@ -0,0 +1,261 @@
+import { randomUUID } from "node:crypto";
+import { existsSync } from "node:fs";
+import { mkdir, readdir, rm, stat } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { getAgentDir, getEnvValue } from "@bastani/atomic";
+import type { DurableWorkflowBackend } from "../durable/backend.js";
+import { getDurableBackend } from "../durable/factory.js";
+import { type WorkflowRunResumeCandidate, workflowRunHasPausedState } from "../durable/resume-eligibility.js";
+import { store } from "./store.js";
+import type { RunSnapshot } from "./store-types.js";
+
+/** Maximum age of durable workflow run artifacts before the next workflow write prunes them. */
+export const WORKFLOW_ARTIFACT_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
+
+/** Overrides the durable workflow-artifact root, mirroring the agent-directory override convention. */
+export const ENV_WORKFLOW_ARTIFACT_DIR = "ATOMIC_WORKFLOW_ARTIFACT_DIR";
+
+export type WorkflowArtifactRunState = "protected" | "terminal" | "orphan";
+export type WorkflowArtifactRunStateResolver = (runId: string) => WorkflowArtifactRunState | undefined;
+
+const ARTIFACT_PRUNE_RECHECK_MS = 60 * 60 * 1000;
+const lastArtifactPruneAt = new Map<string, number>();
+const pendingArtifactPrunes = new Map<string, Promise<void>>();
+
+function workflowArtifactRoot(): string {
+	const override = getEnvValue(ENV_WORKFLOW_ARTIFACT_DIR);
+	if (override !== undefined && override.length > 0) return override;
+	return join(dirname(getAgentDir()), "workflows");
+}
+
+export function workflowArtifactRunsRoot(): string {
+	return join(workflowArtifactRoot(), "runs");
+}
+
+function safeRunId(runId: string): string {
+	const safe = runId.replace(/[^A-Za-z0-9._-]/g, "_");
+	return safe.length > 0 ? safe : "run";
+}
+
+export function workflowArtifactRunPath(runId: string): string {
+	return join(workflowArtifactRunsRoot(), safeRunId(runId));
+}
+
+/**
+ * Detect a run-scoped artifact path anywhere in a run's result or stages.
+ *
+ * `JSON.stringify` escapes each Windows separator, so `…\runs\<id>\…` serializes
+ * as `…\\runs\\<id>\\…` and a single backslash-to-slash pass leaves `//runs//`.
+ * Collapsing repeated separators after that pass makes the probe behave the same
+ * on both platforms; without it every Windows artifact reference was invisible,
+ * so no run was ever reported as having lost its artifacts.
+ */
+export function workflowRunHasArtifactReference(run: Pick<RunSnapshot, "id" | "result" | "stages">): boolean {
+	const serialized = JSON.stringify({ result: run.result, stages: run.stages });
+	if (serialized === undefined) return false;
+	const normalized = serialized.replaceAll("\\", "/").replace(/\/{2,}/g, "/");
+	return normalized.includes(`/runs/${safeRunId(run.id)}/`);
+}
+
+/** Return artifact integrity only for runs whose snapshot names a run-scoped artifact. */
+export function workflowRunArtifactsIntact(run: Pick<RunSnapshot, "id" | "result" | "stages">): boolean | undefined {
+	if (!workflowRunHasArtifactReference(run)) return undefined;
+	return existsSync(workflowArtifactRunPath(run.id));
+}
+
+/** Build the one resume candidate shape used by all live-run resume surfaces. */
+export function workflowRunResumeCandidate(run: RunSnapshot): WorkflowRunResumeCandidate {
+	const artifactsIntact = workflowRunArtifactsIntact(run);
+	let hasDurableCheckpoint: boolean | undefined;
+	try {
+		hasDurableCheckpoint = getDurableBackend().isWorkflowLoadable(run.id);
+	} catch {
+		// A backend that is not ready cannot prove a missing checkpoint.
+	}
+	return {
+		...run,
+		hasPausedState: workflowRunHasPausedState(run),
+		...(hasDurableCheckpoint === undefined ? {} : { hasDurableCheckpoint }),
+		...(artifactsIntact === undefined ? {} : { artifactsIntact }),
+	};
+}
+
+/**
+ * Protection means live work, not "could theoretically be resumed".
+ *
+ * A run still in flight, holding a pending prompt, or explicitly quit keeps its
+ * artifacts indefinitely, because a resume is expected and those files are its
+ * inputs. A run that has FAILED is terminal: it is retryable, but the retention
+ * window is precisely the grace period it gets. Treating `resumable === true` as
+ * protection made every failed run permanent, so repeated recoverable failures
+ * accumulated run-scoped artifacts that the advertised window never reclaimed.
+ */
+function storeRunState(run: RunSnapshot): WorkflowArtifactRunState {
+	const hasPendingInput =
+		run.pendingPrompt !== undefined ||
+		run.stages.some(
+			(stage) => stage.status === "awaiting_input" || stage.status === "paused" || stage.status === "blocked",
+		);
+	if (
+		hasPendingInput ||
+		run.status === "pending" ||
+		run.status === "running" ||
+		run.status === "paused" ||
+		run.status === "blocked" ||
+		run.exitReason === "quit"
+	) {
+		return "protected";
+	}
+	return "terminal";
+}
+
+function durableRunState(backend: DurableWorkflowBackend, runId: string): WorkflowArtifactRunState | undefined {
+	const handle = backend.getLoadableWorkflow(runId);
+	if (handle === undefined) return undefined;
+	// `isDurableWorkflowResumable` deliberately accepts `failed`, so it cannot be
+	// used here: it would pin a failed run's artifacts forever.
+	if (
+		handle.status === "running" ||
+		handle.status === "paused" ||
+		handle.status === "blocked" ||
+		handle.pendingPrompts > 0
+	) {
+		return "protected";
+	}
+	return "terminal";
+}
+
+/**
+ * Snapshot the live store and durable backend once for a pruning pass. This
+ * keeps the transcript write path from querying durable state once per stage.
+ */
+export function createWorkflowArtifactRunStateResolver(): WorkflowArtifactRunStateResolver {
+	const localRuns = new Map(store.runs().map((run) => [run.id, run]));
+	let backend: DurableWorkflowBackend | undefined;
+	let backendReady = true;
+	try {
+		backend = getDurableBackend();
+	} catch {
+		backendReady = false;
+	}
+	return (runId: string): WorkflowArtifactRunState | undefined => {
+		const local = localRuns.get(runId) ?? [...localRuns.values()].find((run) => safeRunId(run.id) === runId);
+		const localState = local === undefined ? undefined : storeRunState(local);
+		if (!backendReady) {
+			// An unavailable durable backend cannot prove that even a terminal-looking
+			// local snapshot has no resumable durable counterpart.
+			return localState === "protected" ? "protected" : undefined;
+		}
+		let durable: WorkflowArtifactRunState | undefined;
+		if (backend !== undefined) {
+			try {
+				durable = durableRunState(backend, runId);
+			} catch {
+				backendReady = false;
+				return localState === "protected" ? "protected" : undefined;
+			}
+		}
+		if (durable === "protected" || localState === "protected") return "protected";
+		if (durable === "terminal" || localState === "terminal") return "terminal";
+		return "orphan";
+	};
+}
+
+/** Resolve one run's artifact ownership from a fresh durable/store snapshot. */
+export function resolveWorkflowArtifactRunState(runId: string): WorkflowArtifactRunState | undefined {
+	return createWorkflowArtifactRunStateResolver()(runId);
+}
+
+/** Delete the durable owner of a terminal run before its artifacts are removed. */
+async function deleteTerminalDurableEntry(runId: string): Promise<boolean> {
+	let backend: DurableWorkflowBackend;
+	try {
+		backend = getDurableBackend();
+	} catch {
+		return false;
+	}
+	try {
+		const result = await backend.deleteWorkflowIfInactive(runId);
+		return result.ok || result.reason === "not_found";
+	} catch {
+		return false;
+	}
+}
+
+/** Remove stale run directories, retaining artifacts for resumable/non-terminal runs. */
+export async function pruneWorkflowArtifactRuns(
+	root = workflowArtifactRunsRoot(),
+	now = Date.now(),
+	stateResolver?: WorkflowArtifactRunStateResolver,
+): Promise<void> {
+	try {
+		const entries = await readdir(root, { withFileTypes: true, encoding: "utf8" });
+		for (const entry of entries) {
+			if (!entry.isDirectory()) continue;
+			const entryPath = join(root, entry.name);
+			let metadata: Awaited<ReturnType<typeof stat>>;
+			try {
+				metadata = await stat(entryPath);
+			} catch (error) {
+				if (error instanceof Error && "code" in error && error.code === "ENOENT") continue;
+				throw error;
+			}
+			if (now - metadata.mtimeMs <= WORKFLOW_ARTIFACT_RETENTION_MS) continue;
+			// Without authoritative state, preserve the directory. An unknown run is
+			// not safe to classify as history merely because its mtime is old.
+			if (stateResolver === undefined) continue;
+			const state = stateResolver(entry.name);
+			if (state !== "terminal" && state !== "orphan") continue;
+			// Delete the durable owner first. If authoritative deletion is unavailable
+			// or refuses an active run, preserve the directory rather than leaving a
+			// durable entry pointing at missing artifacts.
+			if (state === "terminal" && !(await deleteTerminalDurableEntry(entry.name))) continue;
+			await rm(entryPath, { recursive: true, force: true });
+		}
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code === "ENOENT") return;
+		throw error;
+	}
+}
+
+async function pruneArtifactRootIfDue(root: string, now: number): Promise<void> {
+	const pending = pendingArtifactPrunes.get(root);
+	if (pending !== undefined) {
+		try {
+			await pending;
+		} catch {
+			// Pruning is opportunistic and must never block a stage artifact write.
+		}
+		return;
+	}
+	const previous = lastArtifactPruneAt.get(root);
+	if (previous !== undefined && now - previous < ARTIFACT_PRUNE_RECHECK_MS) return;
+	const operation = pruneWorkflowArtifactRuns(root, now, createWorkflowArtifactRunStateResolver());
+	pendingArtifactPrunes.set(root, operation);
+	try {
+		await operation;
+	} catch {
+		// A stale sibling that cannot be inspected is retained; writes continue.
+	} finally {
+		lastArtifactPruneAt.set(root, now);
+		pendingArtifactPrunes.delete(root);
+	}
+}
+
+/** Ensure a run-scoped durable directory exists and perform bounded state-aware GC at most hourly. */
+export async function ensureWorkflowArtifactRunDirectory(runId: string): Promise<string> {
+	const root = workflowArtifactRunsRoot();
+	await pruneArtifactRootIfDue(root, Date.now());
+	const directory = workflowArtifactRunPath(runId);
+	await mkdir(directory, { recursive: true });
+	return directory;
+}
+
+/** Create a unique durable artifact directory beneath the owning run and prune expired siblings. */
+export async function createWorkflowArtifactDirectory(runId?: string): Promise<string> {
+	const effectiveRunId = runId ?? randomUUID();
+	const runDirectory = await ensureWorkflowArtifactRunDirectory(effectiveRunId);
+	const artifactDirectory = join(runDirectory, `artifact-${randomUUID()}`);
+	await mkdir(artifactDirectory, { recursive: true });
+	return artifactDirectory;
+}