@osolmaz/pi-workflows 0.13.4 → 0.15.0

package/src/workflows/store.ts

@@ -1,6 +1,6 @@
 import { createHash, randomUUID } from "node:crypto";
 import { StateDatabase, workflowStatePath } from "../state/database.js";
-import { canonicalJson, type JsonValue } from "../state/json.js";
+import { canonicalJson, parseJson, type JsonValue } from "../state/json.js";
 import {
   StateMutationStore,
   StaleResourceError,
@@ -11,8 +11,22 @@ import {
   type MutationActor,
   type OwnerType,
 } from "../state/mutation.js";
+import {
+  initializeViewerRun,
+  recordViewerDeltas,
+  viewerTailPatch,
+  VIEWER_PAGE_SIZE,
+  type ViewerDeltaDraft,
+} from "../state/viewer.js";
 import { compositionMetadata } from "./composition.js";
+import { ClaimLostError } from "./errors.js";
+import { HumanDecisionStore } from "./human-decision.js";
 import { applyJsonPatch, validateJsonPatch } from "./json-patch.js";
+import {
+  reduceSessionEvents,
+  reduceSessionEventsFromCheckpoint,
+  type TemporalSessionState,
+} from "./session-reducer.js";
 import {
   applyWorkflowSettingsPatch,
   workflowSettingsScopeId,
@@ -32,7 +46,11 @@ import {
 import type {
   WorkflowDefinition,
   WorkflowDefinitionSnapshot,
+  WorkflowEffectRecovery,
+  WorkflowEffectReservation,
   HumanDecisionReceipt,
+  HumanDecisionRequest,
+  ResolvedHumanDecision,
   WorkflowNodeDefinition,
   WorkflowNodeResult,
   WorkflowNodeSnapshot,
@@ -44,6 +62,7 @@ import type {
   WorkflowSessionCapture,
   WorkflowSessionEntryRecord,
   WorkflowSessionEventRecord,
+  WorkflowSessionEventType,
   WorkflowSettingsSnapshot,
   WorkflowTraceEvent,
   WorkflowTraceEventDraft,
@@ -87,14 +106,85 @@ export type RunWriteAuthority = {
   ownerId: string;
   token: string;
   generation: number;
+  /** Duration used when a protected write renews this exact live claim. */
+  leaseMs?: number;
 };
 
 export type WorkflowRunStoreOptions = {
   authorityProvider?: (runId: string) => RunWriteAuthority | undefined;
+  /** Host-owned projection updates that must commit with each run snapshot. */
+  snapshotLifecycle?: (context: {
+    runId: string;
+    state: WorkflowRunState;
+    event: WorkflowTraceEvent;
+    database: StateDatabase;
+    now: number;
+  }) => void;
   state?: StateDatabase;
   readOnly?: boolean;
 };
 
+/** The state boundary used by workflow code, including out-of-process workers. */
+export interface WorkflowExecutionStore {
+  readonly databasePath: string;
+  initializeRun(
+    workflow: WorkflowDefinition,
+    state: WorkflowRunState,
+    options?: InitializeWorkflowRunOptions,
+  ): Promise<string>;
+  prepareRunResume(runId: string): Promise<LoadedWorkflowRun>;
+  readRun(
+    runId: string,
+    options?: ReadWorkflowRunOptions,
+  ): LoadedWorkflowRun | null | Promise<LoadedWorkflowRun | null>;
+  writeSnapshot(
+    runId: string,
+    state: WorkflowRunState,
+    event: WorkflowTraceEventDraft,
+  ): Promise<WorkflowTraceEvent>;
+  publishUpdate(
+    runId: string,
+    state: WorkflowRunState,
+    nodeId: string,
+    attemptId: string,
+    update: WorkflowUpdateInput,
+    options?: { signal?: AbortSignal },
+  ): Promise<{ event: WorkflowTraceEvent; record: WorkflowUpdateRecord }>;
+  findSettingsScope(
+    runId: string,
+    mountPath: string,
+    invocation: number,
+  ): WorkflowSettingsScopeRecord | undefined | Promise<WorkflowSettingsScopeRecord | undefined>;
+  ensureSettingsScope(options: {
+    runId: string;
+    mountPath: string;
+    invocation: number;
+    settings: JsonValue;
+  }): WorkflowSettingsScopeRecord | Promise<WorkflowSettingsScopeRecord>;
+  getSettingsScopeAtChange(
+    scopeId: string,
+    changeNumber: number,
+  ): WorkflowSettingsScopeRecord | undefined | Promise<WorkflowSettingsScopeRecord | undefined>;
+  createHumanDecisionRequest(request: HumanDecisionRequest): Promise<"created" | "adopted">;
+  readResolvedHumanDecision(decisionId: string): Promise<ResolvedHumanDecision | null>;
+  reserveEffect(options: {
+    runId: string;
+    attemptId: string;
+    effectType: string;
+    idempotencyKey: string;
+    request: JsonValue;
+    recovery: WorkflowEffectRecovery;
+  }): Promise<WorkflowEffectReservation>;
+  settleEffect(options: {
+    runId: string;
+    effectId: string;
+    attemptNumber: number;
+    outcome: "applied" | "rejected" | "ambiguous" | "cancelled";
+    result?: JsonValue;
+    error?: string;
+  }): Promise<void>;
+}
+
 type RunContext = {
   revision: number;
   lock: Promise<void>;
@@ -168,6 +258,23 @@ type EventRow = {
   recordedAt: number;
 };
 
+type ViewerSessionCheckpointRow = {
+  eventSeq: number;
+  stateHash: Buffer;
+};
+
+type ViewerSessionEventRow = {
+  runSeq: number;
+  eventType: string;
+  nodeId: string;
+  attemptId: string;
+  turnId: string | null;
+  messageId: string | null;
+  toolCallId: string | null;
+  payloadHash: Buffer;
+  recordedAt: number;
+};
+
 type SettingsScopeRow = {
   scopeId: string;
   resourceId: string;
@@ -317,12 +424,14 @@ export class WorkflowRunStore {
   private readonly authorityProvider:
     | ((runId: string) => RunWriteAuthority | undefined)
     | undefined;
+  private readonly snapshotLifecycle: WorkflowRunStoreOptions["snapshotLifecycle"];
   private readonly contexts = new Map<string, RunContext>();
   private readonly ownsState: boolean;
   private readonly mutations: StateMutationStore;
 
   constructor(databasePath: string = workflowStatePath(), options: WorkflowRunStoreOptions = {}) {
     this.authorityProvider = options.authorityProvider;
+    this.snapshotLifecycle = options.snapshotLifecycle;
     this.ownsState = options.state === undefined;
     this.state =
       options.state ??
@@ -339,10 +448,327 @@ export class WorkflowRunStore {
     if (this.ownsState) this.state.close();
   }
 
+  /** Host-only synchronization after a queue lifecycle mutation on the run resource. */
+  synchronizeRevision(runId: string): number {
+    const revision = this.resourceRevision(runId);
+    const context = this.contexts.get(runId);
+    if (context === undefined) {
+      this.contexts.set(runId, { revision, lock: Promise.resolve() });
+    } else {
+      context.revision = revision;
+    }
+    return revision;
+  }
+
+  async createHumanDecisionRequest(request: HumanDecisionRequest): Promise<"created" | "adopted"> {
+    return await new HumanDecisionStore(this.databasePath, { state: this.state }).createRequest(
+      request,
+    );
+  }
+
+  async readResolvedHumanDecision(decisionId: string): Promise<ResolvedHumanDecision | null> {
+    return await new HumanDecisionStore(this.databasePath, { state: this.state }).readResolved(
+      decisionId,
+    );
+  }
+
+  async reserveEffect(options: {
+    runId: string;
+    attemptId: string;
+    effectType: string;
+    idempotencyKey: string;
+    request: JsonValue;
+    recovery: WorkflowEffectRecovery;
+  }): Promise<WorkflowEffectReservation> {
+    return await this.withRunLock(options.runId, async () =>
+      this.state.transaction(() => {
+        requireBoundedEffectText(options.effectType, "type");
+        requireBoundedEffectText(options.idempotencyKey, "idempotency key");
+        const context = this.contextFor(options.runId);
+        const run = this.requireRunRow(options.runId);
+        this.assertWriteAuthority(run, context.revision);
+        const authority = this.authorityProvider?.(options.runId);
+        const payloadHash = this.state.putJson(
+          { recovery: options.recovery, request: options.request },
+          Date.now(),
+        );
+        const effectId = workflowEffectId(
+          run.resourceId,
+          options.effectType,
+          options.idempotencyKey,
+        );
+        const existing = this.state.connection
+          .prepare(
+            `SELECT status, payload_hash AS payloadHash, result_hash AS resultHash,
+                    attempt_count AS attemptCount
+             FROM effects WHERE effect_id = ?`,
+          )
+          .get(effectId);
+        if (isWorkflowEffectRow(existing)) {
+          if (!existing.payloadHash.equals(payloadHash)) {
+            throw new Error("Managed effect key was reused with another request");
+          }
+          if (existing.status === "applied") {
+            return {
+              effectId,
+              attemptNumber: existing.attemptCount,
+              disposition: "adopted",
+              ...(existing.resultHash === null
+                ? {}
+                : { result: this.state.readJson(existing.resultHash) }),
+            };
+          }
+          if (existing.status !== "pending") {
+            return {
+              effectId,
+              attemptNumber: existing.attemptCount,
+              disposition: "ambiguous",
+            };
+          }
+          return this.beginEffectAttempt(run, effectId, existing.attemptCount + 1, authority);
+        }
+        const now = Date.now();
+        const effectResourceId = this.mutations.ensureResource("effect", effectId, now);
+        this.mutations.mutate(
+          {
+            resourceId: effectResourceId,
+            operation: "effect.reserve",
+            actor: authority?.actor ?? { type: "system" },
+            expectedRevision: 0,
+          },
+          "effect.reserved",
+          () => {
+            this.state.connection
+              .prepare(
+                `INSERT INTO effects(
+                   effect_id, resource_id, source_resource_id, source_revision,
+                   effect_type, idempotency_key, payload_hash, owner_scope, status,
+                   attempt_count, created_at, updated_at
+                 ) VALUES (?, ?, ?, ?, ?, ?, ?, 'run', 'applying', 1, ?, ?)`,
+              )
+              .run(
+                effectId,
+                effectResourceId,
+                run.resourceId,
+                context.revision,
+                options.effectType,
+                options.idempotencyKey,
+                payloadHash,
+                now,
+                now,
+              );
+            this.insertEffectAttempt(effectId, 1, authority, now);
+          },
+          { now, payload: { runId: options.runId, attemptId: options.attemptId } },
+        );
+        return { effectId, attemptNumber: 1, disposition: "execute" };
+      }),
+    );
+  }
+
+  async settleEffect(options: {
+    runId: string;
+    effectId: string;
+    attemptNumber: number;
+    outcome: "applied" | "rejected" | "ambiguous" | "cancelled";
+    result?: JsonValue;
+    error?: string;
+  }): Promise<void> {
+    await this.withRunLock(options.runId, async () =>
+      this.state.transaction(() => {
+        const context = this.contextFor(options.runId);
+        const run = this.requireRunRow(options.runId);
+        this.assertWriteAuthority(run, context.revision);
+        const row = this.state.connection
+          .prepare(
+            `SELECT e.resource_id AS resourceId, e.status
+             FROM effects e WHERE e.effect_id = ? AND e.source_resource_id = ?`,
+          )
+          .get(options.effectId, run.resourceId);
+        if (!isWorkflowEffectIdentityRow(row) || row.status !== "applying") {
+          throw new Error("Managed effect is not applying");
+        }
+        const now = Date.now();
+        const revision = this.requireResourceRevision(row.resourceId);
+        const resultHash =
+          options.result === undefined ? null : this.state.putJson(options.result, now);
+        const errorHash =
+          options.error === undefined ? null : this.state.putText(options.error, now);
+        this.mutations.mutate(
+          {
+            resourceId: row.resourceId,
+            operation: "effect.settle",
+            actor: this.authorityProvider?.(options.runId)?.actor ?? { type: "system" },
+            expectedRevision: revision,
+          },
+          `effect.${options.outcome}`,
+          () => {
+            const changed = this.state.connection
+              .prepare(
+                `UPDATE effects
+                 SET status = ?, result_hash = ?, error_hash = ?, updated_at = ?, settled_at = ?
+                 WHERE effect_id = ? AND status = 'applying' AND attempt_count = ?`,
+              )
+              .run(
+                options.outcome,
+                resultHash,
+                errorHash,
+                now,
+                now,
+                options.effectId,
+                options.attemptNumber,
+              );
+            /* istanbul ignore if -- serialized effect mutation keeps this attempt current */
+            if (changed.changes !== 1) throw new Error("Managed effect attempt changed");
+            this.state.connection
+              .prepare(
+                `UPDATE effect_attempts
+                 SET finished_at = ?, outcome = ?, result_hash = ?, error_hash = ?
+                 WHERE effect_id = ? AND attempt_number = ? AND finished_at IS NULL`,
+              )
+              .run(
+                now,
+                options.outcome === "cancelled" ? "interrupted" : options.outcome,
+                resultHash,
+                errorHash,
+                options.effectId,
+                options.attemptNumber,
+              );
+          },
+          { now, payload: { runId: options.runId, outcome: options.outcome } },
+        );
+      }),
+    );
+  }
+
+  async recoverApplyingEffects(runId: string): Promise<"safe" | "ambiguous"> {
+    return await this.withRunLock(runId, async () =>
+      this.state.transaction(() => {
+        const context = this.contextFor(runId);
+        const run = this.requireRunRow(runId);
+        this.assertWriteAuthority(run, context.revision);
+        const authority = this.authorityProvider?.(runId);
+        const rows = this.state.connection
+          .prepare(
+            `SELECT effect_id AS effectId, resource_id AS resourceId,
+                    payload_hash AS payloadHash, attempt_count AS attemptCount
+             FROM effects WHERE source_resource_id = ? AND status = 'applying'`,
+          )
+          .all(run.resourceId)
+          .filter(isApplyingEffectRow);
+        let ambiguous = false;
+        for (const row of rows) {
+          const payload = this.state.readJson(row.payloadHash);
+          const recovery = effectRecoveryFromPayload(payload);
+          const status = recovery === "idempotent" ? "pending" : "ambiguous";
+          if (status === "ambiguous") ambiguous = true;
+          const now = Date.now();
+          const revision = this.requireResourceRevision(row.resourceId);
+          this.mutations.mutate(
+            {
+              resourceId: row.resourceId,
+              operation: "effect.recover",
+              actor: authority?.actor ?? { type: "system" },
+              expectedRevision: revision,
+            },
+            status === "pending" ? "effect.retry_ready" : "effect.ambiguous",
+            () => {
+              this.state.connection
+                .prepare(
+                  `UPDATE effects SET status = ?, updated_at = ?, settled_at = ?
+                   WHERE effect_id = ? AND status = 'applying'`,
+                )
+                .run(status, now, status === "ambiguous" ? now : null, row.effectId);
+              this.state.connection
+                .prepare(
+                  `UPDATE effect_attempts SET finished_at = ?, outcome = 'interrupted'
+                   WHERE effect_id = ? AND attempt_number = ? AND finished_at IS NULL`,
+                )
+                .run(now, row.effectId, row.attemptCount);
+            },
+            { now, payload: { runId, recovery } },
+          );
+        }
+        return ambiguous ? "ambiguous" : "safe";
+      }),
+    );
+  }
+
+  private beginEffectAttempt(
+    run: RunRow,
+    effectId: string,
+    attemptNumber: number,
+    authority: RunWriteAuthority | undefined,
+  ): WorkflowEffectReservation {
+    const now = Date.now();
+    const row = this.state.connection
+      .prepare("SELECT resource_id AS resourceId FROM effects WHERE effect_id = ?")
+      .get(effectId);
+    /* istanbul ignore if -- beginEffectAttempt is called only for a persisted effect */
+    if (!isResourceIdRow(row)) throw new Error("Managed effect resource is missing");
+    const revision = this.requireResourceRevision(row.resourceId);
+    this.mutations.mutate(
+      {
+        resourceId: row.resourceId,
+        operation: "effect.retry",
+        actor: authority?.actor ?? { type: "system" },
+        expectedRevision: revision,
+      },
+      "effect.retry_started",
+      () => {
+        this.state.connection
+          .prepare(
+            `UPDATE effects SET status = 'applying', attempt_count = ?, updated_at = ?,
+                    settled_at = NULL, error_hash = NULL
+             WHERE effect_id = ? AND status = 'pending'`,
+          )
+          .run(attemptNumber, now, effectId);
+        this.insertEffectAttempt(effectId, attemptNumber, authority, now);
+      },
+      { now, payload: { runId: run.runId, attemptNumber } },
+    );
+    return { effectId, attemptNumber, disposition: "execute" };
+  }
+
+  private insertEffectAttempt(
+    effectId: string,
+    attemptNumber: number,
+    authority: RunWriteAuthority | undefined,
+    now: number,
+  ): void {
+    this.state.connection
+      .prepare(
+        `INSERT INTO effect_attempts(
+           effect_id, attempt_number, owner_id, lease_generation, started_at
+         ) VALUES (?, ?, ?, ?, ?)`,
+      )
+      .run(
+        effectId,
+        attemptNumber,
+        authority?.ownerId ?? "system",
+        authority?.generation ?? 1,
+        now,
+      );
+  }
+
   async initializeRun(
     workflow: WorkflowDefinition,
     state: WorkflowRunState,
     options: InitializeWorkflowRunOptions = {},
+  ): Promise<string> {
+    return await this.initializeRunFromSnapshot(
+      createDefinitionSnapshot(workflow),
+      workflow.name,
+      state,
+      options,
+    );
+  }
+
+  async initializeRunFromSnapshot(
+    snapshot: WorkflowDefinitionSnapshot,
+    workflowName: string,
+    state: WorkflowRunState,
+    options: InitializeWorkflowRunOptions = {},
   ): Promise<string> {
     assertValidRunId(state.runId);
     if (!this.contexts.has(state.runId)) {
@@ -356,7 +782,6 @@ export class WorkflowRunStore {
       let acceptedRevision = 1;
       const now = Date.now();
       const at = new Date(now).toISOString();
-      const snapshot = createDefinitionSnapshot(workflow);
       const definitionJson = canonicalJson(snapshot);
       const definitionDigest = createHash("sha256").update(definitionJson).digest();
       const source = sourceForState(state, definitionDigest);
@@ -377,14 +802,33 @@ export class WorkflowRunStore {
           acceptedRevision = revision;
           state.traceSeq = revision;
           state.updatedAt = at;
-          insertRunEvent(this.state, reserved.resourceId, revision, at, {
+          const traceEvent: WorkflowTraceEvent = {
+            seq: revision,
+            at,
+            runId: state.runId,
             scope: "run",
             type: "run_initialized",
-            payload: { workflowName: workflow.name },
-          });
+            payload: { workflowName },
+          };
+          insertRunEvent(this.state, reserved.resourceId, revision, at, traceEvent);
           this.persistRunState(reserved, state, revision, now);
+          initializeViewerRun(this.state, state.runId, now);
           this.initializeRunSettingsAndFollowUps(state, options.initialSettings ?? [], now);
+          if (state.parentRunId !== undefined) {
+            recordViewerDeltas(
+              this.state,
+              state.parentRunId,
+              this.viewerInspectorTargets(state.parentRunId),
+              now,
+            );
+          }
           this.syncNodeAttempts(state, snapshot, now);
+          recordViewerDeltas(
+            this.state,
+            state.runId,
+            [...runViewerTargets(state, traceEvent), ...this.viewerInspectorTargets(state.runId)],
+            now,
+          );
           this.syncContinuationIdentity(state);
           context.revision = revision;
           return;
@@ -397,7 +841,7 @@ export class WorkflowRunStore {
              ) VALUES (?, ?, ?, ?)
              ON CONFLICT(definition_digest) DO NOTHING`,
           )
-          .run(definitionDigest, workflow.name, definitionHash, now);
+          .run(definitionDigest, workflowName, definitionHash, now);
         this.state.connection
           .prepare(
             `INSERT INTO resources(
@@ -442,14 +886,23 @@ export class WorkflowRunStore {
             now,
             state.finishedAt === undefined ? null : Date.parse(state.finishedAt),
           );
+        initializeViewerRun(this.state, state.runId, now);
         this.insertRunSources(state.runId, source, state.workflowSources ?? []);
         this.syncContinuationIdentity(state);
         insertRunEvent(this.state, resourceId, 1, at, {
           scope: "run",
           type: "run_created",
-          payload: { workflowName: workflow.name },
+          payload: { workflowName },
         });
         this.initializeRunSettingsAndFollowUps(state, options.initialSettings ?? [], now);
+        if (state.parentRunId !== undefined) {
+          recordViewerDeltas(
+            this.state,
+            state.parentRunId,
+            this.viewerInspectorTargets(state.parentRunId),
+            now,
+          );
+        }
         this.syncNodeAttempts(state, snapshot, now);
       });
       this.contexts.set(state.runId, { revision: acceptedRevision, lock: Promise.resolve() });
@@ -496,6 +949,12 @@ export class WorkflowRunStore {
           now,
           now,
         );
+      recordViewerDeltas(
+        this.state,
+        options.runId,
+        this.viewerInspectorTargets(options.runId),
+        now,
+      );
       return this.settingsScopeRecord(this.requireSettingsScopeRow(scopeId));
     });
   }
@@ -680,6 +1139,12 @@ export class WorkflowRunStore {
                 `UPDATE workflow_settings SET current_hash = ?, updated_at = ? WHERE scope_id = ?`,
               )
               .run(savedAfterHash, now, request.scopeId);
+            recordViewerDeltas(
+              this.state,
+              request.runId,
+              this.viewerInspectorTargets(request.runId),
+              now,
+            );
             return changeId;
           },
           {
@@ -784,6 +1249,12 @@ export class WorkflowRunStore {
                 now,
                 now,
               );
+            recordViewerDeltas(
+              this.state,
+              request.runId,
+              this.viewerInspectorTargets(request.runId),
+              now,
+            );
             return followUpId;
           },
           { payload: { runId: request.runId, requestId: request.requestId } },
@@ -834,6 +1305,12 @@ export class WorkflowRunStore {
         if (update.changes !== 1) {
           throw new StaleResourceError("Workflow follow-up changed before removal");
         }
+        recordViewerDeltas(
+          this.state,
+          request.runId,
+          this.viewerInspectorTargets(request.runId),
+          now,
+        );
       },
       { payload: { followUpId: request.followUpId, source: request.source } },
     );
@@ -956,6 +1433,12 @@ export class WorkflowRunStore {
              WHERE run_id = ? AND status = 'pending_presentation'`,
             )
             .run(now, options.runId);
+          recordViewerDeltas(
+            this.state,
+            options.runId,
+            this.viewerInspectorTargets(options.runId),
+            now,
+          );
         },
         { payload: { runId: options.runId, state: options.state } },
       );
@@ -1036,6 +1519,7 @@ export class WorkflowRunStore {
         if (update.changes !== 1) {
           throw new StaleResourceError("Workflow follow-up changed before delivery completed");
         }
+        recordViewerDeltas(this.state, row.runId, this.viewerInspectorTargets(row.runId), now);
       },
       { payload: { followUpId, sessionEntryId } },
     );
@@ -1071,14 +1555,19 @@ export class WorkflowRunStore {
            WHERE run_id = ? AND status IN ('pending', 'running', 'waiting')`,
         )
         .run(now, runId);
-      insertRunEvent(this.state, row.resourceId, nextRevision, at, {
+      const traceEvent: WorkflowTraceEvent = {
+        seq: nextRevision,
+        at,
+        runId,
         scope: "run",
         type: "run_resume_prepared",
         payload: {},
-      });
+      };
+      insertRunEvent(this.state, row.resourceId, nextRevision, at, traceEvent);
       loaded.state.traceSeq = nextRevision;
       loaded.state.updatedAt = at;
       this.persistRunState(row, loaded.state, nextRevision, now);
+      recordViewerDeltas(this.state, runId, runViewerTargets(loaded.state, traceEvent), now);
       context.revision = nextRevision;
     });
     const prepared = this.readRun(runId, { includeTrace: true });
@@ -1099,6 +1588,7 @@ export class WorkflowRunStore {
     delete loaded.state.currentNode;
     delete loaded.state.currentAttemptId;
     delete loaded.state.currentNodeStartedAt;
+    delete loaded.state.currentNodeDeadlineAt;
     delete loaded.state.currentSettingsScopeId;
     delete loaded.state.currentSettingsChangeNumber;
     delete loaded.state.currentSettingsHash;
@@ -1120,81 +1610,95 @@ export class WorkflowRunStore {
     update: WorkflowUpdateInput,
     options: { signal?: AbortSignal } = {},
   ): Promise<{ event: WorkflowTraceEvent; record: WorkflowUpdateRecord }> {
-    return await this.withRunLock(runId, async () => {
-      if (options.signal?.aborted === true) {
-        throw options.signal.reason ?? new Error("workflow update attempt is no longer active");
-      }
-      const exists = (state.updates ?? []).some(
-        (record) => record.type === update.type && record.key === update.key,
-      );
-      if (!exists && (state.updates?.length ?? 0) >= MAX_CURRENT_UPDATES) {
-        throw new Error(`workflow run supports at most ${MAX_CURRENT_UPDATES} current updates`);
-      }
-      const data = structuredClone(update.data) as Record<string, unknown>;
-      const updateId = createUpdateId();
-      let acceptedEvent: WorkflowTraceEvent | undefined;
-      let acceptedRecord: WorkflowUpdateRecord | undefined;
-      this.state.transaction(() => {
-        const context = this.contextFor(runId);
-        const run = this.requireRunRow(runId);
-        this.assertWriteAuthority(run, context.revision);
-        const revision = context.revision + 1;
-        const at = new Date().toISOString();
-        const event: WorkflowTraceEvent = {
-          seq: revision,
-          at,
-          runId,
-          scope: "node",
-          type: "update_published",
-          nodeId,
-          attemptId,
-          payload: { updateId, type: update.type, key: update.key, data },
-        };
-        const record: WorkflowUpdateRecord = {
-          updateId,
-          seq: revision,
-          at,
-          runId,
-          nodeId,
-          attemptId,
-          type: update.type,
-          key: update.key,
-          data,
-        };
-        state.updates = updateProjection(state.updates, record);
-        state.traceSeq = revision;
-        state.updatedAt = at;
-        this.ensureAttempt(state, nodeId, attemptId, Date.now());
-        const dataHash = this.state.putJson(data);
-        const nextUpdateSeq = this.nextUpdateSequence(attemptId);
-        this.state.connection
-          .prepare(
-            `INSERT INTO workflow_updates(
+    return await this.withRunLock(runId, async () =>
+      this.publishUpdateSynchronous(runId, state, nodeId, attemptId, update, options),
+    );
+  }
+
+  /** Host-only synchronous form for an already serialized command transaction. */
+  publishUpdateSynchronous(
+    runId: string,
+    state: WorkflowRunState,
+    nodeId: string,
+    attemptId: string,
+    update: WorkflowUpdateInput,
+    options: { signal?: AbortSignal } = {},
+  ): { event: WorkflowTraceEvent; record: WorkflowUpdateRecord } {
+    if (options.signal?.aborted === true) {
+      throw options.signal.reason ?? new Error("workflow update attempt is no longer active");
+    }
+    const exists = (state.updates ?? []).some(
+      (record) => record.type === update.type && record.key === update.key,
+    );
+    if (!exists && (state.updates?.length ?? 0) >= MAX_CURRENT_UPDATES) {
+      throw new Error(`workflow run supports at most ${MAX_CURRENT_UPDATES} current updates`);
+    }
+    const data = structuredClone(update.data) as Record<string, unknown>;
+    const updateId = createUpdateId();
+    let acceptedEvent: WorkflowTraceEvent | undefined;
+    let acceptedRecord: WorkflowUpdateRecord | undefined;
+    this.state.transaction(() => {
+      const context = this.contextFor(runId);
+      const run = this.requireRunRow(runId);
+      this.assertWriteAuthority(run, context.revision);
+      const revision = context.revision + 1;
+      const at = new Date().toISOString();
+      const event: WorkflowTraceEvent = {
+        seq: revision,
+        at,
+        runId,
+        scope: "node",
+        type: "update_published",
+        nodeId,
+        attemptId,
+        payload: { updateId, type: update.type, key: update.key, data },
+      };
+      const record: WorkflowUpdateRecord = {
+        updateId,
+        seq: revision,
+        at,
+        runId,
+        nodeId,
+        attemptId,
+        type: update.type,
+        key: update.key,
+        data,
+      };
+      state.updates = updateProjection(state.updates, record);
+      state.traceSeq = revision;
+      state.updatedAt = at;
+      this.ensureAttempt(state, nodeId, attemptId, Date.now());
+      const dataHash = this.state.putJson(data);
+      const nextUpdateSeq = this.nextUpdateSequence(attemptId);
+      this.state.connection
+        .prepare(
+          `INSERT INTO workflow_updates(
                update_id, attempt_id, update_seq, run_revision,
                update_type, update_key, data_hash, recorded_at
              ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
-          )
-          .run(
-            updateId,
-            attemptId,
-            nextUpdateSeq,
-            revision,
-            update.type,
-            update.key,
-            dataHash,
-            Date.now(),
-          );
-        insertRunEvent(this.state, run.resourceId, revision, at, event);
-        this.persistRunState(run, state, revision, Date.now());
-        context.revision = revision;
-        acceptedEvent = event;
-        acceptedRecord = record;
-      });
-      if (acceptedEvent === undefined || acceptedRecord === undefined) {
-        throw new Error("Workflow update transaction did not produce a result");
-      }
-      return { event: acceptedEvent, record: acceptedRecord };
+        )
+        .run(
+          updateId,
+          attemptId,
+          nextUpdateSeq,
+          revision,
+          update.type,
+          update.key,
+          dataHash,
+          Date.now(),
+        );
+      insertRunEvent(this.state, run.resourceId, revision, at, event);
+      const committedAt = Date.now();
+      this.persistRunState(run, state, revision, committedAt);
+      recordViewerDeltas(this.state, runId, runViewerTargets(state, event), committedAt);
+      context.revision = revision;
+      acceptedEvent = event;
+      acceptedRecord = record;
     });
+    if (acceptedEvent === undefined || acceptedRecord === undefined) {
+      throw new Error("Workflow update transaction did not produce a result");
+    }
+    return { event: acceptedEvent, record: acceptedRecord };
   }
 
   async writeSnapshot(
@@ -1220,6 +1724,14 @@ export class WorkflowRunStore {
         this.persistRunState(run, state, revision, now);
         this.transitionFollowUpsForRunState(state, event, now);
         this.syncNodeAttempts(state, snapshot, now);
+        recordViewerDeltas(this.state, runId, runViewerTargets(state, traceEvent), now);
+        this.snapshotLifecycle?.({
+          runId,
+          state,
+          event: traceEvent,
+          database: this.state,
+          now,
+        });
         context.revision = revision;
         accepted = traceEvent;
       });
@@ -1254,6 +1766,7 @@ export class WorkflowRunStore {
     await this.withRunLock(runId, async () => {
       const segmentId = segmentIdFor(runId, attemptId);
       if (this.segmentRow(segmentId) !== undefined) return;
+      const hasExistingSession = this.segmentRows(runId).length > 0;
       this.state.transaction(() => {
         const run = this.requireRunRow(runId);
         const context = this.contextFor(runId);
@@ -1313,7 +1826,7 @@ export class WorkflowRunStore {
           .run(binding.piSessionId, now, runId);
         const revision = context.revision + 1;
         const at = new Date(now).toISOString();
-        insertRunEvent(this.state, run.resourceId, revision, at, {
+        const traceEvent: WorkflowTraceEvent = {
           seq: revision,
           at,
           runId,
@@ -1323,11 +1836,38 @@ export class WorkflowRunStore {
             piSessionId: binding.piSessionId,
             ...(attemptId !== undefined ? { captureAttemptId: attemptId } : {}),
           },
-        });
+        };
+        insertRunEvent(this.state, run.resourceId, revision, at, traceEvent);
         const current = this.readRunState(run, this.readDefinition(run.definitionHash));
         current.traceSeq = revision;
         current.updatedAt = at;
         this.persistRunState(run, current, revision, now);
+        const targets = runViewerTargets(current, traceEvent);
+        targets[0]?.patch?.push(
+          hasExistingSession
+            ? {
+                op: "add",
+                path: "/session/binding",
+                value: parseJson(canonicalJson(binding)),
+              }
+            : {
+                op: "add",
+                path: "/session",
+                value: parseJson(
+                  canonicalJson({
+                    binding,
+                    presentationRevision: 0,
+                    entryPage: { presentationRevision: 0, start: 0, total: 0, items: [] },
+                    eventPage: { presentationRevision: 0, start: 0, total: 0, items: [] },
+                    eventsMalformed: false,
+                    eventsTornTail: false,
+                    capture: null,
+                    replayCheckpoint: null,
+                  }),
+                ),
+              },
+        );
+        recordViewerDeltas(this.state, runId, targets, now);
         context.revision = revision;
       });
     });
@@ -1343,15 +1883,26 @@ export class WorkflowRunStore {
       this.assertSessionWriteAuthority(runId);
       const revision = this.requireResourceRevision(segmentResourceId(segment));
       const sequence = segment.entryCount + 1;
+      const runSequenceRow = this.state.connection
+        .prepare(
+          `SELECT COALESCE(MAX(run_seq), 0) + 1 AS count
+           FROM session_entries WHERE run_id = ?`,
+        )
+        .get(runId);
+      if (!isCountRow(runSequenceRow)) {
+        throw new Error("Workflow session entry sequence is unavailable");
+      }
+      const runSequence = runSequenceRow.count;
       const now = Date.now();
       const entryHash = this.state.putJson(entry, now);
       const entryId = typeof entry.id === "string" ? entry.id : `entry-${sequence}`;
       this.state.connection
         .prepare(
-          `INSERT INTO session_entries(segment_id, entry_seq, entry_id, entry_hash, recorded_at)
-           VALUES (?, ?, ?, ?, ?)`,
+          `INSERT INTO session_entries(
+             segment_id, run_id, entry_seq, run_seq, entry_id, entry_hash, recorded_at
+           ) VALUES (?, ?, ?, ?, ?, ?, ?)`,
         )
-        .run(segment.segmentId, sequence, entryId, entryHash, now);
+        .run(segment.segmentId, runId, sequence, runSequence, entryId, entryHash, now);
       this.state.connection
         .prepare("UPDATE session_segments SET entry_count = ? WHERE segment_id = ?")
         .run(sequence, segment.segmentId);
@@ -1366,6 +1917,37 @@ export class WorkflowRunStore {
         null,
         now,
       );
+      recordViewerDeltas(
+        this.state,
+        runId,
+        [
+          {
+            targetType: "conversation",
+            targetKey: "entries:tail",
+            patch: viewerTailPatch(runSequence - 1, [
+              parseJson(
+                canonicalJson({
+                  seq: runSequence,
+                  at: new Date(now).toISOString(),
+                  entry,
+                }),
+              ),
+            ]),
+          },
+          {
+            targetType: "conversation",
+            targetKey: "capture",
+            patch: [
+              {
+                op: "replace",
+                path: "/capture/entryCount",
+                value: runSequence,
+              },
+            ],
+          },
+        ],
+        now,
+      );
       return sequence;
     });
   }
@@ -1382,6 +1964,18 @@ export class WorkflowRunStore {
       const current = this.requireSegment(segment.segmentId);
       if (current.status !== "recording") throw new Error("Session event capture has stopped");
       let expected = current.eventCount + 1;
+      const runSequenceRow = this.state.connection
+        .prepare(
+          `SELECT COALESCE(MAX(run_seq), 0) + 1 AS count
+           FROM session_events WHERE run_id = ?`,
+        )
+        .get(runId);
+      if (!isCountRow(runSequenceRow)) {
+        throw new Error("Workflow session event sequence is unavailable");
+      }
+      let runSequence = runSequenceRow.count;
+      const firstRunSequence = runSequence;
+      const projectedRecords: Array<WorkflowSessionEventRecord & { stepIndex?: number }> = [];
       for (const record of records) {
         validateSessionEventRecord(record);
         if (record.seq !== expected) {
@@ -1394,13 +1988,15 @@ export class WorkflowRunStore {
         this.state.connection
           .prepare(
             `INSERT INTO session_events(
-               segment_id, event_seq, event_type, node_id, attempt_id,
+               segment_id, run_id, event_seq, run_seq, event_type, node_id, attempt_id,
                turn_id, message_id, tool_call_id, payload_hash, recorded_at
-             ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+             ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
           )
           .run(
             current.segmentId,
+            runId,
             record.seq,
+            runSequence,
             record.type,
             record.nodeId,
             record.attemptId,
@@ -1410,14 +2006,189 @@ export class WorkflowRunStore {
             payloadHash,
             Date.parse(record.at),
           );
+        const stepIndex = this.state.connection
+          .prepare(
+            `SELECT step_index AS stepIndex
+             FROM run_steps WHERE run_id = ? AND attempt_id = ?`,
+          )
+          .get(runId, record.attemptId);
+        projectedRecords.push({
+          ...record,
+          seq: runSequence,
+          ...(isStepIndexRow(stepIndex) ? { stepIndex: stepIndex.stepIndex } : {}),
+        });
         expected += 1;
+        runSequence += 1;
       }
       this.state.connection
         .prepare("UPDATE session_segments SET event_count = ? WHERE segment_id = ?")
         .run(expected - 1, current.segmentId);
+      const recordedAt = Date.now();
+      this.recordSessionReplayCheckpoints(runId, firstRunSequence, projectedRecords, recordedAt);
+      const projectedValues = projectedRecords.map((record) => parseJson(canonicalJson(record)));
+      const nextEventTotal = firstRunSequence - 1 + projectedValues.length;
+      const previousBlock = Math.floor(Math.max(0, firstRunSequence - 2) / VIEWER_PAGE_SIZE);
+      const nextBlock = Math.floor(Math.max(0, nextEventTotal - 1) / VIEWER_PAGE_SIZE);
+      const crossesPageBoundary = previousBlock !== nextBlock;
+      recordViewerDeltas(
+        this.state,
+        runId,
+        [
+          {
+            targetType: "timeline",
+            targetKey: crossesPageBoundary ? "session:reload" : "session:tail",
+            patch: crossesPageBoundary
+              ? [{ op: "replace", path: "/total", value: nextEventTotal }]
+              : [
+                  { op: "append", path: "/items", value: projectedValues },
+                  { op: "replace", path: "/total", value: nextEventTotal },
+                ],
+          },
+          {
+            targetType: "conversation",
+            targetKey: "capture",
+            patch: [
+              {
+                op: "replace",
+                path: "/capture/eventCount",
+                value: nextEventTotal,
+              },
+              {
+                op: "replace",
+                path: "/capture/lastEventSeq",
+                value: nextEventTotal,
+              },
+            ],
+          },
+        ],
+        recordedAt,
+      );
     });
   }
 
+  private recordSessionReplayCheckpoints(
+    runId: string,
+    firstRunSequence: number,
+    newRecords: WorkflowSessionEventRecord[],
+    now: number,
+  ): void {
+    const row = this.state.connection
+      .prepare(
+        `SELECT event_seq AS eventSeq, state_hash AS stateHash
+         FROM viewer_session_checkpoints
+         WHERE run_id = ? ORDER BY event_seq DESC LIMIT 1`,
+      )
+      .get(runId);
+    let checkpoint = reduceSessionEvents([], [], 0);
+    if (isViewerSessionCheckpointRow(row)) {
+      const saved = this.state.readJson(row.stateHash);
+      if (!isTemporalSessionState(saved) || saved.throughSeq !== row.eventSeq) {
+        throw new Error(`Viewer session checkpoint is invalid for ${runId}`);
+      }
+      checkpoint = saved;
+    }
+    let pending = [
+      ...this.sessionEventRecords(runId, checkpoint.throughSeq, firstRunSequence),
+      ...newRecords,
+    ];
+    const lastSequence = pending.at(-1)?.seq ?? checkpoint.throughSeq;
+    let boundary = (Math.floor(checkpoint.throughSeq / VIEWER_PAGE_SIZE) + 1) * VIEWER_PAGE_SIZE;
+    while (boundary <= lastSequence) {
+      const page = pending.filter((event) => event.seq <= boundary);
+      checkpoint = reduceSessionEventsFromCheckpoint([], page, boundary, checkpoint);
+      checkpoint = boundedTemporalCheckpoint(checkpoint);
+      const stateHash = this.state.putJson(checkpoint, now);
+      this.state.connection
+        .prepare(
+          `INSERT INTO viewer_session_checkpoints(run_id, event_seq, state_hash, recorded_at)
+           VALUES (?, ?, ?, ?)`,
+        )
+        .run(runId, boundary, stateHash, now);
+      pending = pending.filter((event) => event.seq > boundary);
+      boundary += VIEWER_PAGE_SIZE;
+    }
+  }
+
+  private sessionEventRecords(
+    runId: string,
+    afterSequence: number,
+    beforeSequence: number,
+  ): WorkflowSessionEventRecord[] {
+    return this.state.connection
+      .prepare(
+        `SELECT run_seq AS runSeq, event_type AS eventType, node_id AS nodeId,
+                attempt_id AS attemptId, turn_id AS turnId, message_id AS messageId,
+                tool_call_id AS toolCallId, payload_hash AS payloadHash,
+                recorded_at AS recordedAt
+         FROM session_events
+         WHERE run_id = ? AND run_seq > ? AND run_seq < ?
+         ORDER BY run_seq`,
+      )
+      .all(runId, afterSequence, beforeSequence)
+      .map((value) => {
+        if (!isViewerSessionEventRow(value)) {
+          throw new Error(`Viewer session event row is invalid for ${runId}`);
+        }
+        const payload = this.state.readJson(value.payloadHash);
+        if (!isRecord(payload)) {
+          throw new Error(`Viewer session event payload is invalid for ${runId}`);
+        }
+        return {
+          seq: value.runSeq,
+          at: new Date(value.recordedAt).toISOString(),
+          nodeId: value.nodeId,
+          attemptId: value.attemptId,
+          type: assertSessionEventType(value.eventType),
+          payload,
+          ...(value.turnId === null ? {} : { turnId: value.turnId }),
+          ...(value.messageId === null ? {} : { messageId: value.messageId }),
+          ...(value.toolCallId === null ? {} : { toolCallId: value.toolCallId }),
+        };
+      });
+  }
+
+  private viewerSessionCapture(runId: string): WorkflowSessionCapture {
+    const segments = this.segmentRows(runId);
+    let status: WorkflowSessionCapture["status"] = "complete";
+    let failure: WorkflowSessionCapture["failure"];
+    let entryCount = 0;
+    let eventCount = 0;
+    for (const segment of segments) {
+      entryCount += segment.entryCount;
+      eventCount += segment.eventCount;
+      if (segment.status === "failed") {
+        status = "failed";
+        if (failure === undefined && segment.failureHash !== null) {
+          const value = this.state.readJson(segment.failureHash);
+          if (
+            !isRecord(value) ||
+            typeof value.failedAt !== "string" ||
+            typeof value.code !== "string" ||
+            typeof value.message !== "string"
+          ) {
+            throw new Error(`Session capture failure is invalid for ${runId}`);
+          }
+          failure = {
+            failedAt: value.failedAt,
+            code: value.code,
+            message: value.message,
+          };
+        }
+      } else if (segment.status === "recording" && status !== "failed") {
+        status = "recording";
+      }
+    }
+    return {
+      schema: SESSION_CAPTURE_SCHEMA,
+      eventSchema: SESSION_EVENT_SCHEMA,
+      status,
+      eventCount,
+      entryCount,
+      lastEventSeq: eventCount,
+      ...(failure === undefined ? {} : { failure }),
+    };
+  }
+
   async writeSessionCapture(
     runId: string,
     capture: WorkflowSessionCapture,
@@ -1461,6 +2232,25 @@ export class WorkflowRunStore {
         payloadHash,
         now,
       );
+      const viewerCapture = this.viewerSessionCapture(runId);
+      recordViewerDeltas(
+        this.state,
+        runId,
+        [
+          {
+            targetType: "conversation",
+            targetKey: "capture",
+            patch: [
+              {
+                op: "add",
+                path: "/capture",
+                value: parseJson(canonicalJson(viewerCapture)),
+              },
+            ],
+          },
+        ],
+        now,
+      );
     });
   }
 
@@ -1576,12 +2366,6 @@ export class WorkflowRunStore {
   }
 
   private assertWriteAuthority(run: RunRow, expectedRevision: number): void {
-    const actualRevision = this.requireResourceRevision(run.resourceId);
-    if (actualRevision !== expectedRevision) {
-      throw new Error(
-        `Workflow run revision conflict: expected ${expectedRevision}, got ${actualRevision}`,
-      );
-    }
     const lease = this.state.connection
       .prepare(
         `SELECT generation, owner_type AS ownerType, owner_id AS ownerId,
@@ -1591,19 +2375,56 @@ export class WorkflowRunStore {
       .get(run.resourceId);
     /* istanbul ignore if -- exact schema and internal query shape */
     if (!isLeaseAuthorityRow(lease)) throw new Error("Workflow run lease is missing");
-    if (lease.ownerId === null) return;
-    const authority = this.authorityProvider?.(run.runId);
-    if (
-      authority === undefined ||
-      authority.ownerType !== lease.ownerType ||
-      authority.ownerId !== lease.ownerId ||
-      authority.generation !== lease.generation ||
-      lease.tokenHash === null ||
-      !lease.tokenHash.equals(tokenHash(authority.token)) ||
-      lease.expiresAt === null ||
-      lease.expiresAt <= Date.now()
-    ) {
-      throw new Error("Workflow run write rejected because ownership changed");
+
+    if (lease.ownerId !== null || this.authorityProvider !== undefined) {
+      const authority = this.authorityProvider?.(run.runId);
+      if (authority === undefined) {
+        throw new ClaimLostError(run.runId, "missingAuthority");
+      }
+      const now = Date.now();
+      if (lease.expiresAt === null || lease.expiresAt <= now) {
+        throw new ClaimLostError(run.runId, "expired");
+      }
+      if (authority.ownerType !== lease.ownerType || authority.ownerId !== lease.ownerId) {
+        throw new ClaimLostError(run.runId, "ownerChanged");
+      }
+      if (lease.tokenHash === null || !lease.tokenHash.equals(tokenHash(authority.token))) {
+        throw new ClaimLostError(run.runId, "tokenChanged");
+      }
+      if (authority.generation !== lease.generation) {
+        throw new ClaimLostError(run.runId, "generationChanged");
+      }
+      const leaseMs = authority.leaseMs ?? 30_000;
+      if (!Number.isInteger(leaseMs) || leaseMs <= 0) {
+        throw new Error("Workflow run authority lease duration must be a positive integer");
+      }
+      const renewal = this.state.connection
+        .prepare(
+          `UPDATE leases SET heartbeat_at = ?, expires_at = ?
+           WHERE resource_id = ? AND owner_type = ? AND owner_id = ?
+             AND token_hash = ? AND generation = ? AND expires_at > ?`,
+        )
+        .run(
+          now,
+          now + leaseMs,
+          run.resourceId,
+          authority.ownerType,
+          authority.ownerId,
+          tokenHash(authority.token),
+          authority.generation,
+          now,
+        );
+      /* istanbul ignore if -- BEGIN IMMEDIATE keeps the checked lease stable */
+      if (renewal.changes !== 1) {
+        throw new ClaimLostError(run.runId, "expired");
+      }
+    }
+
+    const actualRevision = this.requireResourceRevision(run.resourceId);
+    if (actualRevision !== expectedRevision) {
+      throw new Error(
+        `Workflow run revision conflict: expected ${expectedRevision}, got ${actualRevision}`,
+      );
     }
   }
 
@@ -1708,6 +2529,77 @@ export class WorkflowRunStore {
     );
   }
 
+  private viewerInspectorTargets(runId: string): ViewerDeltaDraft[] {
+    const settings = this.state.connection
+      .prepare(
+        `SELECT s.scope_id AS scopeId, s.resource_id AS resourceId,
+                s.origin_run_id AS originRunId, s.active_run_id AS activeRunId,
+                s.mount_path AS mountPath, s.invocation,
+                s.current_hash AS currentHash, r.revision,
+                s.created_at AS createdAt, s.updated_at AS updatedAt
+         FROM workflow_settings s
+         JOIN resources r ON r.resource_id = s.resource_id
+         WHERE s.active_run_id = ?
+         ORDER BY s.mount_path, s.invocation`,
+      )
+      .all(runId)
+      .filter(isSettingsScopeRow)
+      .map((row) => ({
+        scopeId: row.scopeId,
+        mountPath: row.mountPath,
+        invocation: row.invocation,
+        changeNumber: row.revision,
+        settingsHash: row.currentHash.toString("hex"),
+      }));
+    const settingsStart = Math.max(0, settings.length - VIEWER_PAGE_SIZE);
+    const followUps = this.state.connection
+      .prepare(`${FOLLOW_UP_ROW_SELECT} WHERE f.run_id = ? ORDER BY f.order_number`)
+      .all(runId)
+      .filter(isFollowUpRow)
+      .map((row) => ({
+        followUpId: row.followUpId,
+        order: row.orderNumber,
+        state: row.status,
+        source: row.sourceType,
+        sessionEntryId: row.sessionEntryId,
+      }));
+    const followUpStart = Math.max(0, followUps.length - VIEWER_PAGE_SIZE);
+    const queue = this.requireFollowUpQueueRow(runId);
+    return [
+      {
+        targetType: "inspector",
+        targetKey: "settings",
+        patch: [
+          {
+            op: "replace",
+            path: "/settingsScopes",
+            value: parseJson(canonicalJson(settings.slice(settingsStart))),
+          },
+          { op: "replace", path: "/settingsStart", value: settingsStart },
+          { op: "replace", path: "/settingsTotal", value: settings.length },
+        ],
+      },
+      {
+        targetType: "inspector",
+        targetKey: "follow-ups",
+        patch: [
+          {
+            op: "replace",
+            path: "/followUpQueue",
+            value: parseJson(
+              canonicalJson({
+                presentationState: queue.presentationState,
+                items: followUps.slice(followUpStart),
+              }),
+            ),
+          },
+          { op: "replace", path: "/followUpStart", value: followUpStart },
+          { op: "replace", path: "/followUpTotal", value: followUps.length },
+        ],
+      },
+    ];
+  }
+
   private initializeRunSettingsAndFollowUps(
     state: WorkflowRunState,
     initialSettings: InitialWorkflowSettingsScope[],
@@ -2207,6 +3099,20 @@ export class WorkflowRunStore {
     }
     if (state.currentAttemptId !== undefined && state.currentNode !== undefined) {
       this.ensureAttempt(state, state.currentNode, state.currentAttemptId, now, snapshot);
+      if (state.currentNodeDeadlineAt !== undefined) {
+        const deadlineAt =
+          state.currentNodeDeadlineAt === null ? null : Date.parse(state.currentNodeDeadlineAt);
+        if (deadlineAt !== null && !Number.isFinite(deadlineAt)) {
+          throw new Error("Workflow node deadline is invalid");
+        }
+        this.state.connection
+          .prepare(
+            `UPDATE node_attempts SET deadline_at = ?, updated_at = ?
+             WHERE attempt_id = ? AND run_id = ?
+               AND status IN ('pending', 'running', 'waiting', 'interrupted')`,
+          )
+          .run(deadlineAt, now, state.currentAttemptId, state.runId);
+      }
     }
     this.syncRunSteps(state, now);
   }
@@ -2550,6 +3456,14 @@ export class WorkflowRunStore {
       ...(activeAttempt?.startedAt === null || activeAttempt === undefined
         ? {}
         : { currentNodeStartedAt: new Date(activeAttempt.startedAt).toISOString() }),
+      ...(activeAttempt === undefined
+        ? {}
+        : {
+            currentNodeDeadlineAt:
+              activeAttempt.deadlineAt === null
+                ? null
+                : new Date(activeAttempt.deadlineAt).toISOString(),
+          }),
       ...savedCurrentSettingsBinding(
         activeAttempt?.settingsScopeId ?? null,
         activeAttempt?.settingsChangeNumber ?? null,
@@ -2700,6 +3614,7 @@ export class WorkflowRunStore {
         attemptId: string;
         nodeId: string;
         startedAt: number | null;
+        deadlineAt: number | null;
         settingsScopeId: string | null;
         settingsChangeNumber: number | null;
         settingsHash: Buffer | null;
@@ -2708,7 +3623,7 @@ export class WorkflowRunStore {
     const row = this.state.connection
       .prepare(
         `SELECT attempt_id AS attemptId, node_id AS nodeId, started_at AS startedAt,
-                settings_scope_id AS settingsScopeId,
+                deadline_at AS deadlineAt, settings_scope_id AS settingsScopeId,
                 settings_change_number AS settingsChangeNumber,
                 settings_hash AS settingsHash
          FROM node_attempts
@@ -2987,11 +3902,159 @@ export class WorkflowRunStore {
           payloadHash,
           now,
         );
+        const viewerCapture = this.viewerSessionCapture(runId);
+        recordViewerDeltas(
+          this.state,
+          runId,
+          [
+            {
+              targetType: "conversation",
+              targetKey: "capture",
+              patch: [
+                {
+                  op: "add",
+                  path: "/capture",
+                  value: parseJson(canonicalJson(viewerCapture)),
+                },
+              ],
+            },
+          ],
+          now,
+        );
       });
     }
   }
 }
 
+function runViewerTargets(
+  state: WorkflowRunState,
+  traceEvent: WorkflowTraceEvent,
+): ViewerDeltaDraft[] {
+  const stepTotal = state.steps.length;
+  const stepStart = Math.max(0, stepTotal - VIEWER_PAGE_SIZE);
+  const updateTotal = state.updates?.length ?? 0;
+  const updateStart = Math.max(0, updateTotal - VIEWER_PAGE_SIZE);
+  const compactStep = (step: WorkflowStepRecord) => ({
+    attemptId: step.attemptId,
+    nodeId: step.nodeId,
+    nodeType: step.nodeType,
+    outcome: step.outcome,
+    startedAt: step.startedAt,
+    finishedAt: step.finishedAt,
+    prompt: null,
+    output: null,
+    ...(step.settingsScopeId === undefined ? {} : { settingsScopeId: step.settingsScopeId }),
+    ...(step.settingsChangeNumber === undefined
+      ? {}
+      : { settingsChangeNumber: step.settingsChangeNumber }),
+    ...(step.settingsHash === undefined ? {} : { settingsHash: step.settingsHash }),
+  });
+  const latestStepByNode = new Map<string, WorkflowStepRecord>();
+  for (const step of state.steps) latestStepByNode.set(step.nodeId, step);
+  const graphSteps = state.steps
+    .filter((step) => latestStepByNode.get(step.nodeId) === step)
+    .map(compactStep);
+  const transitions = new Set<string>();
+  for (let index = 1; index < state.steps.length; index += 1) {
+    const previous = state.steps[index - 1];
+    const current = state.steps[index];
+    if (previous !== undefined && current !== undefined) {
+      transitions.add(`${previous.nodeId}->${current.nodeId}`);
+    }
+  }
+  const graphPatch: NonNullable<ViewerDeltaDraft["patch"]> = [
+    { op: "replace", path: "/state/traceSeq", value: state.traceSeq },
+    { op: "replace", path: "/state/updatedAt", value: state.updatedAt },
+    { op: "replace", path: "/state/status", value: state.status },
+    {
+      op: "add",
+      path: "/state/updates",
+      value: parseJson(canonicalJson(state.updates?.slice(updateStart) ?? [])),
+    },
+    { op: "add", path: "/state/finishedAt", value: state.finishedAt ?? null },
+    { op: "add", path: "/state/currentNode", value: state.currentNode ?? null },
+    { op: "add", path: "/state/currentAttemptId", value: state.currentAttemptId ?? null },
+    {
+      op: "add",
+      path: "/state/currentNodeStartedAt",
+      value: state.currentNodeStartedAt ?? null,
+    },
+    {
+      op: "add",
+      path: "/state/currentNodeDeadlineAt",
+      value: state.currentNodeDeadlineAt ?? null,
+    },
+    {
+      op: "add",
+      path: "/state/currentSettingsScopeId",
+      value: state.currentSettingsScopeId ?? null,
+    },
+    {
+      op: "add",
+      path: "/state/currentSettingsChangeNumber",
+      value: state.currentSettingsChangeNumber ?? null,
+    },
+    {
+      op: "add",
+      path: "/state/currentSettingsHash",
+      value: state.currentSettingsHash ?? null,
+    },
+    { op: "add", path: "/state/statusDetail", value: state.statusDetail ?? null },
+    { op: "add", path: "/state/paused", value: state.paused ?? false },
+    { op: "add", path: "/state/waitingOn", value: state.waitingOn ?? null },
+    {
+      op: "add",
+      path: "/state/humanDecision",
+      value: parseJson(canonicalJson(state.humanDecision ?? null)),
+    },
+    {
+      op: "replace",
+      path: "/graphSteps",
+      value: parseJson(canonicalJson(graphSteps)),
+    },
+    {
+      op: "replace",
+      path: "/takenTransitions",
+      value: [...transitions].sort(),
+    },
+    { op: "replace", path: "/graphCursor", value: Math.max(0, stepTotal - 1) },
+    { op: "replace", path: "/stepStart", value: stepStart },
+    { op: "replace", path: "/stepTotal", value: stepTotal },
+    { op: "replace", path: "/updateStart", value: updateStart },
+    { op: "replace", path: "/updateTotal", value: updateTotal },
+    { op: "replace", path: "/manifest/status", value: state.status },
+    { op: "add", path: "/manifest/finishedAt", value: state.finishedAt ?? null },
+    {
+      op: "replace",
+      path: "/live",
+      value: state.status === "running" || state.status === "waiting",
+    },
+  ];
+  const targets: ViewerDeltaDraft[] = [
+    { targetType: "graph", patch: graphPatch },
+    {
+      targetType: "timeline",
+      targetKey: "trace:tail",
+      patch: viewerTailPatch(traceEvent.seq - 1, [
+        parseJson(
+          canonicalJson({
+            ...traceEvent,
+            payload: compactTracePayload(traceEvent.type, traceEvent.payload),
+          }),
+        ),
+      ]),
+    },
+  ];
+  if (traceEvent.type === "node_finished" || traceEvent.type === "node_failed") {
+    targets.push({
+      targetType: "replay",
+      targetKey: "steps:reload",
+      patch: [{ op: "replace", path: "/stepTotal", value: stepTotal }],
+    });
+  }
+  return targets;
+}
+
 export function readWorkflowRun(
   runId: string,
   options: ReadWorkflowRunOptions & { databasePath?: string } = {},
@@ -3265,6 +4328,21 @@ function emptySegment(): SessionCaptureSegment {
   };
 }
 
+function assertSessionEventType(value: string): WorkflowSessionEventType {
+  switch (value) {
+    case "turn_started":
+    case "turn_finished":
+    case "message_started":
+    case "assistant_event":
+    case "message_finished":
+    case "tool_execution_started":
+    case "tool_execution_finished":
+      return value;
+    default:
+      throw new Error(`Unknown session event type: ${value}`);
+  }
+}
+
 function validateSessionEventRecord(record: WorkflowSessionEventRecord): void {
   if (!Number.isSafeInteger(record.seq) || record.seq < 1) {
     throw new Error("Session event seq must be a positive safe integer");
@@ -3473,6 +4551,10 @@ function isCountRow(value: unknown): value is { count: number } {
   return isRecord(value) && typeof value.count === "number";
 }
 
+function isStepIndexRow(value: unknown): value is { stepIndex: number } {
+  return isRecord(value) && typeof value.stepIndex === "number";
+}
+
 function isLeaseExpiryRow(value: unknown): value is { expiresAt: number | null } {
   return isRecord(value) && (typeof value.expiresAt === "number" || value.expiresAt === null);
 }
@@ -3481,6 +4563,52 @@ function isNextOrderRow(value: unknown): value is { nextOrder: number } {
   return isRecord(value) && typeof value.nextOrder === "number";
 }
 
+function isViewerSessionCheckpointRow(value: unknown): value is ViewerSessionCheckpointRow {
+  return isRecord(value) && typeof value.eventSeq === "number" && Buffer.isBuffer(value.stateHash);
+}
+
+function isViewerSessionEventRow(value: unknown): value is ViewerSessionEventRow {
+  return (
+    isRecord(value) &&
+    typeof value.runSeq === "number" &&
+    typeof value.eventType === "string" &&
+    typeof value.nodeId === "string" &&
+    typeof value.attemptId === "string" &&
+    (typeof value.turnId === "string" || value.turnId === null) &&
+    (typeof value.messageId === "string" || value.messageId === null) &&
+    (typeof value.toolCallId === "string" || value.toolCallId === null) &&
+    Buffer.isBuffer(value.payloadHash) &&
+    typeof value.recordedAt === "number"
+  );
+}
+
+function isTemporalSessionState(value: unknown): value is TemporalSessionState {
+  return (
+    isRecord(value) &&
+    typeof value.throughSeq === "number" &&
+    Array.isArray(value.messages) &&
+    Array.isArray(value.tools) &&
+    Array.isArray(value.settledEntryIds) &&
+    value.settledEntryIds.every((item) => typeof item === "string") &&
+    Array.isArray(value.diagnostics) &&
+    value.diagnostics.every((item) => typeof item === "string")
+  );
+}
+
+function boundedTemporalCheckpoint(state: TemporalSessionState): TemporalSessionState {
+  const messages = state.messages.filter((message) => message.status === "streaming");
+  const activeMessages = new Set(messages.map((message) => message.messageId));
+  return {
+    ...state,
+    messages,
+    tools: state.tools.filter(
+      (tool) => tool.status === "running" && activeMessages.has(tool.messageId),
+    ),
+    settledEntryIds: [],
+    diagnostics: ["earlier session messages are outside this page"],
+  };
+}
+
 function assertValidRunId(runId: string): void {
   if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/.test(runId)) {
     throw new Error(`Invalid workflow run id: ${JSON.stringify(runId)}`);
@@ -3569,6 +4697,7 @@ function isActiveAttemptRow(value: unknown): value is {
   attemptId: string;
   nodeId: string;
   startedAt: number | null;
+  deadlineAt: number | null;
   settingsScopeId: string | null;
   settingsChangeNumber: number | null;
   settingsHash: Buffer | null;
@@ -3635,6 +4764,79 @@ function isLeaseAuthorityRow(value: unknown): value is {
   return isRecord(value);
 }
 
+type ApplyingEffectRow = {
+  effectId: string;
+  resourceId: string;
+  payloadHash: Buffer;
+  attemptCount: number;
+};
+
+type WorkflowEffectRow = {
+  status: "pending" | "applying" | "applied" | "rejected" | "ambiguous" | "cancelled";
+  payloadHash: Buffer;
+  resultHash: Buffer | null;
+  attemptCount: number;
+};
+
+function isApplyingEffectRow(value: unknown): value is ApplyingEffectRow {
+  return (
+    isRecord(value) &&
+    typeof value.effectId === "string" &&
+    typeof value.resourceId === "string" &&
+    Buffer.isBuffer(value.payloadHash) &&
+    typeof value.attemptCount === "number"
+  );
+}
+
+function effectRecoveryFromPayload(value: JsonValue): WorkflowEffectRecovery {
+  return typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    value.recovery === "idempotent"
+    ? "idempotent"
+    : "manual";
+}
+
+function isWorkflowEffectRow(value: unknown): value is WorkflowEffectRow {
+  return (
+    isRecord(value) &&
+    typeof value.status === "string" &&
+    Buffer.isBuffer(value.payloadHash) &&
+    (value.resultHash === null || Buffer.isBuffer(value.resultHash)) &&
+    typeof value.attemptCount === "number"
+  );
+}
+
+function isWorkflowEffectIdentityRow(
+  value: unknown,
+): value is { resourceId: string; status: string } {
+  return (
+    isRecord(value) && typeof value.resourceId === "string" && typeof value.status === "string"
+  );
+}
+
+function isResourceIdRow(value: unknown): value is { resourceId: string } {
+  return isRecord(value) && typeof value.resourceId === "string";
+}
+
+function workflowEffectId(
+  sourceResourceId: string,
+  effectType: string,
+  idempotencyKey: string,
+): string {
+  const digest = createHash("sha256")
+    .update(`${sourceResourceId}\0${effectType}\0${idempotencyKey}`)
+    .digest("hex")
+    .slice(0, 40);
+  return `effect-${digest}`;
+}
+
+function requireBoundedEffectText(value: string, label: string): void {
+  if (typeof value !== "string" || value.length === 0 || value.length > 256) {
+    throw new Error(`Managed effect ${label} must be nonempty text of at most 256 characters`);
+  }
+}
+
 export function createDefinitionSnapshot(workflow: WorkflowDefinition): WorkflowDefinitionSnapshot {
   const metadata = compositionMetadata(workflow);
   const composition = metadata?.snapshot;
@@ -3718,7 +4920,13 @@ function snapshotNode(
       ...(typeof node.humanDecision.onTimeout === "function" ? { dynamicTimeout: true } : {}),
     };
   }
-  if (node.nodeType === "action") common.actionExecution = "exec" in node ? "shell" : "function";
+  if (node.nodeType === "action") {
+    common.actionExecution = "exec" in node ? "shell" : "function";
+    /* istanbul ignore else -- validated action nodes always declare a managed effect */
+    if (node.effect !== undefined) {
+      common.effect = { type: node.effect.type, recovery: node.effect.recovery };
+    }
+  }
   return common;
 }