@bastani/atomic 0.9.16-alpha.2 → 0.9.16-alpha.4

package/dist/builtin/workflows/src/runs/background/quit.ts

@@ -1,417 +0,0 @@
-import type { DurableWorkflowBackend } from "../../durable/backend.js";
-import { getDurableBackend } from "../../durable/factory.js";
-import { recordRunTimingCheckpoint } from "../../durable/run-timing.js";
-import {
-	getLoadableDurableWorkflow,
-	transitionDurableWorkflowStatus,
-} from "../../durable/workflow-status-transition.js";
-import type { ToolAdmissionBoundary } from "../../engine/run-tool-admission-boundary.js";
-import {
-	toolControlRegistry as defaultToolControlRegistry,
-	sameToolNodeIdentity,
-	settleAbortedToolNodes,
-	TOOL_QUIT_SETTLEMENT_TIMEOUT_MS,
-	type ToolControlHandle,
-	type ToolControlRegistry,
-} from "../../engine/run-tool-control-registry.js";
-import { WorkflowGracefulQuitError } from "../../engine/workflow-tool-abort.js";
-import { expandWorkflowGraph } from "../../shared/expanded-workflow-graph.js";
-import { topLevelWorkflowRuns } from "../../shared/run-visibility.js";
-import { store as defaultStore } from "../../shared/store.js";
-import { readGraphStoreSnapshot } from "../../shared/store-observation.js";
-import type { Store } from "../../shared/store-public-types.js";
-import type { RunSnapshot, StageSnapshot, WorkflowActor } from "../../shared/store-types.js";
-import type { WorkflowCancelledToolNode, WorkflowToolNodeIdentity } from "../../shared/types.js";
-import {
-	stageControlRegistry as defaultStageControlRegistry,
-	type StageControlHandle,
-	type StageControlRegistry,
-} from "../foreground/stage-control-registry.js";
-import { jobTracker as defaultJobTracker, type JobTracker } from "./job-tracker.js";
-import { expandedControlRunIds } from "./workflow-lifecycle-aggregate.js";
-
-export type QuitRunResult =
-	| {
-			readonly ok: true;
-			readonly runId: string;
-			readonly paused: readonly StageSnapshot[];
-			/** Tool nodes aborted by this quit, settled or abandoned, with owning run. */
-			readonly cancelledTools: readonly WorkflowCancelledToolNode[];
-			/** Aborted nodes whose callback ignored its signal within the bounded wait. */
-			readonly abandonedTools: readonly WorkflowToolNodeIdentity[];
-	  }
-	| {
-			readonly ok: false;
-			readonly runId: string;
-			readonly reason: "not_found" | "already_ended" | "no_active_stages" | "stage_not_found";
-	  };
-
-type QuitAllRunResult =
-	| QuitRunResult
-	| {
-			readonly ok: false;
-			readonly runId: string;
-			readonly reason: "pause_failed";
-			readonly message: string;
-	  };
-
-/**
- * Gracefully quit workflow work without destructive cancellation.
- *
- * This is the graceful public quit primitive. Order matters, because quit is
- * documented as an exact durability boundary:
- *
- * 1. pause every controllable stage and await its acknowledgement;
- * 2. close the root-shared `ctx.tool` admission boundary, so no root or nested
- *    run can admit another callback, and await open registration sections;
- * 3. rescan every root/nested tool handle — after the close the set can only
- *    shrink, so one scan is enough and no rescan loop can spin;
- * 4. abort that set, wait a bounded interval, and publish settled/abandoned
- *    nodes as cancelled;
- * 5. only then record the durable paused transition and the resumable run.
- *
- * Step 4 is the point of no return: an aborted callback cannot be un-aborted,
- * and the executor that observed the abort suspends without writing any
- * terminal record. So once it has run, step 5 publishes the local paused record
- * whatever the durable transition does — a durable failure that skipped it left
- * a run reported as running with nothing running it, and no live handle for a
- * retry to rediscover. Only `resumable` follows the durable outcome.
- *
- * A callback that ignores its signal is abandoned rather than pinning quit; its
- * `{runId, nodeId}` identity is reported in `abandonedTools`.
- *
- * It deliberately does NOT abort through the cancellation registry or append a
- * terminal `workflow.run.end` entry. Destructive cancellation remains an
- * internal lifecycle mechanism.
- *
- * A quit publishes its stage pauses in step 1, long before step 5 can record the
- * quit itself, so the run passes through an ordinary paused state on the way.
- * Only step 5 carries the caller's `actor`, so an observer that reports deliberate
- * control actions sees one quit rather than a pause followed by a quit — and
- * still sees nothing at all when a quit never publishes.
- */
-export async function quitRun(
-	runId: string,
-	opts?: {
-		store?: Store;
-		stageControlRegistry?: StageControlRegistry;
-		toolControlRegistry?: ToolControlRegistry;
-		jobs?: JobTracker;
-		/** Who requested this quit. Omitted for internal callers. */
-		actor?: WorkflowActor;
-	},
-): Promise<QuitRunResult> {
-	const activeStore = opts?.store ?? defaultStore;
-	const registry = opts?.stageControlRegistry ?? defaultStageControlRegistry;
-	const toolControls = opts?.toolControlRegistry ?? defaultToolControlRegistry;
-	const jobs = opts?.jobs ?? defaultJobTracker;
-	const run = activeStore.runs().find((candidate) => candidate.id === runId);
-	if (!run) return { ok: false, runId, reason: "not_found" };
-	if (run.endedAt !== undefined) return { ok: false, runId, reason: "already_ended" };
-
-	const graph = expandWorkflowGraph(readGraphStoreSnapshot(activeStore), runId);
-	const handles = controllableHandles(activeStore, registry, runId);
-	const admissionBoundaries = controllableAdmissionBoundaries(activeStore, toolControls, runId);
-	const promptStages = graph.stages.filter(
-		(stage) =>
-			stage.pendingPrompt !== undefined || stage.inputRequest !== undefined || stage.status === "awaiting_input",
-	);
-	const hasPausedState = run.status === "paused" || graph.stages.some((stage) => stage.status === "paused");
-	const hasLiveToolWork =
-		controllableToolHandles(activeStore, toolControls, runId).length > 0 ||
-		admissionBoundaries.some((boundary) => boundary.hasPendingAdmissions);
-	// Nothing controllable: leave admission open so an ordinary between-stages run
-	// keeps working exactly as before.
-	if (handles.length === 0 && !hasLiveToolWork && promptStages.length === 0 && !hasPausedState) {
-		return { ok: false, runId, reason: "no_active_stages" };
-	}
-
-	const paused: StageSnapshot[] = [];
-	const pausedRunIds = new Set<string>();
-	const pausable = handles.filter(({ handle }) => handle.status !== "paused");
-	const settled = await Promise.allSettled(pausable.map(({ handle }) => handle.pause()));
-	const pauseFailures: string[] = [];
-	settled.forEach((result, index) => {
-		const target = pausable[index]!;
-		if (result.status === "rejected") {
-			const message = result.reason instanceof Error ? result.reason.message : String(result.reason);
-			pauseFailures.push(`${target.controlRunId}/${target.handle.stageId}: ${message}`);
-			return;
-		}
-		const controlRun = activeStore.runs().find((candidate) => candidate.id === target.controlRunId);
-		if (controlRun?.endedAt !== undefined) return;
-		activeStore.recordStagePaused(target.controlRunId, target.handle.stageId);
-		const stage = activeStore
-			.runs()
-			.find((candidate) => candidate.id === target.controlRunId)
-			?.stages.find((candidate) => candidate.id === target.handle.stageId);
-		if (stage?.status === "paused") {
-			pausedRunIds.add(target.controlRunId);
-			paused.push(structuredClone(stage));
-		}
-	});
-	if (pauseFailures.length > 0) {
-		throw new Error(`Failed to pause workflow stages: ${pauseFailures.join("; ")}`);
-	}
-
-	for (const promptStage of promptStages) {
-		const target = promptStage.workflowGraphTarget;
-		activeStore.recordStagePaused(target.runId, target.stageId);
-		pausedRunIds.add(target.runId);
-	}
-	// Durability boundary. Closing admission first is what makes the following
-	// scan final: a callback admitted while the stage pauses were still being
-	// acknowledged is included, and none can start afterwards — not even while
-	// `markDurableQuit()` awaits the backend.
-	await closeToolAdmission(admissionBoundaries, runId);
-	const toolHandles = controllableToolHandles(activeStore, toolControls, runId);
-	const abandonedTools = await abortInFlightTools(activeStore, toolHandles);
-	const cancelledTools = collectCancelledToolNodes(activeStore, toolHandles);
-	// A nested run whose tool was aborted has no paused stage of its own; mark it
-	// paused too so the boundary's live state matches the root's.
-	for (const handle of toolHandles) if (handle.runId !== runId) pausedRunIds.add(handle.runId);
-	const current = activeStore.runs().find((candidate) => candidate.id === runId);
-	if (current === undefined) return { ok: false, runId, reason: "not_found" };
-	if (current.endedAt !== undefined) return { ok: false, runId, reason: "already_ended" };
-	// A quit that aborted a call is committed: each of those callbacks observed a
-	// whole-run quit, so its executor suspends without writing any terminal
-	// record, and only the publication below can report that the run stopped.
-	const suspendedByAbort = toolHandles.length > 0;
-	const publish = (resumable: boolean): void => {
-		publishLocalQuit(activeStore, runId, pausedRunIds, resumable, opts?.actor);
-		// An abandoned callback keeps its executor alive, but that executor is no
-		// longer authoritative for this run id: detach it so `/workflow resume`
-		// relaunches a fresh executor instead of adopting the stale job and
-		// reporting a running run nothing is actually running. Cooperative quits
-		// settle on their own and unregister themselves.
-		if (abandonedTools.length > 0) jobs.detach(runId, jobs.get(runId));
-	};
-	let durableTransition: DurableQuitOutcome;
-	try {
-		durableTransition = await markDurableQuit(runId, current);
-	} catch (error) {
-		if (!suspendedByAbort) throw error;
-		publish(false);
-		throw new Error(unrecordedDurableQuitMessage(error), { cause: error });
-	}
-	if (durableTransition === "refused") {
-		if (suspendedByAbort) publish(false);
-		return { ok: false, runId, reason: "already_ended" };
-	}
-	publish(true);
-	return { ok: true, runId, paused, cancelledTools, abandonedTools };
-}
-
-/**
- * Publish the local paused record for this workflow boundary.
- *
- * `resumable` follows the durable outcome rather than the local one: a pause the
- * durable backend never accepted is still real — the run stopped — but no future
- * process could resume from it, so it is not advertised as resumable. Recording
- * it keeps the run controllable, so a later `/workflow quit` re-attempts the
- * transition and upgrades the record.
- *
- * The boundary run is deliberately excluded from the descendant loop: a bare
- * `recordRunPaused(runId)` first would publish a plain paused state, and a
- * lifecycle observer would report this quit as a pause followed by a quit. The
- * single metadata-carrying call below records the same end state in one step.
- */
-function publishLocalQuit(
-	activeStore: Store,
-	runId: string,
-	pausedRunIds: ReadonlySet<string>,
-	resumable: boolean,
-	actor?: WorkflowActor,
-): void {
-	for (const pausedRunId of pausedRunIds) {
-		if (pausedRunId === runId) continue;
-		activeStore.recordRunPaused(pausedRunId);
-	}
-	activeStore.recordRunPaused(runId, undefined, {
-		exitReason: "quit",
-		resumable,
-		...(actor === undefined ? {} : { actor }),
-	});
-}
-
-/**
- * Report what the failed durable write left behind, not merely that it failed.
- *
- * Every caller already names the run ("Failed to quit run …: "), so this reads
- * as the rest of that sentence.
- */
-function unrecordedDurableQuitMessage(error: unknown): string {
-	const detail = error instanceof Error ? error.message : String(error);
-	return (
-		`the in-flight ctx.tool work was cancelled but the durable paused transition failed: ${detail}.` +
-		" The run is paused locally and is not resumable until a retried quit records it durably."
-	);
-}
-
-/** Distinct admission boundaries owned by this workflow boundary's runs. */
-function controllableAdmissionBoundaries(
-	activeStore: Store,
-	toolControls: ToolControlRegistry,
-	runId: string,
-): readonly ToolAdmissionBoundary[] {
-	const boundaries = new Set<ToolAdmissionBoundary>();
-	for (const controlRunId of expandedControlRunIds(activeStore, runId)) {
-		const boundary = toolControls.admissionBoundary(controlRunId);
-		if (boundary !== undefined) boundaries.add(boundary);
-	}
-	return [...boundaries];
-}
-
-/**
- * Refuse further `ctx.tool` admissions and wait for calls already inside their
- * short registration section. A call refused after this point receives the
- * graceful-quit signal, so it suspends the executor instead of failing the run.
- */
-async function closeToolAdmission(boundaries: readonly ToolAdmissionBoundary[], runId: string): Promise<void> {
-	if (boundaries.length === 0) return;
-	const reason = new WorkflowGracefulQuitError(runId, `run ${runId}`);
-	await Promise.all(boundaries.map((boundary) => boundary.closeForQuit(reason)));
-}
-
-/** In-flight tool nodes below this workflow boundary, including nested runs. */
-function controllableToolHandles(
-	activeStore: Store,
-	toolControls: ToolControlRegistry,
-	runId: string,
-): readonly ToolControlHandle[] {
-	return expandedControlRunIds(activeStore, runId).flatMap((controlRunId) => [...toolControls.active(controlRunId)]);
-}
-
-/**
- * Abort every selected tool node, wait a bounded interval for settlement, and
- * publish anything still unsettled as cancelled. Returns the abandoned
- * identities, keyed by owning run so nested duplicates stay distinguishable.
- */
-async function abortInFlightTools(
-	activeStore: Store,
-	toolHandles: readonly ToolControlHandle[],
-): Promise<readonly WorkflowToolNodeIdentity[]> {
-	if (toolHandles.length === 0) return [];
-	for (const handle of toolHandles) handle.abort("quit");
-	const abandoned = await settleAbortedToolNodes(toolHandles, TOOL_QUIT_SETTLEMENT_TIMEOUT_MS);
-	const endedAt = Date.now();
-	for (const handle of toolHandles) {
-		if (!abandoned.some((identity) => sameToolNodeIdentity(identity, handle))) continue;
-		activeStore.recordToolNodeEnd(handle.runId, handle.nodeId, {
-			status: "cancelled",
-			endedAt,
-			error: `atomic-workflows: ctx.tool ${handle.name} abandoned after quit; the callback ignored its abort signal`,
-		});
-	}
-	return abandoned;
-}
-
-function collectCancelledToolNodes(
-	activeStore: Store,
-	toolHandles: readonly ToolControlHandle[],
-): readonly WorkflowCancelledToolNode[] {
-	return toolHandles.flatMap((handle) => {
-		const node = activeStore
-			.runs()
-			.find((candidate) => candidate.id === handle.runId)
-			?.toolNodes?.find((candidate) => candidate.id === handle.nodeId);
-		if (node === undefined || node.status !== "cancelled") return [];
-		return [{ runId: handle.runId, nodeId: handle.nodeId, node: structuredClone(node) }];
-	});
-}
-
-function controllableHandles(
-	activeStore: Store,
-	registry: StageControlRegistry,
-	runId: string,
-): Array<{ controlRunId: string; handle: StageControlHandle }> {
-	const graph = expandWorkflowGraph(readGraphStoreSnapshot(activeStore), runId);
-	const controlRunIds = new Set<string>([runId]);
-	for (const stage of graph.stages) controlRunIds.add(stage.workflowGraphTarget.runId);
-	return [...controlRunIds].flatMap((controlRunId) =>
-		registry
-			.run(controlRunId)
-			.stages()
-			.filter(
-				(handle) =>
-					handle.status === "running" ||
-					handle.status === "pending" ||
-					handle.status === "awaiting_input" ||
-					handle.status === "paused",
-			)
-			.map((handle) => ({ controlRunId, handle })),
-	);
-}
-
-type DurableQuitOutcome = "transitioned" | "not_needed" | "refused";
-
-async function markDurableQuit(runId: string, run: RunSnapshot): Promise<DurableQuitOutcome> {
-	const backend = discoverDurableQuitBackend(runId);
-	if (backend === undefined) return "not_needed";
-	// The workflow is durably tracked, so a failure to persist the paused
-	// transition or flush it must surface: swallowing it here would let quitRun
-	// advertise a resumable pause no future process could resume from. The caller
-	// still reconciles an already-suspended executor into a pause that is not
-	// advertised as resumable, so the failure costs the promise, not the record.
-	const transitioned = await transitionDurableWorkflowStatus(
-		backend,
-		runId,
-		["running", "paused"],
-		"paused",
-		undefined,
-		true,
-	);
-	if (!transitioned) return "refused";
-	// Persist the exact accumulated run elapsed at quit time so a later durable
-	// resume seeds the total workflow duration with prior-session time.
-	recordRunTimingCheckpoint(backend, run);
-	await backend.flush();
-	return "transitioned";
-}
-
-/**
- * Resolve the durable backend only when `runId` is durably tracked. Discovery
- * stays best-effort for custom backends that throw on unsupported inspection;
- * the persistence writes performed after a positive match are intentionally
- * left to propagate so genuine durable failures are not masked.
- */
-function discoverDurableQuitBackend(runId: string): DurableWorkflowBackend | undefined {
-	try {
-		const backend = getDurableBackend();
-		return getLoadableDurableWorkflow(backend, runId) === undefined ? undefined : backend;
-	} catch {
-		return undefined;
-	}
-}
-
-export async function quitAllRuns(opts?: {
-	store?: Store;
-	stageControlRegistry?: StageControlRegistry;
-	toolControlRegistry?: ToolControlRegistry;
-	jobs?: JobTracker;
-	/** Who requested these quits. Omitted for internal callers. */
-	actor?: WorkflowActor;
-}): Promise<QuitAllRunResult[]> {
-	const activeStore = opts?.store ?? defaultStore;
-	const inFlight = topLevelWorkflowRuns(activeStore.runs()).filter((run) => run.endedAt === undefined);
-	const attempts = inFlight.map((run) =>
-		quitRun(run.id, {
-			store: activeStore,
-			stageControlRegistry: opts?.stageControlRegistry,
-			toolControlRegistry: opts?.toolControlRegistry,
-			jobs: opts?.jobs,
-			...(opts?.actor === undefined ? {} : { actor: opts.actor }),
-		}),
-	);
-	const settled = await Promise.allSettled(attempts);
-	return settled.map((result, index) => {
-		if (result.status === "fulfilled") return result.value;
-		const runId = inFlight[index]!.id;
-		return {
-			ok: false,
-			runId,
-			reason: "pause_failed",
-			message: result.reason instanceof Error ? result.reason.message : String(result.reason),
-		};
-	});
-}

