@bastani/atomic 0.9.13 → 0.9.14-alpha.1

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [Unreleased]
 
+## [0.9.14-alpha.1] - 2026-08-14
+
+### Fixed
+
+- **The whole transcript stays readable while the `ask_user_question` dialog is open** ([#2378](https://github.com/bastani-inc/atomic/issues/2378)). The dialog used to mount inline in the fullscreen dock, where it is a flex sibling of the transcript viewport, so a tall side-by-side questionnaire took the transcript's rows: on a 200×40 terminal the viewport collapsed from 34 rows to 6, and because the page step is derived from that viewport, `PageUp` crawled two lines at a time through a six-line window. The dialog is now pinned to the bottom as an overlay, which is not measured into the layout, so the transcript keeps its full viewport height and full page step — a single `PageUp` moves a full page and `Home` reaches the top of the scrollback. The overlay is also bounded so at least six transcript rows always survive on a short terminal, and the rows it does cover are added back to the transcript's scroll extent, so scrolling to the end raises the newest output into the visible strip instead of leaving it stranded behind the dialog. Transcript page, Home/End, and wheel input remain available while the questionnaire's Notes editor is active. Notes keeps text and edit keys, and the dialog still owns arrows, `enter`, `tab`, `space`, `esc`, clicks, and selection.
+- **The active questionnaire row stays visible on a short terminal.** Bounding a tall dialog has to drop rows, and dropping them from a fixed head cropped away the control you were using: at 80 columns a single-select option disappeared as the arrow keys moved down, multi-select choices plus their Next and Submit rows vanished, and the focused Notes input was hidden. The dialog now keeps a window around every active row, including single- and multi-select choices, Next, Submit, Cancel, inline sentinels, and focused text inputs.
+
+### Added
+
+- `ctx.ui.custom()` accepts `reserveTranscriptRows` for bottom-anchored overlay mounts. A blocking dialog sets it to be height-bounded against the terminal and to have its covered transcript-bottom suffix added to the scroll extent. Numeric and percentage `maxHeight` limits are applied before active-row windowing, so the focused control is not removed by a second fixed-head crop. Top and bottom margins are included in the overlay geometry, and concurrent overlays share the connected covered suffix instead of adding duplicate padding. Mount and resize height changes settle through one automatic repaint. A hidden overlay reserves nothing, and the reserve returns when it becomes visible again; handle-based, closed, or raw host removal releases the exact registration. Reserving overlays require a bottom anchor and reject `row` or a nonzero `offsetY`; leave the option unset for an overlay meant to take the screen, such as the workflow graph.
+- `OVERLAY_ACTIVE_ROW_MARKER` is exported for components mounted that way. Embed it in the line you most need kept — the selected row of a list — and the bound places what it keeps around that row instead of taking a fixed head. It is a zero-width APC sequence the host strips before painting, so it never reaches the terminal.
+
 ## [0.9.13] - 2026-08-13
 
 Cumulative release of the `0.9.13-alpha.1` – `0.9.13-alpha.4` prereleases. The summary below covers the user-visible outcome of that work; the per-change detail remains in the prerelease sections below.

package/dist/builtin/i-have-adhd/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/i-have-adhd",
-  "version": "0.9.13",
+  "version": "0.9.14-alpha.1",
   "private": true,
   "description": "Atomic extension that shapes responses for readers with ADHD. Fork of: https://github.com/ayghri/i-have-adhd",
   "contributors": [

package/dist/builtin/intercom/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/intercom",
-  "version": "0.9.13",
+  "version": "0.9.14-alpha.1",
   "private": true,
   "description": "Atomic extension providing a private coordination channel between parent and child agent sessions. Fork of: https://github.com/nicobailon/pi-intercom",
   "contributors": [

package/dist/builtin/mcp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/mcp",
-  "version": "0.9.13",
+  "version": "0.9.14-alpha.1",
   "private": true,
   "description": "Atomic extension that adapts MCP (Model Context Protocol) servers into the coding agent. Fork of: https://github.com/nicobailon/pi-mcp-adapter",
   "contributors": [

package/dist/builtin/subagents/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/subagents",
-  "version": "0.9.13",
+  "version": "0.9.14-alpha.1",
   "private": true,
   "description": "Atomic extension for delegating tasks to subagents with parallel execution. Fork of: https://github.com/nicobailon/pi-subagents",
   "contributors": [

package/dist/builtin/web-access/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/web-access",
-  "version": "0.9.13",
+  "version": "0.9.14-alpha.1",
   "private": true,
   "description": "Atomic extension for web search, URL fetching, GitHub repo cloning, PDF/video extraction. Fork of: https://github.com/nicobailon/pi-web-access",
   "contributors": [

package/dist/builtin/workflows/CHANGELOG.md

@@ -6,6 +6,18 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.9.14-alpha.1] - 2026-08-14
+
+### Added
+
+- Added `heartbeatIntervalMinutes` to the workflow authoring surface: an optional cadence in minutes that resolves to the `15`-minute default when omitted, treats `0` as an explicit disable, and rejects negative and non-finite values with a `TypeError` while the definition is authored, so a bad cadence fails at authoring rather than at schedule time. Every compiled definition carries the resolved value, and a distinct `workflows:workflow-heartbeat` event contract is declared alongside it — run id, workflow name, start time, scheduled time, and interval, with heartbeat identity keyed by run id plus scheduled time. The default interval constant, heartbeat custom type, and heartbeat event types are exported from the `@bastani/workflows` package root ([#1975](https://github.com/bastani-inc/atomic/issues/1975)).
+- Added workflow heartbeat scheduling and queued parent delivery for `heartbeatIntervalMinutes`, so a positive cadence now produces real heartbeats. While a top-level run is active, one heartbeat is raised per `startedAt + n × interval` boundary computed from the run's persisted start time — never from the previous delivery — so a slow send, a retry, or a process restart cannot shift the cadence. A resolved interval of `0` creates no timer and no durable record at all. One globally-next-due wake-up serves every enabled run rather than one recurring timer per run. At most one heartbeat per run is outstanding at a time: an outstanding heartbeat holds its slot until its card is actually consumed into the conversation — not merely until the parent's turn ends, which can happen while the card is still queued or its queue is paused — so a boundary that falls before that is skipped rather than stacked behind it, and the cadence then resumes at the first future boundary. However long a turn runs, and however often the queue is paused, only one unread heartbeat per run is ever waiting on a host that reports message consumption, which Atomic's chat host does. Delivery reuses the lifecycle-notice parent path (`triggerTurn`, `deliverAs: "steer"`, `persistWhenStreaming`) under the distinct `workflows:workflow-heartbeat` custom type with the five-field payload, so a busy parent chat is queued and never interrupted. Paused runs emit nothing and receive no backfill; a resumed or restarted run takes the first future boundary. Simultaneously due heartbeats reach the parent in scheduled-time order with the run id as the stable tie-break — a heartbeat being retried holds its place rather than letting a later one overtake it — terminal state is re-checked immediately before enqueue, again immediately before processing, and again before every delivery attempt including retries, and nested child workflow runs never heartbeat the parent chat. A run keeps the cadence its own definition was authored with, so editing, renaming, deleting, or reloading a workflow mid-run changes what the next launch uses and leaves runs already in flight on their launch cadence; the anchor record carries that cadence too, so it survives a durable resume. A run that launched with heartbeats disabled writes no durable record at all, so if it is resumed in a new process it adopts whatever the workflow then declares. A cadence below a millisecond schedules at the finest representable instant, and the cadence range carries a documented representable upper limit: above roughly 3 × 10^303 minutes `startedAt + interval` exceeds the largest finite timestamp, so no first boundary exists, nothing is scheduled, no durable record is written, and `ATOMIC_WORKFLOW_DEBUG=1` says so — such a cadence stays a valid positive interval but delivers no heartbeat, and `0` remains the only value that declares heartbeats off. A durable resume re-dispatches under the original run id but records a fresh start time, so each run also writes one reserved durable cadence-anchor record as soon as it has durable progress of its own, before its first boundary comes due; the anchor is read only as the earlier of itself and the run's current start time, so it keeps a resumed run on its original cadence without being able to move a boundary or raise a missed one. The delivered card names the workflow, run id, cadence, and elapsed run time and hints `/workflow status <run-id>`, rendered through the existing workflow notice-card renderer ([#1975](https://github.com/bastani-inc/atomic/issues/1975)).
+- Added terminal heartbeat cleanup and restart recovery, so a workflow's heartbeats stop when the run does. Reaching any terminal status — completed, failed, blocked, skipped, cancelled, or killed — drops everything that run's cadence held in one pass: its armed wake-up, its next scheduled boundary, its outstanding slot and the card text held for it, any heartbeat of its own still waiting in the delivery queue along with the retry timer that belonged to it, and its cadence and durable-anchor memos. No pending timer and no queued heartbeat outlives the run that owns it. The pass is idempotent: repeating it creates no state, resurrects no schedule, and does not throw, including for a run the scheduler never saw. Both completion races converge on suppression — a run that finishes before its due boundary is enqueued has that boundary dropped and is refused at enqueue, and one that finishes after enqueue but before processing has its queued identity discarded rather than sent. Cleanup keys on the run's observed state rather than on a transition event, so it also covers the paths that reach a terminal snapshot without a normal end transition — durable replay, completed-catalog reconstruction, and a restore that inserts an already-failed run — and the same pass runs at startup, making it the recovery pass: a stale durable anchor or leftover queued record belonging to an already-terminal run is discarded rather than replayed, its anchor is neither read nor rewritten, and a run the store no longer holds is dropped the same way. An active run is never affected by another run's cleanup, a paused run keeps the floor that stops it re-raising a boundary it already delivered, and recovery for an active run still selects the first future boundary rather than replaying a missed one. A late durable acknowledgement or a send that settles after cleanup re-creates nothing. A heartbeat the chat host had already accepted into the parent's queue is past that pass, because no queued message can be withdrawn, so it is invalidated at the moment the parent reads it instead: a heartbeat whose run has since reached a terminal state, or whose run this process no longer knows at all, is excluded from the model's context and never steers the parent about a run that is over. That closes both remaining stale paths — a card parked through a long turn while its run finished, and a card recovered from a previous process at startup, which would otherwise replay a boundary raised before the restart. The card already rendered in the transcript is deliberately left in place as a true record that the heartbeat was raised; only the model-facing steer is invalidated ([#1975](https://github.com/bastani-inc/atomic/issues/1975)).
+  A run that is only blocked on a recoverable provider or rate-limit failure remains stored as `running` and resumable: it raises no new heartbeat while blocked, but keeps its cadence state and any card already waiting with the parent. Cleanup runs only when the run's own status is terminal.
+  Parent pickup is keyed by the typed `workflows:workflow-heartbeat` entry and exact run id plus scheduled time rather than rendered card text, so a foreign custom message cannot release an unread heartbeat's slot and a durable resume that reuses the run id cannot revive an old admitted card after terminal cleanup ([#1975](https://github.com/bastani-inc/atomic/issues/1975)).
+  The cadence-anchor record is now written at the durability boundary itself, so it is durable before the checkpoint that made the run resumable is acknowledged. The scheduler's own write is guarded against runs with no durable progress and can therefore only be issued after resumability already exists; a process that exited inside that window left a resumable run carrying no record of what it launched with, and the next process then took both a freshly minted start time and whatever cadence the definition declared by then, shifting the phase and the cadence of a run already in flight ([#1975](https://github.com/bastani-inc/atomic/issues/1975)).
+- Every bundled builtin workflow now states its heartbeat cadence rather than inheriting it. `adversarial-verification`, `classify-and-act`, `fan-out-and-synthesize`, `generate-and-filter`, `goal`, `loop-until-done`, `ralph`, and `tournament` declare the `15`-minute default explicitly, so these long autonomous runs report to the parent chat on a known cadence and a future change to the global default cannot silently re-cadence them. `open-claude-design` sets `0` and runs quiet: it is driven by the user reviewing generated HTML turn by turn, so the parent chat is already holding it to its goal and a periodic alignment steer would interrupt that review rather than inform it. Behaviour is unchanged for the eight that were already resolving to the default; only `open-claude-design` changes ([#1975](https://github.com/bastani-inc/atomic/issues/1975)).
+
 ## [0.9.13] - 2026-08-13
 
 Cumulative release of the `0.9.13-alpha.1` – `0.9.13-alpha.4` prereleases. The summary below covers the user-visible outcome of that work; the per-change detail remains in the prerelease sections below.

package/dist/builtin/workflows/README.md

@@ -702,6 +702,14 @@ Because human input is runtime-only and workflows no longer carry a declaration-
 
 For library or package authoring, define reusable workflows with `workflow({...})` and export the returned definition. Hand-written objects with `__piWorkflow: true` are rejected by discovery and composition; `workflow({...})` is the public authoring surface. Standalone TypeScript workflow packages import `workflow` from `@bastani/workflows` and `Type` from `typebox` directly with no local `.d.ts` file or `declare module` shim. Migration from the removed builder API is mechanical: move `.description(...)` to `description`, `.input(key, schema)` calls into `inputs`, `.output(key, schema)` calls into `outputs`, `.worktreeFromInputs(...)` to `worktreeFromInputs`, and the `.run(fn)` callback to `run: fn`; delete `.compile()`. The former imperative `runWorkflow` object-form API is removed; use workflow definitions with the exported `run()` / registry helpers for programmatic execution.
 
+Set `heartbeatIntervalMinutes` to declare the workflow's heartbeat cadence in minutes. Omitting it uses the `15`-minute default; `0` explicitly disables heartbeats. Negative and non-finite values are rejected when the workflow definition is authored. The scheduler consumes this validated setting directly: while a top-level run is active it raises one heartbeat per `startedAt + n × interval` boundary, computed from the run's persisted start time rather than the previous delivery, so retries and restarts cannot shift the cadence. The example below heartbeats every 30 minutes, so a run started at 09:00 raises boundaries at 09:30, 10:00, 10:30, and so on.
+
+Each heartbeat reaches the parent chat as a `workflows:workflow-heartbeat` card through the same queued-steer delivery lifecycle notices use (`triggerTurn`, `deliverAs: "steer"`, `persistWhenStreaming`), so a busy parent is never interrupted — the steer lands at its next protocol-safe boundary. At most one heartbeat per run is outstanding at a time: it holds its slot until its card is actually consumed into the conversation, not merely until the parent's turn ends, so a boundary that falls before that is skipped rather than stacked behind it and the cadence then resumes at the first future boundary. Parent pickup follows the typed heartbeat entry and releases the slot only for the exact `runId + scheduledAt` identity; another custom message cannot release it by copying the rendered text. Paused runs emit nothing and are never backfilled, a resumed or restarted run takes the first future boundary rather than bursting missed ones, simultaneous heartbeats process in `scheduledAt` order with the run id as the tie-break, and a run that reaches a terminal state is suppressed before every delivery attempt.
+
+When a run reaches any terminal status — completed, failed, blocked, skipped, cancelled, or killed — one idempotent cleanup pass drops its wake-up timer, its next boundary, its outstanding slot, any heartbeat of its own still queued inside the scheduler with the retry timer that belonged to it, and its cadence and durable-anchor memos. Repeating the pass creates nothing and resurrects nothing. Because it reads observed state rather than transition events, it is also the recovery pass: a later process discards a stale durable anchor or leftover queued record for an already-terminal run instead of replaying it, and never replays a missed boundary for an active one. A heartbeat the host already accepted into the parent's queue is past that pass, since nothing withdraws a queued message, so it is invalidated when the parent reads it instead: its exact `runId + scheduledAt` must still be pending for a current nonterminal run. A same-ID durable resume therefore cannot revive an old card, and a heartbeat whose run is terminal or absent from this process is excluded from the model's context. That covers a card parked through a long turn and a card recovered from a previous process alike. The rendered card stays in the transcript as a record of what was raised; only the model-facing steer is invalidated ([#1975](https://github.com/bastani-inc/atomic/issues/1975)).
+
+A recoverable provider or rate-limit block is not the terminal `blocked` status: the run remains stored as `running` and resumable. It raises no new heartbeat while blocked, but keeps its cadence state and any card already waiting with the parent; cleanup runs only once the run's own status becomes terminal.
+
 ```ts
 import { workflow } from "@bastani/workflows";
 import { Type } from "typebox";
@@ -709,6 +717,7 @@ import { Type } from "typebox";
 export default workflow({
   name: "audit-auth",
   description: "Audit the authentication module.",
+  heartbeatIntervalMinutes: 30,
   inputs: {
     prompt: Type.String({ default: "Investigate the auth module" }),
   },

package/dist/builtin/workflows/builtin/adversarial-verification.ts

@@ -6,6 +6,10 @@ import { runAdversarialVerification } from "./adversarial-verification-runner.js
 export default workflow({
   name: "adversarial-verification",
   description: "Produce a candidate, challenge it with fresh-context rubric-based verifiers, and reduce their evidence through a bounded repair loop.",
+  // 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: {
     task: Type.String({ description: "Task whose candidate result must be independently verified." }),
     verifier_count: Type.Integer({ minimum: 1, maximum: 5, default: 3, description: "Number of independent verifiers per review round." }),

package/dist/builtin/workflows/builtin/classify-and-act.ts

@@ -8,6 +8,10 @@ export const DEFAULT_ACTION_CATEGORIES = ["analysis", "implementation", "researc
 export default workflow({
   name: "classify-and-act",
   description: "Classify a task with structured confidence, route deterministically to an isolated category action, and ask for human selection when confidence is low.",
+  // 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 to classify and execute." }),
     categories: Type.Array(Type.String({ minLength: 1 }), {

package/dist/builtin/workflows/builtin/fan-out-and-synthesize.ts

@@ -6,6 +6,10 @@ import { runFanOutAndSynthesize } from "./fan-out-and-synthesize-runner.js";
 export default workflow({
   name: "fan-out-and-synthesize",
   description: "Partition a task, run bounded independent artifact branches, then synthesize all evidence at an explicit barrier.",
+  // 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 to partition, investigate, and synthesize." }),
     max_branches: Type.Integer({

package/dist/builtin/workflows/builtin/generate-and-filter.ts

@@ -6,6 +6,10 @@ import { runGenerateAndFilter } from "./generate-and-filter-runner.js";
 export default workflow({
   name: "generate-and-filter",
   description: "Generate more independent candidates than needed, deduplicate and filter them by rubric, optionally judge them, and return a parent-consumable shortlist.",
+  // 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: "Prompt for candidate generation and selection." }),
     num_candidates: Type.Integer({ minimum: 2, maximum: 20, default: 8, description: "Number of independent candidates to generate." }),

package/dist/builtin/workflows/builtin/goal.ts

@@ -15,6 +15,10 @@ import { DEFAULT_MAX_TURNS } from "./goal-types.js";
 export default workflow({
   name: "goal",
   description: "Goal Runner workflow with bounded sub-agent orchestration turns, immutable acceptance criteria, ledger artifacts, parallel reviewers, and reducer-gated completion. When launching follow-up goal runs from review findings, pass the ORIGINAL task text as acceptance_criteria so deltas cannot drift from the literal contract. If the task includes submitting a pull request (or MR/review), remove that final action from the objective text and set create_pr=true instead when preparing the workflow inputs.",
+  // 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: {
     objective: Type.String({ description: "The objective or delta for this Goal Runner workflow run. Do not include PR/MR submission instructions here; strip them from the task text and request them via create_pr=true instead." }),
     acceptance_criteria: Type.Optional(Type.String({ description: "Original immutable task contract this run must remain consistent with. Defaults to objective. Orchestrators launching follow-up runs from reviewer findings should pass the ORIGINAL task text here." })),

package/dist/builtin/workflows/builtin/loop-until-done.ts

@@ -6,6 +6,10 @@ import { runLoopUntilDone } from "./loop-until-done-runner.js";
 export default workflow({
   name: "loop-until-done",
   description: "Repeat evidence-producing work and independent completion evaluation against a durable ledger until done or an inspectable iteration-limit failure.",
+  // 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: "Objective whose explicit completion condition controls the bounded loop." }),
     max_iterations: Type.Integer({

package/dist/builtin/workflows/builtin/open-claude-design.ts

@@ -27,6 +27,10 @@ import {
 export default workflow({
   name: "open-claude-design",
   description: "AI-powered design workflow: combined discovery/init → design-system/reference research → curated reference discovery → HTML generation → live-driven refinement → rich HTML handoff. The discovery stage asks what to build, the output type, and which references to emulate, then runs impeccable init for PRODUCT.md/DESIGN.md (references take precedence over project context). The user iteratively reviews the generated HTML.",
+  // Disabled: this workflow is driven by the user reviewing generated HTML,
+  // so the parent chat is already the thing holding it to its goal. A periodic
+  // alignment steer would interrupt that review rather than inform it.
+  heartbeatIntervalMinutes: 0,
   inputs: {
     prompt: Type.String({
       description: "What to design (for example, a dashboard, page, component, or prototype). The discovery stage refines this into a confirmed brief and asks for the output type and references.",

package/dist/builtin/workflows/builtin/ralph.ts

@@ -13,6 +13,10 @@ import { runRalphWorkflow } from "./ralph-runner.js";
 export default workflow({
   name: "ralph",
   description: "Raw prompt → research-prompt-refinement → research → orchestrate → multi-model parallel review loop with bounded iteration and immutable acceptance criteria. When launching follow-up ralph runs from review findings, pass the ORIGINAL task text as acceptance_criteria so deltas cannot drift from the literal contract. If the task includes submitting a pull request (or MR/review), remove that final action from the prompt text and set create_pr=true instead when preparing the workflow inputs.",
+  // 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: "The task or goal to research, execute, and refine. Do not include PR/MR submission instructions here; strip them from the task text and request them via create_pr=true instead." }),
     acceptance_criteria: Type.Optional(Type.String({ description: "Original immutable task contract this run must remain consistent with. Defaults to prompt. Orchestrators launching follow-up runs from reviewer findings should pass the ORIGINAL task text here." })),

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",
+  "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,