@bastani/atomic 0.9.13-alpha.4 → 0.9.14-alpha.1

package/dist/builtin/workflows/builtin/tournament.ts

@@ -6,6 +6,10 @@ import { runTournament } from "./tournament-runner.js";
 export default workflow({
   name: "tournament",
   description: "Run several independent whole-task attempts through a balanced pairwise judging bracket and return an auditable winner.",
+  // The 15-minute default, stated rather than inherited: this is a per-workflow
+  // product decision, so a future change to the global default must not silently
+  // re-cadence a long autonomous run.
+  heartbeatIntervalMinutes: 15,
   inputs: {
     prompt: Type.String({ description: "Task every competing agent must attempt independently." }),
     num_attempts: Type.Integer({

package/dist/builtin/workflows/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/workflows",
-  "version": "0.9.13-alpha.4",
+  "version": "0.9.14-alpha.1",
   "private": true,
   "description": "Atomic extension for multi-stage workflow authoring and execution.",
   "contributors": [

package/dist/builtin/workflows/src/authoring/workflow.ts

@@ -17,6 +17,7 @@ import type {
 	WorkflowOutputsFromSchemas,
 	WorkflowProvidedInputsFromSchemas,
 } from "../shared/workflow-authoring-types.js";
+import { DEFAULT_WORKFLOW_HEARTBEAT_INTERVAL_MINUTES } from "../shared/workflow-heartbeat-contract.js";
 import { normalizeWorkflowName } from "../workflows/identity.js";
 
 export type {
@@ -158,6 +159,13 @@ export function workflow<
 	) {
 		throw new TypeError("workflow: inputs must be a schema map");
 	}
+	const heartbeatIntervalMinutes =
+		spec.heartbeatIntervalMinutes === undefined
+			? DEFAULT_WORKFLOW_HEARTBEAT_INTERVAL_MINUTES
+			: spec.heartbeatIntervalMinutes;
+	if (!Number.isFinite(heartbeatIntervalMinutes) || heartbeatIntervalMinutes < 0) {
+		throw new TypeError("workflow: heartbeatIntervalMinutes must be a non-negative finite number");
+	}
 
 	const name = resolveWorkflowName(spec.name);
 	const normalizedName = normalizeWorkflowName(name);
@@ -174,6 +182,7 @@ export function workflow<
 		normalizedName,
 		description: spec.description,
 		...(spec.autoAttach === true ? { autoAttach: true } : {}),
+		heartbeatIntervalMinutes,
 		inputs: frozenInputs,
 		outputs: frozenOutputs,
 		...(inputBindings !== undefined ? { inputBindings } : {}),

package/dist/builtin/workflows/src/authoring.d.ts

@@ -4,6 +4,7 @@ export type { AgentSessionAdapter, CompleteAdapter, CompleteStageOpts, GitWorktr
 import type * as AuthoringContract from "./shared/authoring-contract.js";
 import type { AuthoredWorkflowSpec as SharedAuthoredWorkflowSpec, WorkflowInputsFromSchemas, WorkflowOutputsFromSchemas, WorkflowProvidedInputsFromSchemas } from "./shared/workflow-authoring-types.js";
 export type { WorkflowInputsFromSchemas, WorkflowOutputsFromSchemas, WorkflowProvidedInputsFromSchemas, } from "./shared/workflow-authoring-types.js";
+export type { WorkflowHeartbeatEvent, WorkflowHeartbeatEventDetails, WorkflowHeartbeatIdentity, } from "./shared/workflow-heartbeat-contract.js";
 import type { GitWorktreeSetupOptions, GitWorktreeSetupResult, ResolvedInputs, RunResult, RunStatus, StageSnapshot, WorkflowDefinition as WorkflowContractDefinition, WorkflowExecutionPolicy, WorkflowInputSchemaMap, WorkflowInputValues, WorkflowOutputSchemaMap, WorkflowOutputValues, WorkflowSerializableObject } from "./shared/authoring-contract.js";
 declare const workflowDefinitionBrand: unique symbol;
 type WorkflowDefinitionBrand = {
@@ -55,6 +56,8 @@ export declare function workflow<const TInputs extends WorkflowInputSchemaMap =
 export declare function keepContext(text: string): string;
 export declare const KEEP_CONTEXT_OPEN_TAG: string;
 export declare const KEEP_CONTEXT_CLOSE_TAG: string;
+export declare const DEFAULT_WORKFLOW_HEARTBEAT_INTERVAL_MINUTES: 15;
+export declare const WORKFLOW_HEARTBEAT_CUSTOM_TYPE: "workflows:workflow-heartbeat";
 export declare function createRegistry<TDefinitions extends readonly AnyWorkflowDefinition[] = readonly AnyWorkflowDefinition[]>(initial?: TDefinitions): WorkflowRegistry;
 export declare function normalizeWorkflowName(name: string): string;
 export declare function workflowNamesEqual(a: string, b: string): boolean;

package/dist/builtin/workflows/src/durable/completed-catalog.ts

@@ -23,6 +23,17 @@ import {
 import { isDurableWorkflowResumable } from "./resume-eligibility.js";
 import { resolveDurableEntry } from "./resume-runtime.js";
 import { priorRunElapsedMs, RUN_TIMING_CHECKPOINT_NAME } from "./run-timing.js";
+import { WORKFLOW_HEARTBEAT_ANCHOR_CHECKPOINT_NAME } from "./workflow-heartbeat-anchor.js";
+
+/**
+ * Reserved run-level tool checkpoints that carry no graph node. They round-trip
+ * through the durable envelope like any tool checkpoint, so reconstruction has
+ * to skip them or they surface as phantom cached tool nodes.
+ */
+function isReservedRunCheckpointHash(argsHash: string): boolean {
+	return argsHash === RUN_TIMING_CHECKPOINT_NAME || argsHash === WORKFLOW_HEARTBEAT_ANCHOR_CHECKPOINT_NAME;
+}
+
 import {
 	directChildTopologyError,
 	groupByDurableStageKey,
@@ -218,7 +229,7 @@ function checkpointDrafts(checkpoints: readonly DurableCheckpoint[]): Reconstruc
 			stageByReplayKey.set(checkpoint.replayKey, mergeStageDraft(existing, checkpoint, sequence));
 			return;
 		}
-		if (checkpoint.kind !== "tool" || checkpoint.argsHash === RUN_TIMING_CHECKPOINT_NAME) return;
+		if (checkpoint.kind !== "tool" || isReservedRunCheckpointHash(checkpoint.argsHash)) return;
 		if (!firstToolSequenceByHash.has(checkpoint.argsHash)) {
 			firstToolSequenceByHash.set(checkpoint.argsHash, sequence);
 		}
@@ -390,7 +401,7 @@ function runSnapshotsFromCheckpoints(
 		const supportedNonGraphState = checkpoints.every(
 			(checkpoint) =>
 				checkpoint.kind === "ui" ||
-				(checkpoint.kind === "tool" && checkpoint.argsHash === RUN_TIMING_CHECKPOINT_NAME),
+				(checkpoint.kind === "tool" && isReservedRunCheckpointHash(checkpoint.argsHash)),
 		);
 		if (policy.failClosed && supportedNonGraphState) {
 			return [emptyGraphRun(rootRunId, rootRunName, fallbackCompletedAt)];

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.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/extension-runtime-state.ts

@@ -1,3 +1,5 @@
+import { getDurableBackend } from "../durable/factory.js";
+import { readWorkflowHeartbeatAnchor, recordWorkflowHeartbeatAnchor } from "../durable/workflow-heartbeat-anchor.js";
 import { cancellationRegistry } from "../runs/background/cancellation-registry.js";
 import type { StageAdapters } from "../runs/foreground/stage-runner.js";
 import type { SessionManager } from "../shared/persistence-restore.js";
@@ -11,6 +13,7 @@ import type {
 	WorkflowPersistencePort,
 	WorkflowRuntimeConfig,
 } from "../shared/types.js";
+import type { WorkflowHeartbeatIdentity } from "../shared/workflow-heartbeat-contract.js";
 import {
 	type ConfigLoadResult,
 	loadWorkflowConfig,
@@ -35,11 +38,57 @@ import {
 import type { ExtensionAPI, PiModelContext } from "./public-types.js";
 import { createExtensionRuntime, type ExtensionRuntime } from "./runtime.js";
 import { createStatusWriter, type StatusWriter } from "./status-writer.js";
+import { registerWorkflowHeartbeatRenderer } from "./workflow-heartbeat-notice.js";
+import {
+	createWorkflowHeartbeatSchedulerState,
+	installWorkflowHeartbeatScheduler,
+	isWorkflowHeartbeatTerminalRun,
+	resetWorkflowHeartbeatSchedulerState,
+	type WorkflowHeartbeatAnchorStore,
+	type WorkflowHeartbeatScheduler,
+	workflowHeartbeatConsumedIdentity,
+	workflowHeartbeatContextInvalidation,
+} from "./workflow-heartbeat-scheduler.js";
 import { workflowModelCatalogFromContext } from "./workflow-model-catalog.js";
 import { makeMcpPort, makePersistencePort } from "./workflow-ports.js";
 import { createWorkflowReloadCoordinator } from "./workflow-reload-coordinator.js";
 import { type WorkflowReloadReport, workflowReloadDiagnostics } from "./workflow-reload-report.js";
 
+/**
+ * Best-effort durable cadence-anchor store for workflow heartbeats.
+ *
+ * `getDurableBackend()` throws `DbosNotReadyError` until a backend exists, and
+ * the scheduler installs at `session_start`, before any workflow has run — so
+ * both sides swallow failure and fall back to the run's own `startedAt`.
+ */
+function durableWorkflowHeartbeatAnchorStore(): WorkflowHeartbeatAnchorStore {
+	return {
+		readAnchorAt(runId) {
+			try {
+				return readWorkflowHeartbeatAnchor(getDurableBackend(), runId);
+			} catch {
+				return undefined;
+			}
+		},
+		async recordAnchorAt(runId, record) {
+			try {
+				return await recordWorkflowHeartbeatAnchor(getDurableBackend(), {
+					runId,
+					anchorAt: record.anchorAt,
+					// The scheduler only records a positive cadence; a run launched
+					// disabled never reaches this seam.
+					intervalMinutes: record.intervalMinutes ?? 0,
+					now: Date.now(),
+				});
+			} catch {
+				// A backend that is not ready must not break a background pass; the
+				// caller retries on the next schedule pass.
+				return false;
+			}
+		},
+	};
+}
+
 export interface WorkflowExtensionRuntimeState {
 	persistenceRef: { current: WorkflowPersistencePort | undefined };
 	mcpPort: WorkflowMcpPort | undefined;
@@ -48,6 +97,7 @@ export interface WorkflowExtensionRuntimeState {
 	discoveryRef: { current: DiscoveryResult | null };
 	lifecycleNotificationState: ReturnType<typeof createWorkflowLifecycleNotificationState>;
 	hilAnswerNotificationState: ReturnType<typeof createWorkflowHilAnswerNotificationState>;
+	workflowHeartbeatSchedulerState: ReturnType<typeof createWorkflowHeartbeatSchedulerState>;
 	/** Seed lifecycle notification state before completed historical snapshots are inserted. */
 	beforeRestoreCompleted(snapshots: readonly RunSnapshot[]): void;
 	runtimeForContext(ctx?: PiModelContext): ExtensionRuntime;
@@ -83,10 +133,12 @@ export function createWorkflowExtensionRuntimeState(
 	let statusWriterRef: StatusWriter = createStatusWriter(store, runtimeConfigRef.current);
 	let lifecycleNotificationsUnsubscribe: (() => void) | null = null;
 	let hilAnswerNotificationsUnsubscribe: (() => void) | null = null;
+	let workflowHeartbeatScheduler: WorkflowHeartbeatScheduler | null = null;
 	let notificationsActive = false;
 	let notificationGeneration = 0;
 	const lifecycleNotificationState = createWorkflowLifecycleNotificationState();
 	const hilAnswerNotificationState = createWorkflowHilAnswerNotificationState();
+	const workflowHeartbeatSchedulerState = createWorkflowHeartbeatSchedulerState();
 	const beforeRestoreCompleted = (snapshots: readonly RunSnapshot[]): void => {
 		seedWorkflowLifecycleNotificationState(lifecycleNotificationState, {
 			...readGraphStoreSnapshot(store),
@@ -102,6 +154,7 @@ export function createWorkflowExtensionRuntimeState(
 			: undefined;
 	registerLifecycleNoticeRenderer({ rendererHost: pi, registerMessageRenderer });
 	registerHilAnswerNoticeRenderer({ rendererHost: pi, registerMessageRenderer });
+	registerWorkflowHeartbeatRenderer({ rendererHost: pi, registerMessageRenderer });
 	const sendWorkflowNotificationMessage: ExtensionAPI["sendMessage"] | undefined =
 		typeof pi.sendMessage === "function" ? (message, options) => pi.sendMessage!(message, options) : undefined;
 	const reinstallLifecycleNotifications = (): void => {
@@ -127,6 +180,86 @@ export function createWorkflowExtensionRuntimeState(
 			sendMessage: sendWorkflowNotificationMessage,
 		});
 	};
+	// `message_end` is the host's injection signal: agent-core emits it at the
+	// moment a message enters the conversation. That is what releases a held
+	// heartbeat slot.
+	//
+	// The turn-settled event is deliberately not used. The host emits it from the
+	// prompt cycle's `finally` whether or not the queued messages were drained, so
+	// pausing the queue mid-turn would release a slot whose card is still parked
+	// and let the next boundary stack a second card behind it. `message_end` never
+	// fires for a parked card. The visible display card is published on the
+	// session-listener channel only, so an extension sees the hidden
+	// reconciliation at consumption and never the card at admission — there is no
+	// ambiguity to disambiguate. Proven end to end against a real `AgentSession`
+	// in test/unit/workflow-heartbeat-parent-pickup.test.ts.
+	//
+	// Registered exactly once, at construction: `pi.on` has no unsubscribe, so a
+	// per-install registration would accumulate a handler on every notification
+	// cycle. The mutable scheduler reference is what routes the signal to the
+	// current installation, and a `null` reference makes it a no-op.
+	//
+	// The same condition decides whether the scheduler holds a slot at all, so the
+	// registration and the option can never disagree: a host that reports no
+	// consumption would leave a held slot with nothing to release it.
+	const parentAvailabilityReported = typeof pi.on === "function";
+	if (parentAvailabilityReported) {
+		// This handler observes, and for one narrow case replaces.
+		//
+		// The last guard on the heartbeat path (issue #1975): the three before it
+		// all sit before `sendMessage`, so a heartbeat the host has already
+		// admitted is beyond them. Consumption is the final moment before its
+		// steer joins the model's context, and `message_end` may return a
+		// replacement of the same role, so a heartbeat whose run has finished,
+		// vanished, or no longer owns that exact scheduled identity is excluded
+		// from context rather than steering the parent about stale work.
+		//
+		// `absent` counts as much as `terminal`. A card recovered at the restart
+		// door is consumed just after `session_start` cleared the store, so its run
+		// is normally absent. A durable resume may instead reuse the run id, but its
+		// future pending boundary has a different `scheduledAt`. Both cases fail
+		// exact pending ownership and preserve the no-backfill rule.
+		pi.on?.("message_end", (event, ctx) => {
+			// The host hands the session manager to the handler on its context; the
+			// top-level `pi.sessionManager` is not populated in every host, so the
+			// per-call one is preferred and the other is the fallback. Verified
+			// against a real `AgentSession` in
+			// test/unit/workflow-heartbeat-parent-pickup.test.ts.
+			const entries = (ctx?.sessionManager ?? pi.sessionManager)?.getEntries?.();
+			const invalidation = workflowHeartbeatContextInvalidation(event, entries, isWorkflowHeartbeatIdentityOwned);
+			if (invalidation !== undefined) return invalidation;
+			const identity = workflowHeartbeatConsumedIdentity(event, entries);
+			if (identity !== undefined) workflowHeartbeatScheduler?.notifyHeartbeatConsumed(identity);
+			return undefined;
+		});
+	}
+
+	/** Whether this exact identity is still pending for a current nonterminal run. */
+	function isWorkflowHeartbeatIdentityOwned(identity: WorkflowHeartbeatIdentity): boolean {
+		const pending = workflowHeartbeatSchedulerState.pending.get(identity.runId);
+		const run = store.runs().find((candidate) => candidate.id === identity.runId);
+		return pending?.scheduledAt === identity.scheduledAt && run !== undefined && !isWorkflowHeartbeatTerminalRun(run);
+	}
+
+	/**
+	 * Workflow heartbeats share the lifecycle-notice lifetime: they are armed
+	 * while notifications are active and disposed with them. The cadence itself
+	 * comes from the live registry, so a workflow reload is picked up without a
+	 * reinstall.
+	 */
+	const reinstallWorkflowHeartbeatScheduler = (): void => {
+		workflowHeartbeatScheduler?.dispose();
+		workflowHeartbeatScheduler = null;
+		if (!notificationsActive) return;
+		workflowHeartbeatScheduler = installWorkflowHeartbeatScheduler({
+			store,
+			state: workflowHeartbeatSchedulerState,
+			sendMessage: sendWorkflowNotificationMessage,
+			resolveIntervalMinutes: (workflowName) => runtimeProxy.registry.get(workflowName)?.heartbeatIntervalMinutes,
+			parentAvailabilityReported,
+			anchorStore: durableWorkflowHeartbeatAnchorStore(),
+		});
+	};
 
 	const hostStageSessionDir: { current: string | undefined } = { current: undefined };
 	const resolveDefaultStageSessionDir = (): string | undefined => hostStageSessionDir.current;
@@ -425,6 +558,7 @@ export function createWorkflowExtensionRuntimeState(
 		discoveryRef,
 		lifecycleNotificationState,
 		hilAnswerNotificationState,
+		workflowHeartbeatSchedulerState,
 		beforeRestoreCompleted,
 		runtimeForContext,
 		resetWorkflowDiscoveryForSession,
@@ -442,6 +576,10 @@ export function createWorkflowExtensionRuntimeState(
 			notificationsActive = active;
 			reinstallLifecycleNotifications();
 			reinstallHilAnswerNotifications();
+			// A fresh host session restarts the cadence from each run's persisted
+			// start time; prior-session schedule and pending state cannot apply.
+			if (!active) resetWorkflowHeartbeatSchedulerState(workflowHeartbeatSchedulerState);
+			reinstallWorkflowHeartbeatScheduler();
 		},
 		updateHostStageSessionDir(sessionManager) {
 			try {