package/dist/builtin/workflows/src/runs/background/resume-acknowledgements.ts

@@ -1,99 +0,0 @@
-import type { Store } from "../../shared/store-public-types.js";
-import type { StageSnapshot } from "../../shared/store-types.js";
-import type { StageControlHandle } from "../foreground/stage-control-registry.js";
-
-export interface ResumeAcknowledgementTarget {
-	readonly controlRunId: string;
-	readonly handle: StageControlHandle;
-}
-
-export interface ResumeAcknowledgementResult {
-	readonly resumed: readonly StageSnapshot[];
-	readonly acknowledged: number;
-	/** Rejections whose targets are still visibly paused and therefore retryable. */
-	readonly failures: readonly string[];
-	/** Rejections reported after the target had already become visibly running. */
-	readonly lateFailures: readonly string[];
-}
-
-function targetStage(store: Store, target: ResumeAcknowledgementTarget): StageSnapshot | undefined {
-	return store
-		.runs()
-		.find((run) => run.id === target.controlRunId)
-		?.stages.find((stage) => stage.id === target.handle.stageId);
-}
-
-function targetIsActuallyPaused(store: Store, target: ResumeAcknowledgementTarget): boolean {
-	const run = store.runs().find((candidate) => candidate.id === target.controlRunId);
-	const stage = targetStage(store, target);
-	if (run?.endedAt !== undefined || stage?.endedAt !== undefined) return false;
-	return (
-		stage?.status === "paused" ||
-		stage?.status === "blocked" ||
-		(run?.status === "paused" && target.handle.status === "paused")
-	);
-}
-
-/** Attempt every actually-paused control, then reconcile outcomes from visible state in target order. */
-export async function settleResumeAcknowledgements(
-	store: Store,
-	targets: readonly ResumeAcknowledgementTarget[],
-	message?: string,
-): Promise<ResumeAcknowledgementResult> {
-	const attempted = targets.filter(
-		(target) => target.handle.status === "paused" && targetIsActuallyPaused(store, target),
-	);
-	const settled = await Promise.allSettled(attempted.map(({ handle }) => handle.resume(message)));
-	const resumed: StageSnapshot[] = [];
-	let acknowledged = 0;
-	const failures: string[] = [];
-	const lateFailures: string[] = [];
-	const resumedRunIds = new Set<string>();
-	settled.forEach((result, index) => {
-		const target = attempted[index]!;
-		const controlRun = store.runs().find((candidate) => candidate.id === target.controlRunId);
-		const controlVisiblyRunning =
-			target.handle.status === "running" ||
-			target.handle.status === "pending" ||
-			target.handle.status === "awaiting_input";
-		if (result.status === "fulfilled" || controlVisiblyRunning) acknowledged += 1;
-		if ((result.status === "fulfilled" || controlVisiblyRunning) && controlRun?.endedAt === undefined) {
-			const stage = targetStage(store, target);
-			if (stage?.status === "paused" || stage?.status === "blocked") {
-				store.recordStageResumed(target.controlRunId, target.handle.stageId);
-			}
-		}
-		const stage = targetStage(store, target);
-		const visiblyRunning = controlRun?.endedAt === undefined && stage?.status === "running";
-		if (visiblyRunning && stage !== undefined) {
-			resumedRunIds.add(target.controlRunId);
-			resumed.push(structuredClone(stage));
-		}
-		if (result.status !== "rejected") return;
-		const detail = result.reason instanceof Error ? result.reason.message : String(result.reason);
-		const qualified = `${target.controlRunId}/${target.handle.stageId}: ${detail}`;
-		if (visiblyRunning) lateFailures.push(qualified);
-		else if (controlRun?.endedAt === undefined && targetIsActuallyPaused(store, target)) failures.push(qualified);
-	});
-	for (const controlRunId of resumedRunIds)
-		store.recordRunResumed(controlRunId, undefined, { source: "acknowledgement" });
-	return { resumed, acknowledged, failures, lateFailures };
-}
-
-/** Let immediate prompt/root finalizers settle before public resume reconciliation. */
-export async function waitForResumeReconciliation(acknowledged: number): Promise<void> {
-	if (acknowledged > 0) await new Promise<void>((resolve) => setTimeout(resolve, 0));
-}
-
-/** Existing optional message channel for a fulfilled zero-stage or terminal acknowledgement. */
-export function resumeAcknowledgementMessage(
-	acknowledged: number,
-	resumed: number,
-	runId: string,
-	current: { readonly status: string; readonly endedAt?: number },
-): string | undefined {
-	if (acknowledged === 0 || (current.endedAt === undefined && resumed > 0)) return undefined;
-	return `Resume acknowledged; workflow ${runId} ${
-		current.endedAt !== undefined ? `reached terminal status ${current.status}` : "can continue"
-	}.`;
-}

