@bastani/atomic 0.9.13 → 0.9.14-alpha.2

package/dist/builtin/workflows/src/durable/tool-failure-checkpoint.ts

@@ -1,4 +1,5 @@
 import type { ToolNodeSnapshot } from "../shared/store-types.js";
+import type { WorkflowSerializableValue } from "../shared/types.js";
 import type { DurableWorkflowBackend } from "./backend.js";
 import { workflowToolFailure } from "./tool-outcome.js";
 import { DURABLE_TOOL_TOPOLOGY_VERSION, type DurableStageRunTopology } from "./types.js";
@@ -16,6 +17,8 @@ export async function recordThrowingToolFailure(
 	node: ToolNodeSnapshot,
 	identity: {
 		readonly name: string;
+		readonly args?: Readonly<Record<string, WorkflowSerializableValue>>;
+		readonly source?: string;
 		readonly argsHash: string;
 		readonly ordinal: number;
 		readonly startedAt: number;
@@ -30,6 +33,8 @@ export async function recordThrowingToolFailure(
 		workflowId: input.workflowId,
 		checkpointId: `tool-failure:${identity.argsHash}:${input.nextCheckpointId()}`,
 		name: identity.name,
+		...(identity.args !== undefined ? { args: identity.args } : {}),
+		...(identity.source !== undefined ? { source: identity.source } : {}),
 		argsHash: identity.argsHash,
 		output: null,
 		throwingFailureError: message,

package/dist/builtin/workflows/src/durable/tool-primitive.ts

@@ -19,6 +19,7 @@ import { runCallback } from "@bastani/atomic";
 import { sleepOrAbort } from "../runs/shared/retry.js";
 import { flattenTruncatedString } from "../shared/flat-string.js";
 import type { ToolNodeSnapshot } from "../shared/store-types.js";
+import { boundedToolPayloadRecord, boundedToolText } from "../shared/tool-payload-bounds.js";
 import type {
 	WorkflowSerializableValue,
 	WorkflowToolContext,
@@ -109,12 +110,41 @@ export interface CreateToolPrimitiveInput {
 	readonly onNodeRunning?: (nodeId: string, startedAt: number) => void;
 	readonly onNodeEnd?: (
 		nodeId: string,
-		update: Pick<ToolNodeSnapshot, "status"> & Partial<Pick<ToolNodeSnapshot, "endedAt" | "resultSummary" | "error">>,
+		update: Pick<ToolNodeSnapshot, "status"> &
+			Partial<Pick<ToolNodeSnapshot, "endedAt" | "durationMs" | "result" | "resultSummary" | "error">>,
 	) => void;
 	readonly onNodeSettle?: (nodeId: string) => void;
 	readonly runTopology?: DurableStageRunTopology;
 }
 
+function cloneToolArgs(
+	args: Readonly<Record<string, WorkflowSerializableValue>>,
+): Readonly<Record<string, WorkflowSerializableValue>> {
+	// Bounded, hostile-input safe, and always a plain object: author args may be
+	// cyclic, may throw on property access, may be arbitrarily large, and may
+	// carry a `toJSON` that would otherwise collapse the record to a scalar in a
+	// durable checkpoint. `argsHash` still hashes the raw args, so cache identity
+	// is unaffected by this inspection copy.
+	return boundedToolPayloadRecord(args);
+}
+
+/**
+ * Capture the callback's own source for read-only inspection.
+ *
+ * `Function.prototype.toString` reads text the runtime already holds: it never
+ * invokes the callback, never touches the filesystem, and never reaches any
+ * data beyond the function passed to this call. A host that refuses the read
+ * simply yields no source row.
+ */
+function captureCallbackSource(fn: unknown): string | undefined {
+	if (typeof fn !== "function") return undefined;
+	try {
+		return boundedToolText(Function.prototype.toString.call(fn));
+	} catch {
+		return undefined;
+	}
+}
+
 /**
  * Create the `ctx.tool` primitive wired to a durable backend.
  */
@@ -155,7 +185,7 @@ export function createToolPrimitive(input: CreateToolPrimitiveInput): WorkflowTo
 			noteCancelled: () => admission?.noteCancelled?.(),
 			releaseAdmission: () => lease?.release(),
 		};
-		void executeToolInvocation(input, ordinals, name, args, fn, options, control)
+		void executeToolInvocation(input, ordinals, name, args, fn, options, control, captureCallbackSource(fn))
 			// Backstop for a throw before either explicit release point; the lease
 			// release itself is idempotent.
 			.finally(() => lease?.release())
@@ -172,6 +202,7 @@ async function executeToolInvocation<T extends WorkflowSerializableValue>(
 	fn: (toolCtx: WorkflowToolContext) => Promise<T>,
 	options: WorkflowToolOptions | undefined,
 	control: ToolInvocationAdmissionControl,
+	source: string | undefined,
 ): Promise<WorkflowToolInvocationResult<T>> {
 	input.throwIfCancelled();
 	if (
@@ -181,6 +212,9 @@ async function executeToolInvocation<T extends WorkflowSerializableValue>(
 	) {
 		throw new RangeError("atomic-workflows: ctx.tool maxAttempts must be a positive integer");
 	}
+	if (options?.timeoutMs !== undefined && (!Number.isFinite(options.timeoutMs) || options.timeoutMs <= 0)) {
+		throw new RangeError("atomic-workflows: ctx.tool timeoutMs must be a positive finite number");
+	}
 	const returnFailure = options?.failureMode === "return";
 	const identityMode = returnFailure ? { failureMode: "return" as const } : {};
 	const callKey = durableHash({ name, args, ...identityMode });
@@ -189,10 +223,13 @@ async function executeToolInvocation<T extends WorkflowSerializableValue>(
 	const argsHash = durableHash({ name, args, ordinal, ...identityMode });
 
 	const cached = input.backend.getToolCheckpoint(input.workflowId, argsHash);
+	const capturedSource = cached?.source ?? source;
 	const node: ToolNodeSnapshot = {
 		kind: "tool",
 		id: cached?.topology?.nodeId ?? `tool:${argsHash}`,
 		name,
+		args: cloneToolArgs(cached?.args ?? args),
+		...(capturedSource !== undefined ? { source: capturedSource } : {}),
 		argsHash,
 		ordinal: cached?.topology?.ordinal ?? ordinal,
 		parentIds: Object.freeze(cached?.topology?.parentIds ?? []),
@@ -223,6 +260,8 @@ async function executeToolInvocation<T extends WorkflowSerializableValue>(
 			input.onNodeEnd?.(node.id, {
 				status: failed ? "failed" : "cached",
 				endedAt,
+				...(node.startedAt !== undefined ? { durationMs: Math.max(0, endedAt - node.startedAt) } : {}),
+				result: output,
 				...(failed && returnedOutcome?.ok === false
 					? { error: returnedOutcome.error.message }
 					: { resultSummary: summarizeToolResult(output) }),
@@ -233,9 +272,11 @@ async function executeToolInvocation<T extends WorkflowSerializableValue>(
 			const cancelled = input.signal?.aborted === true;
 			if (cancelled) control.noteCancelled();
 			else input.onFailureObserved?.(error, node.id);
+			const endedAt = Date.now();
 			input.onNodeEnd?.(node.id, {
 				status: cancelled ? "cancelled" : "failed",
-				endedAt: Date.now(),
+				endedAt,
+				...(node.startedAt !== undefined ? { durationMs: Math.max(0, endedAt - node.startedAt) } : {}),
 				error: error instanceof Error ? error.message : String(error),
 			});
 			input.onNodeSettle?.(node.id);
@@ -246,6 +287,8 @@ async function executeToolInvocation<T extends WorkflowSerializableValue>(
 		input,
 		node,
 		name,
+		args: node.args ?? args,
+		...(capturedSource !== undefined ? { source: capturedSource } : {}),
 		argsHash,
 		ordinal,
 		fn,
@@ -259,6 +302,8 @@ interface LiveToolInvocation<T extends WorkflowSerializableValue> {
 	readonly input: CreateToolPrimitiveInput;
 	readonly node: ToolNodeSnapshot;
 	readonly name: string;
+	readonly args: Readonly<Record<string, WorkflowSerializableValue>>;
+	readonly source?: string;
 	readonly argsHash: string;
 	readonly ordinal: number;
 	readonly fn: (toolCtx: WorkflowToolContext) => Promise<T>;
@@ -266,6 +311,86 @@ interface LiveToolInvocation<T extends WorkflowSerializableValue> {
 	readonly control: ToolInvocationAdmissionControl;
 	readonly returnFailure: boolean;
 }
+class WorkflowToolTimeoutError extends Error {
+	constructor(toolName: string, timeoutMs: number) {
+		super(`atomic-workflows: ctx.tool ${toolName} timed out after ${timeoutMs}ms`);
+		this.name = "TimeoutError";
+	}
+}
+
+const MAX_HOST_TIMER_MS = 2_147_483_647;
+
+/** Schedule a finite deadline without triggering host timer overflow clamping. */
+function scheduleDeadline(callback: () => void, timeoutMs: number): () => void {
+	let remainingMs = timeoutMs;
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	const scheduleNextChunk = () => {
+		const chunkMs = Math.min(remainingMs, MAX_HOST_TIMER_MS);
+		timer = setTimeout(() => {
+			remainingMs -= chunkMs;
+			if (remainingMs > 0) scheduleNextChunk();
+			else callback();
+		}, chunkMs);
+	};
+	scheduleNextChunk();
+	return () => {
+		if (timer !== undefined) clearTimeout(timer);
+	};
+}
+
+type ToolCallbackAttemptResult<T> =
+	| { readonly kind: "value"; readonly value: T }
+	| { readonly kind: "error"; readonly error: unknown };
+
+function abortReason(signal: AbortSignal): Error {
+	return signal.reason instanceof Error ? signal.reason : new Error("atomic-workflows: workflow cancelled");
+}
+
+/** Run one callback attempt with a fresh signal and deadline. */
+async function executeTimedToolAttempt<T extends WorkflowSerializableValue>(
+	toolName: string,
+	runId: string,
+	fn: (toolCtx: WorkflowToolContext) => Promise<T>,
+	baseSignal: AbortSignal,
+	timeoutMs: number,
+): Promise<T> {
+	const timeoutController = new AbortController();
+	const attemptSignal = AbortSignal.any([baseSignal, timeoutController.signal]);
+	return runCallback({ kind: "workflow.ctx_tool", name: toolName, runId }, async () => {
+		const callbackResult: Promise<ToolCallbackAttemptResult<T>> = Promise.resolve()
+			.then(() => fn({ signal: attemptSignal }))
+			.then(
+				(value) => ({ kind: "value" as const, value }),
+				(error: unknown) => ({ kind: "error" as const, error }),
+			);
+		let cancelDeadline: (() => void) | undefined;
+		let onAbort: (() => void) | undefined;
+		let timeoutError: WorkflowToolTimeoutError | undefined;
+		const timeoutResult = new Promise<never>((_, reject) => {
+			cancelDeadline = scheduleDeadline(() => {
+				if (baseSignal.aborted) return;
+				timeoutError = new WorkflowToolTimeoutError(toolName, timeoutMs);
+				timeoutController.abort(timeoutError);
+				reject(timeoutError);
+			}, timeoutMs);
+		});
+		const cancellationResult = new Promise<never>((_, reject) => {
+			onAbort = () => {
+				if (timeoutError === undefined) reject(abortReason(baseSignal));
+			};
+			if (baseSignal.aborted) onAbort();
+			else baseSignal.addEventListener("abort", onAbort, { once: true });
+		});
+		try {
+			const result = await Promise.race([callbackResult, timeoutResult, cancellationResult]);
+			if (result.kind === "value") return result.value;
+			throw result.error;
+		} finally {
+			cancelDeadline?.();
+			if (onAbort !== undefined) baseSignal.removeEventListener("abort", onAbort);
+		}
+	});
+}
 
 /**
  * Execute one uncached tool call under its own abort controller.
@@ -278,7 +403,7 @@ interface LiveToolInvocation<T extends WorkflowSerializableValue> {
 async function executeLiveToolInvocation<T extends WorkflowSerializableValue>(
 	live: LiveToolInvocation<T>,
 ): Promise<WorkflowToolInvocationResult<T>> {
-	const { input, node, name, argsHash, ordinal, fn, options, control, returnFailure } = live;
+	const { input, node, name, args, source, argsHash, ordinal, fn, options, control, returnFailure } = live;
 	const nodeController = new AbortController();
 	const toolSignal =
 		input.signal === undefined ? nodeController.signal : AbortSignal.any([input.signal, nodeController.signal]);
@@ -302,9 +427,13 @@ async function executeLiveToolInvocation<T extends WorkflowSerializableValue>(
 		const result = await executeWithRetries(
 			() => {
 				attempts += 1;
-				return runCallback({ kind: "workflow.ctx_tool", name, runId: input.workflowId }, () =>
-					fn({ signal: toolSignal }),
-				).catch((error: unknown) => {
+				const callback =
+					options?.timeoutMs === undefined
+						? runCallback({ kind: "workflow.ctx_tool", name, runId: input.workflowId }, () =>
+								fn({ signal: toolSignal }),
+							)
+						: executeTimedToolAttempt(name, input.workflowId, fn, toolSignal, options.timeoutMs);
+				return callback.catch((error: unknown) => {
 					callbackError = error;
 					throw error;
 				});
@@ -328,6 +457,8 @@ async function executeLiveToolInvocation<T extends WorkflowSerializableValue>(
 			workflowId: input.workflowId,
 			checkpointId: `tool:${argsHash}`,
 			name,
+			args: cloneToolArgs(args),
+			...(source !== undefined ? { source } : {}),
 			argsHash,
 			output,
 			...(returnFailure ? { outcomeKind: "return_success" as const } : {}),
@@ -347,12 +478,15 @@ async function executeLiveToolInvocation<T extends WorkflowSerializableValue>(
 		input.onNodeEnd?.(node.id, {
 			status: "completed",
 			endedAt: completedAt,
+			durationMs: Math.max(0, completedAt - startedAt),
+			result: output,
 			resultSummary: summarizeToolResult(output),
 		});
 		input.onNodeSettle?.(node.id);
 		return output;
 	} catch (error) {
-		const cancellation = invocationCancellation(input, toolSignal);
+		const timeoutFailure = error instanceof WorkflowToolTimeoutError;
+		const cancellation = timeoutFailure ? undefined : invocationCancellation(input, toolSignal);
 		if (cancellation !== undefined) {
 			control.noteCancelled();
 			// A cancelled call never writes a replayable `tool:` checkpoint and never
@@ -366,9 +500,11 @@ async function executeLiveToolInvocation<T extends WorkflowSerializableValue>(
 			if (returnFailure) {
 				await recordCancelledToolInspection(live, startedAt, cancellation, attempts);
 			}
+			const endedAt = Date.now();
 			input.onNodeEnd?.(node.id, {
 				status: "cancelled",
-				endedAt: Date.now(),
+				endedAt,
+				durationMs: Math.max(0, endedAt - startedAt),
 				error: cancellation.message,
 			});
 			input.onNodeSettle?.(node.id);
@@ -380,11 +516,16 @@ async function executeLiveToolInvocation<T extends WorkflowSerializableValue>(
 			const failure = await recordThrowingToolFailure(
 				input,
 				node,
-				{ name, argsHash, ordinal, startedAt },
+				{ name, args, ...(source !== undefined ? { source } : {}), argsHash, ordinal, startedAt },
 				callbackFailure,
 				attempts,
 			);
-			input.onNodeEnd?.(node.id, { status: "failed", endedAt: failure.failedAt, error: failure.message });
+			input.onNodeEnd?.(node.id, {
+				status: "failed",
+				endedAt: failure.failedAt,
+				durationMs: Math.max(0, failure.failedAt - startedAt),
+				error: failure.message,
+			});
 			input.onNodeSettle?.(node.id);
 			throw callbackFailure;
 		}
@@ -396,6 +537,8 @@ async function executeLiveToolInvocation<T extends WorkflowSerializableValue>(
 				workflowId: input.workflowId,
 				checkpointId: `tool:${argsHash}`,
 				name,
+				args: cloneToolArgs(args),
+				...(source !== undefined ? { source } : {}),
 				argsHash,
 				output: outcome,
 				outcomeKind: "return_failure",
@@ -415,30 +558,44 @@ async function executeLiveToolInvocation<T extends WorkflowSerializableValue>(
 				await recordCheckpointDurably(input.backend, checkpoint);
 			} catch (persistenceError) {
 				input.onFailureObserved?.(persistenceError, node.id);
+				const endedAt = Date.now();
 				input.onNodeEnd?.(node.id, {
 					status: "failed",
-					endedAt: Date.now(),
+					endedAt,
+					durationMs: Math.max(0, endedAt - startedAt),
 					error: persistenceError instanceof Error ? persistenceError.message : String(persistenceError),
 				});
 				input.onNodeSettle?.(node.id);
 				throw persistenceError;
 			}
-			input.onNodeEnd?.(node.id, { status: "failed", endedAt: completedAt, error: outcome.error.message });
+			input.onNodeEnd?.(node.id, {
+				status: "failed",
+				endedAt: completedAt,
+				durationMs: Math.max(0, completedAt - startedAt),
+				result: outcome,
+				error: outcome.error.message,
+			});
 			input.onNodeSettle?.(node.id);
-			throwIfInvocationCancelled(input, toolSignal);
+			if (!timeoutFailure) throwIfInvocationCancelled(input, toolSignal);
 			return outcome;
 		}
-		input.onFailureObserved?.(error, node.id);
+		const reportedFailure = timeoutFailure ? callbackError : error;
+		input.onFailureObserved?.(reportedFailure, node.id);
 		const failure = await recordThrowingToolFailure(
 			input,
 			node,
-			{ name, argsHash, ordinal, startedAt },
-			error,
+			{ name, args, ...(source !== undefined ? { source } : {}), argsHash, ordinal, startedAt },
+			reportedFailure,
 			attempts,
 		);
-		input.onNodeEnd?.(node.id, { status: "failed", endedAt: failure.failedAt, error: failure.message });
+		input.onNodeEnd?.(node.id, {
+			status: "failed",
+			endedAt: failure.failedAt,
+			durationMs: Math.max(0, failure.failedAt - startedAt),
+			error: failure.message,
+		});
 		input.onNodeSettle?.(node.id);
-		throw error;
+		throw reportedFailure;
 	} finally {
 		settlement.resolve();
 		unregisterControl?.();
@@ -464,7 +621,14 @@ async function recordCancelledToolInspection<T extends WorkflowSerializableValue
 		await recordThrowingToolFailure(
 			live.input,
 			live.node,
-			{ name: live.name, argsHash: live.argsHash, ordinal: live.ordinal, startedAt },
+			{
+				name: live.name,
+				args: live.args,
+				...(live.source !== undefined ? { source: live.source } : {}),
+				argsHash: live.argsHash,
+				ordinal: live.ordinal,
+				startedAt,
+			},
 			cancellation,
 			attempts,
 		);
@@ -606,6 +770,8 @@ async function recordReplayedToolTopology(
 		workflowId: input.workflowId,
 		checkpointId: `tool-replay-meta:${durableHash({ argsHash, topology })}`,
 		name: node.name,
+		...(cached.args !== undefined ? { args: cached.args } : {}),
+		...(cached.source !== undefined ? { source: cached.source } : {}),
 		argsHash,
 		output: cached.output,
 		...(cached.outcomeKind !== undefined ? { outcomeKind: cached.outcomeKind } : {}),

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

@@ -112,6 +112,10 @@ export interface DurableToolCheckpoint {
 	readonly checkpointId: string;
 	/** Tool name for display/debugging. */
 	readonly name: string;
+	/** Exact invocation arguments retained for read-only inspection. */
+	readonly args?: Readonly<Record<string, WorkflowSerializableValue>>;
+	/** Callback source captured at registration for read-only inspection. */
+	readonly source?: string;
 	/** Deterministic hash of the tool arguments for idempotency. */
 	readonly argsHash: string;
 	/** Cached tool output (JSON-serializable). */

package/dist/builtin/workflows/src/durable/workflow-heartbeat-anchor.ts

@@ -0,0 +1,153 @@
+/**
+ * Durable workflow-heartbeat cadence anchor.
+ *
+ * The heartbeat cadence is `anchorAt + n × interval`. Every input to that is
+ * already persisted except one: the *original* run start time. A durable resume
+ * re-dispatches under the original workflow id but mints a fresh
+ * `RunSnapshot.startedAt` (`engine/run.ts`), and that fresh value is passed to
+ * `registerWorkflow` as `createdAt`, which the backend overwrites
+ * unconditionally (`durable/backend.ts`). Checkpoints are the only per-run state
+ * that survives re-registration, so this record is the sole surviving carrier of
+ * the original start — which is what keeps a resumed run on its original
+ * cadence rather than starting a fresh series.
+ *
+ * Storage shape: a reserved tool-kind checkpoint (name/argsHash
+ * `workflow-heartbeat-anchor`), following `run-timing.ts`. Its `checkpointId` is
+ * that same constant with no suffix, so `recordCheckpoint`'s duplicate-key early
+ * return makes the record **write-once and exactly one row per run** rather than
+ * one row per boundary.
+ *
+ * Three properties this shape is chosen for:
+ *
+ * - **It cannot manufacture resumability.** `recordCheckpoint` sets
+ *   `completedCheckpoints = checkpoints.size`, and `isDurableWorkflowResumable`
+ *   gates a running or paused run on `completedCheckpoints > 0`. Writing for a
+ *   run with no durable progress of its own would make it look resumable, so the
+ *   write is skipped until the run has at least one other checkpoint — the same
+ *   guard, and the same reason, as `run-timing.ts`.
+ * - **It cannot walk liveness backwards.** `recordCheckpoint` copies
+ *   `completedAt` onto the handle as `updatedAt`, which the foreign-liveness
+ *   window reads, so `completedAt` is the write time and never a cadence
+ *   boundary.
+ * - **It cannot move a boundary forward.** It is read as
+ *   `min(run.startedAt, anchorAt)`, so it can only restore the original anchor,
+ *   never advance it. Recovery still floors at `now`, so no missed boundary is
+ *   ever replayed.
+ *
+ * The record has no per-checkpoint deletion — `DurableWorkflowBackend` removes
+ * whole workflows only — so terminal cleanup (issue #1975) invalidates it on the
+ * read side instead: the scheduler neither reads nor writes an anchor for a run
+ * it observes as terminal, and drops the in-memory memo of it. A leftover row is
+ * therefore inert, and cannot put a finished run back on a cadence.
+ *
+ * cross-ref: packages/workflows/src/extension/workflow-heartbeat-scheduler.ts
+ */
+
+import type { DurableWorkflowBackend } from "./backend.js";
+import type { DurableToolCheckpoint } from "./types.js";
+
+/** Reserved checkpoint name, args-hash, AND checkpoint id for cadence anchors. */
+export const WORKFLOW_HEARTBEAT_ANCHOR_CHECKPOINT_NAME = "workflow-heartbeat-anchor";
+
+/**
+ * What a run launched with: its original start time, and the cadence its own
+ * definition declared.
+ *
+ * `intervalMinutes` is absent on records written before it was added, so a
+ * reader must treat that as "unknown" and fall back to the live definition —
+ * never as `0`.
+ */
+export interface WorkflowHeartbeatAnchorRecord {
+	readonly anchorAt: number;
+	readonly intervalMinutes?: number;
+}
+
+/**
+ * The stored checkpoint payload, before validation.
+ *
+ * `getToolOutput` returns whatever a previous process wrote, so the fields are
+ * declared optional and validated below rather than trusted. Naming the shape
+ * keeps the decode free of inline casts while leaving the trust boundary
+ * explicit.
+ */
+interface PersistedAnchorOutput {
+	readonly anchorAt?: number;
+	readonly intervalMinutes?: number;
+}
+
+function asPersistedAnchorOutput(output: unknown): PersistedAnchorOutput | undefined {
+	if (typeof output !== "object" || output === null || Array.isArray(output)) return undefined;
+	const { anchorAt, intervalMinutes } = output as Partial<Record<keyof PersistedAnchorOutput, unknown>>;
+	return {
+		...(typeof anchorAt === "number" ? { anchorAt } : {}),
+		...(typeof intervalMinutes === "number" ? { intervalMinutes } : {}),
+	};
+}
+
+/** The persisted launch anchor for a run, or undefined when absent or malformed. */
+export function readWorkflowHeartbeatAnchor(
+	backend: DurableWorkflowBackend,
+	workflowId: string,
+): WorkflowHeartbeatAnchorRecord | undefined {
+	const record = asPersistedAnchorOutput(backend.getToolOutput(workflowId, WORKFLOW_HEARTBEAT_ANCHOR_CHECKPOINT_NAME));
+	if (record === undefined) return undefined;
+	const { anchorAt, intervalMinutes } = record;
+	if (anchorAt === undefined || !Number.isFinite(anchorAt)) return undefined;
+	// Only a positive finite cadence is carried: a disabled run never writes a
+	// record at all, so a non-positive value here is corrupt rather than meaningful.
+	return intervalMinutes !== undefined && Number.isFinite(intervalMinutes) && intervalMinutes > 0
+		? { anchorAt, intervalMinutes }
+		: { anchorAt };
+}
+
+/**
+ * Persist what a run launched with, once.
+ *
+ * Uses `recordAdditiveCheckpointBestEffort` rather than the synchronous
+ * `recordCheckpoint`, because the DBOS backend updates its in-memory mirror
+ * *before* the real write is queued: a synchronous read-back therefore proves
+ * only that the mirror holds the row, and would let a rejected storage write be
+ * remembered as a success that is never retried. The best-effort path awaits
+ * `recordStepOutput` and updates the mirror only after it resolves, and turns a
+ * storage rejection into `false` instead of a fatal flush error.
+ *
+ * Returns `true` only when the record is durably written *and* readable — the
+ * backend silently drops a checkpoint for a workflow it has never registered,
+ * so the read-back stays as well.
+ */
+export async function recordWorkflowHeartbeatAnchor(
+	backend: DurableWorkflowBackend,
+	record: {
+		readonly runId: string;
+		readonly anchorAt: number;
+		readonly intervalMinutes: number;
+		readonly now: number;
+	},
+): Promise<boolean> {
+	if (!Number.isFinite(record.anchorAt)) return false;
+	// A run launched with heartbeats disabled writes no record at all, so this
+	// path is never reached for a non-positive cadence. Guarding it here keeps
+	// that invariant local to the writer as well as to its caller.
+	if (!Number.isFinite(record.intervalMinutes) || record.intervalMinutes <= 0) return false;
+	const existing = readWorkflowHeartbeatAnchor(backend, record.runId);
+	// Write-once: the first record stands. A later write cannot move the anchor
+	// forward, and it cannot retro-fit an edited cadence onto a run in flight.
+	if (existing !== undefined) return true;
+	// A record for a run with no durable progress of its own would make that run
+	// look resumable; the anchor is worth nothing on a run that cannot resume.
+	if (backend.listCheckpoints(record.runId).length === 0) return false;
+	const checkpoint: DurableToolCheckpoint = {
+		kind: "tool",
+		workflowId: record.runId,
+		checkpointId: WORKFLOW_HEARTBEAT_ANCHOR_CHECKPOINT_NAME,
+		name: WORKFLOW_HEARTBEAT_ANCHOR_CHECKPOINT_NAME,
+		argsHash: WORKFLOW_HEARTBEAT_ANCHOR_CHECKPOINT_NAME,
+		output: { anchorAt: record.anchorAt, intervalMinutes: record.intervalMinutes },
+		// Write time, never the boundary: this lands on the handle as `updatedAt`,
+		// which the foreign-liveness window reads.
+		completedAt: record.now,
+	};
+	const stored = await backend.recordAdditiveCheckpointBestEffort(checkpoint);
+	if (!stored) return false;
+	return readWorkflowHeartbeatAnchor(backend, record.runId) !== undefined;
+}

package/dist/builtin/workflows/src/engine/run-durable-stage-session.ts

@@ -1,5 +1,6 @@
 import { recordRunTimingCheckpointAsync } from "../durable/run-timing.js";
 import { type DurableStageDeps, recordStageSessionCheckpoint } from "../durable/stage-primitive.js";
+import { recordWorkflowHeartbeatAnchor } from "../durable/workflow-heartbeat-anchor.js";
 import type { StageSessionCheckpointOptions } from "../runs/foreground/executor-types.js";
 import type { RunSnapshot, StageSnapshot } from "../shared/store-types.js";
 
@@ -18,6 +19,8 @@ export interface DurableStageSessionRecorderInput {
 	 * only tracked for the root workflow.
 	 */
 	readonly runSnapshot?: RunSnapshot;
+	/** Cadence declared by the live definition that minted `runSnapshot`. */
+	readonly heartbeatIntervalMinutes: number;
 }
 
 export function createDurableStageSessionRecorder(
@@ -30,6 +33,31 @@ export function createDurableStageSessionRecorder(
 				await recordRunTimingCheckpointAsync(input.deps.backend, input.runSnapshot, {
 					debounce: options?.forceDurable !== true,
 				});
+				// Any checkpoint above can be the first one that makes the run
+				// resumable, and the scheduler's own launch-record write is
+				// asynchronous and best-effort: it is guarded against runs with no
+				// durable progress, so it can only be issued *after* resumability
+				// already exists. A process that exits inside that window leaves a
+				// resumable run with no record of what it launched with, and the next
+				// process then reads a freshly minted `startedAt` and whatever cadence
+				// the definition currently declares — shifting both phase and cadence
+				// under a run already in flight.
+				//
+				// Awaiting the write here closes that window: the record is durable
+				// before this checkpoint is acknowledged to its caller. It is
+				// write-once and returns early once present, so later passes cost one
+				// mirror read. A forced pause/quit capture additionally has no further
+				// active schedule pass to retry in, which is why this must not be
+				// limited to the ordinary path either.
+				const intervalMinutes = input.heartbeatIntervalMinutes;
+				if (Number.isFinite(intervalMinutes * 60_000)) {
+					await recordWorkflowHeartbeatAnchor(input.deps.backend, {
+						runId: input.runId,
+						anchorAt: input.runSnapshot.startedAt,
+						intervalMinutes,
+						now: input.deps.now?.() ?? Date.now(),
+					});
+				}
 			}
 		}
 		await input.onStageSession?.(stageRunId, snapshot, options);

package/dist/builtin/workflows/src/engine/run-tool-control-registry.ts

@@ -13,6 +13,7 @@
  * cross-ref: issue #2078; src/runs/foreground/stage-control-registry.ts
  */
 
+import { createSessionScopedSingleton } from "../shared/session-scoped-singleton.js";
 import type { WorkflowToolNodeIdentity } from "../shared/types.js";
 import type { ToolAdmissionBoundary } from "./run-tool-admission-boundary.js";
 import { WorkflowToolAbortError, type WorkflowToolAbortScope } from "./workflow-tool-abort.js";
@@ -130,7 +131,14 @@ export function createToolControlRegistry(): ToolControlRegistry {
  * through `RunOpts.toolControlRegistry`; the singleton is the default consumer
  * surface used by the extension factory.
  */
-export const toolControlRegistry: ToolControlRegistry = createToolControlRegistry();
+const SESSION_KEY = "workflows:tool-control:v1";
+const singleton = createSessionScopedSingleton(SESSION_KEY, createToolControlRegistry);
+
+export const toolControlRegistry: ToolControlRegistry = singleton.facade;
+
+export function adoptToolControlRegistry(scope: object): ToolControlRegistry {
+	return singleton.adopt(scope);
+}
 
 /**
  * Await settlement of aborted tool handles up to `timeoutMs` and report the

package/dist/builtin/workflows/src/engine/run.ts

@@ -296,6 +296,7 @@ export async function run<TInputs extends WorkflowInputValues, TRunInputs extend
 		deps: durableStageDeps,
 		onStageSession: opts.onStageSession,
 		...(opts.parentRun === undefined ? { runSnapshot } : {}),
+		heartbeatIntervalMinutes: def.heartbeatIntervalMinutes,
 	});
 	const stageOptions: EngineStageRuntimeOptions = {
 		continuation: opts.continuation,

package/dist/builtin/workflows/src/extension/adopt-session-run-state.ts

@@ -0,0 +1,20 @@
+import { adoptToolControlRegistry } from "../engine/run-tool-control-registry.js";
+import { adoptCancellationRegistry } from "../runs/background/cancellation-registry.js";
+import { adoptJobTracker } from "../runs/background/job-tracker.js";
+import { adoptStageControlRegistry } from "../runs/foreground/stage-control-registry.js";
+import { adoptStageUiBroker } from "../shared/stage-ui-broker.js";
+import { adoptStore } from "../shared/store-factory.js";
+
+/**
+ * Re-bind every run-scoped singleton to host session state for `scope`.
+ * No-op when the host has not supplied a scope (unit tests, embedded SDK).
+ */
+export function adoptWorkflowSessionRunState(scope: object | undefined): void {
+	if (scope === undefined) return;
+	adoptStore(scope);
+	adoptStageControlRegistry(scope);
+	adoptCancellationRegistry(scope);
+	adoptToolControlRegistry(scope);
+	adoptJobTracker(scope);
+	adoptStageUiBroker(scope);
+}