@bastani/atomic 0.9.13 → 0.9.14-alpha.2

package/dist/builtin/workflows/src/extension/background-ui-adapter.ts

@@ -29,6 +29,7 @@
  *   src/tui/graph-view.ts pending-prompt rendering + key handling
  */
 
+import { requirePrimitivePromptAnswer } from "../shared/prompt-answer.js";
 import type { Store } from "../shared/store.js";
 import type { PendingPrompt, PromptKind } from "../shared/store-types.js";
 import type { WorkflowUIAdapter } from "../shared/types.js";
@@ -128,48 +129,26 @@ function fallbackForKind(descriptor: PromptDescriptor): unknown {
 export function buildBackgroundUIAdapter(store: Store, runId: string, signal?: AbortSignal): WorkflowUIAdapter {
 	return {
 		async input(prompt: string): Promise<string> {
-			const response = await ask(store, runId, { kind: "input", message: prompt }, signal);
-			return typeof response === "string" ? response : String(response ?? "");
+			const descriptor = { kind: "input" as const, message: prompt };
+			return requirePrimitivePromptAnswer(descriptor, await ask(store, runId, descriptor, signal)) as string;
 		},
 
 		async confirm(message: string): Promise<boolean> {
-			const response = await ask(store, runId, { kind: "confirm", message }, signal);
-			return response === true;
+			const descriptor = { kind: "confirm" as const, message };
+			return requirePrimitivePromptAnswer(descriptor, await ask(store, runId, descriptor, signal)) as boolean;
 		},
 
 		async select<T extends string>(message: string, options: readonly T[]): Promise<T> {
 			if (options.length === 0) {
 				throw new Error("atomic-workflows: ctx.ui.select requires at least one option");
 			}
-			const response = await ask(
-				store,
-				runId,
-				{
-					kind: "select",
-					message,
-					choices: options,
-				},
-				signal,
-			);
-			if (typeof response === "string" && (options as readonly string[]).includes(response)) {
-				return response as T;
-			}
-			return options[0]!;
+			const descriptor = { kind: "select" as const, message, choices: options };
+			return requirePrimitivePromptAnswer(descriptor, await ask(store, runId, descriptor, signal)) as T;
 		},
 
 		async editor(initial?: string): Promise<string> {
-			const response = await ask(
-				store,
-				runId,
-				{
-					kind: "editor",
-					message: "Edit and save to continue.",
-					initial,
-				},
-				signal,
-			);
-			if (typeof response === "string") return response;
-			return initial ?? "";
+			const descriptor = { kind: "editor" as const, message: "Edit and save to continue.", initial };
+			return requirePrimitivePromptAnswer(descriptor, await ask(store, runId, descriptor, signal)) as string;
 		},
 	};
 }

package/dist/builtin/workflows/src/extension/extension-factory.ts

@@ -8,6 +8,7 @@ import type { GraphOverlayPort } from "../tui/overlay-adapter.js";
 import { buildGraphOverlayAdapter } from "../tui/overlay-adapter.js";
 import { installStoreWidget, installToolExecutionHooks } from "../tui/store-widget-installer.js";
 import type { PostMortemHandleResolution } from "../tui/workflow-attach-pane-types.js";
+import { adoptWorkflowSessionRunState } from "./adopt-session-run-state.js";
 import { registerCompletedStageIntercomAskRouter } from "./completed-stage-intercom-ask.js";
 import { registerWorkflowLifecycleHandlers } from "./extension-lifecycle.js";
 import { createWorkflowExtensionRuntimeState } from "./extension-runtime-state.js";
@@ -68,6 +69,8 @@ function registerIntercomControl(pi: ExtensionAPI, intercomControlRef: { current
 }
 
 function factory(pi: ExtensionAPI): void {
+	adoptWorkflowSessionRunState(pi.events);
+
 	const adapters = buildRuntimeAdapters(pi);
 	const runtimeState = createWorkflowExtensionRuntimeState(pi, adapters);
 	const postMortemResolverDeps = {

package/dist/builtin/workflows/src/extension/extension-lifecycle.ts

@@ -47,6 +47,17 @@ function installDbosProcessShutdown(): void {
 	process.once("beforeExit", () => void shutdownDbosQuietly());
 }
 
+/**
+ * `/reload`, `/fork`, `/new`, and `/resume` replace the host session inside
+ * one process that keeps running the workflows. Those reasons must not kill
+ * in-flight runs or drop live executor handles. `startup` and any reason
+ * this code does not recognise still clear: neither names a predecessor
+ * that handed anything over. `/reload` reuses the host bus; the others do not.
+ */
+function replacementStopsWorkflows(reason: string | undefined): boolean {
+	return reason !== "reload" && reason !== "fork" && reason !== "new" && reason !== "resume";
+}
+
 export interface WorkflowLifecycleRegistrationDeps {
 	runtimeState: WorkflowExtensionRuntimeState;
 	storeWidgetRef: { current: (() => void) | null };
@@ -72,28 +83,35 @@ export function registerWorkflowLifecycleHandlers(pi: ExtensionAPI, deps: Workfl
 		const messageLabel = reason === "new" ? "Starting a new session" : "Resuming another session";
 		try {
 			const shouldSwitchSession = await confirmSessionSwitch(
-				`${actionLabel} and stop ${inFlightWorkflowCount} in-flight ${workflowNoun}?`,
-				`${messageLabel} will stop/kill ${inFlightWorkflowCount} in-flight ${workflowNoun} and clear workflow history tied to the current session.`,
+				`${actionLabel} with ${inFlightWorkflowCount} in-flight ${workflowNoun} still running?`,
+				`${messageLabel} keeps ${inFlightWorkflowCount} in-flight ${workflowNoun} running in this process. They stay on the session that started them.`,
 			);
 			if (shouldSwitchSession) return undefined;
 		} catch {
 			return undefined;
 		}
 		const cancelledLabel = reason === "new" ? "New session" : "Resume";
-		ctx?.ui?.notify?.(`${cancelledLabel} cancelled; in-flight workflows were left unchanged.`, "info");
+		ctx?.ui?.notify?.(`${cancelledLabel} cancelled; in-flight workflows keep running.`, "info");
 		return { cancel: true };
 	});
 
-	pi.on("session_start", async (_event, ctx) => {
+	pi.on("session_start", async (event, ctx) => {
+		const reason =
+			typeof event === "object" && event !== null && "reason" in event
+				? (event as { readonly reason?: string }).reason
+				: undefined;
 		runtimeState.resetWorkflowDiscoveryForSession();
 		deAdvertiseAskUserQuestionWhenHeadless(pi, ctx?.hasUI);
 		await runtimeState.ensureWorkflowConfigLoaded();
-		killAllRuns({ store, cancellation: cancellationRegistry, persistence: runtimeState.persistenceRef.current });
-		store.clear();
+		if (replacementStopsWorkflows(reason)) {
+			killAllRuns({ store, cancellation: cancellationRegistry, persistence: runtimeState.persistenceRef.current });
+			store.clear();
+		}
 		clearForms();
 		resetWorkflowLifecycleNotificationState(runtimeState.lifecycleNotificationState);
 		resetWorkflowHilAnswerNotificationState(runtimeState.hilAnswerNotificationState);
-		stageControlRegistry.clear();
+		if (replacementStopsWorkflows(reason)) stageControlRegistry.clear();
+		else stageControlRegistry.clearDetached();
 		// Named workflows publish lifecycle notices through the normal notification path.
 		runtimeState.setNotificationsActive(true);
 		runtimeState.startWorkflowDiscoveryWarmup(() => {
@@ -141,10 +159,10 @@ export function registerWorkflowLifecycleHandlers(pi: ExtensionAPI, deps: Workfl
 			} finally {
 				stageControlRegistry.clear();
 			}
-		} else {
-			// Every non-quit host-session boundary invalidates detached lazy handles
-			// synchronously, before they can attach to the replacement session.
+		} else if (replacementStopsWorkflows(reason)) {
 			stageControlRegistry.clear();
+		} else {
+			stageControlRegistry.clearDetached();
 		}
 		deps.storeWidgetRef.current?.();
 		deps.storeWidgetRef.current = null;

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 {