package/dist/builtin/workflows/src/runs/background/run-inspect.ts

@@ -1,126 +0,0 @@
-/**
- * Read-only per-run inspection surface.
- *
- * Extracted from `status.ts` (which stays focused on lifecycle status,
- * cancellation, and resume helpers) so both files respect the repository
- * focused modules.
- *
- * cross-ref: spec §5.5
- */
-
-import { expandWorkflowGraph } from "../../shared/expanded-workflow-graph.js";
-import {
-	actionableReturnedStatusText,
-	effectiveRunStatus,
-	structuredRecoverableWorkflowFailureText,
-} from "../../shared/returned-run-status.js";
-import type { Store } from "../../shared/store.js";
-import { store as defaultStore } from "../../shared/store.js";
-import type { RunSnapshot, RunStatus } from "../../shared/store-types.js";
-import type { WorkflowInputValues, WorkflowOutputValues } from "../../shared/types.js";
-
-/**
- * Per-run detail returned by {@link inspectRun}. A read-only view over the
- * store snapshot suitable for the "  RUN" detail surface — same data the
- * resume snapshot carries, plus a normalised `mode` field derived from
- * stage shape so renderers don't have to recompute it.
- */
-export interface RunDetail {
-	readonly runId: string;
-	readonly name: string;
-	readonly status: RunStatus | "crashed";
-	readonly mode: "single" | "chain";
-	readonly startedAt: number;
-	readonly endedAt?: number;
-	readonly durationMs?: number;
-	readonly pausedDurationMs?: number;
-	readonly pausedAt?: number;
-	readonly resumedAt?: number;
-	/** Elapsed ms inherited from prior sessions of a resumed durable run. */
-	readonly accumulatedDurationMs?: number;
-	readonly inputs: Readonly<WorkflowInputValues>;
-	readonly stages: readonly RunSnapshot["stages"][number][];
-	/** Always populated by inspectRun; optional for legacy structural literals. */
-	readonly tools?: readonly NonNullable<RunSnapshot["toolNodes"]>[number][];
-	readonly result?: WorkflowOutputValues;
-	readonly error?: string;
-	readonly exited?: boolean;
-	readonly exitReason?: string;
-	readonly failureKind?: RunSnapshot["failureKind"];
-	readonly failureCode?: RunSnapshot["failureCode"];
-	readonly failureRecoverability?: RunSnapshot["failureRecoverability"];
-	readonly failureDisposition?: RunSnapshot["failureDisposition"];
-	readonly failedStageId?: string;
-	readonly failedToolNodeId?: string;
-	readonly resumable?: boolean;
-	readonly retryAfterMs?: number;
-	/** Actionable guidance for a snapshot hydrated from durable storage. */
-	readonly resumeGuidance?: string;
-	/** True when a fresh durable owner is active in another Atomic process. */
-	readonly ownerActiveElsewhere?: boolean;
-	readonly blockedAt?: number;
-}
-
-export type InspectRunResult =
-	| { ok: true; runId: string; detail: RunDetail }
-	| { ok: false; runId: string; reason: "not_found" };
-
-/**
- * Look up a single run by its exact id and return a normalised
- * {@link RunDetail} for the per-run text/TUI surfaces.
- *
- * Exact match only. Callers reach this with an id already resolved at the input
- * boundary, where shape is validated; a second, looser prefix match here would
- * only reintroduce the truncated targeting the resolvers now reject.
- *
- * Read-only: does not mutate the store.
- */
-export function inspectRun(runId: string, opts?: { store?: Store }): InspectRunResult {
-	const activeStore = opts?.store ?? defaultStore;
-	const candidate = activeStore.runs().find((r) => r.id === runId);
-
-	if (!candidate) {
-		return { ok: false, runId, reason: "not_found" };
-	}
-
-	// Deep copy so callers cannot mutate the store via the snapshot.
-	const copy = structuredClone(candidate);
-	const expandedGraph = expandWorkflowGraph(activeStore.snapshot(), copy.id);
-	const expandedStages = expandedGraph.stages;
-
-	const detail: RunDetail = {
-		runId: copy.id,
-		name: copy.name,
-		status: effectiveRunStatus(copy),
-		mode: expandedStages.length > 1 ? "chain" : "single",
-		startedAt: copy.startedAt,
-		endedAt: copy.endedAt,
-		durationMs: copy.durationMs,
-		pausedDurationMs: copy.pausedDurationMs,
-		pausedAt: copy.pausedAt,
-		resumedAt: copy.resumedAt,
-		accumulatedDurationMs: copy.accumulatedDurationMs,
-		inputs: copy.inputs,
-		stages: expandedStages.map((stage) => structuredClone(stage)),
-		tools: expandedGraph.tools.map((tool) => structuredClone(tool)),
-		result: copy.result,
-		error:
-			copy.error ??
-			(effectiveRunStatus(copy) === copy.status
-				? undefined
-				: (structuredRecoverableWorkflowFailureText(copy) ?? actionableReturnedStatusText(copy.result))),
-		exited: copy.exited,
-		exitReason: copy.exitReason,
-		failureKind: copy.failureKind,
-		failureCode: copy.failureCode,
-		failureRecoverability: copy.failureRecoverability,
-		failureDisposition: copy.failureDisposition,
-		failedStageId: copy.failedStageId,
-		failedToolNodeId: copy.failedToolNodeId,
-		resumable: copy.resumable,
-		retryAfterMs: copy.retryAfterMs,
-		blockedAt: copy.blockedAt,
-	};
-
-	return { ok: true, runId: copy.id, detail };
-}