@osolmaz/pi-workflows 0.13.4 → 0.15.0

package/dist/workflows/store.js

@@ -1,9 +1,13 @@
 import { createHash, randomUUID } from "node:crypto";
 import { StateDatabase, workflowStatePath } from "../state/database.js";
-import { canonicalJson } from "../state/json.js";
+import { canonicalJson, parseJson } from "../state/json.js";
 import { StateMutationStore, StaleResourceError, resourceIdFor, tokenHash, } from "../state/mutation.js";
+import { initializeViewerRun, recordViewerDeltas, viewerTailPatch, VIEWER_PAGE_SIZE, } 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, } from "./session-reducer.js";
 import { applyWorkflowSettingsPatch, workflowSettingsScopeId, } from "./settings.js";
 import { MAX_CURRENT_UPDATES, createUpdateId, updateProjection } from "./updates.js";
 export const RUN_STATE_SCHEMA = "pi-workflows.run-state.v1";
@@ -35,11 +39,13 @@ export class WorkflowRunStore {
     databasePath;
     state;
     authorityProvider;
+    snapshotLifecycle;
     contexts = new Map();
     ownsState;
     mutations;
     constructor(databasePath = workflowStatePath(), options = {}) {
         this.authorityProvider = options.authorityProvider;
+        this.snapshotLifecycle = options.snapshotLifecycle;
         this.ownsState = options.state === undefined;
         this.state =
             options.state ??
@@ -55,7 +61,195 @@ export class WorkflowRunStore {
         if (this.ownsState)
             this.state.close();
     }
+    /** Host-only synchronization after a queue lifecycle mutation on the run resource. */
+    synchronizeRevision(runId) {
+        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) {
+        return await new HumanDecisionStore(this.databasePath, { state: this.state }).createRequest(request);
+    }
+    async readResolvedHumanDecision(decisionId) {
+        return await new HumanDecisionStore(this.databasePath, { state: this.state }).readResolved(decisionId);
+    }
+    async reserveEffect(options) {
+        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) {
+        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) {
+        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";
+        }));
+    }
+    beginEffectAttempt(run, effectId, attemptNumber, authority) {
+        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" };
+    }
+    insertEffectAttempt(effectId, attemptNumber, authority, now) {
+        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, state, options = {}) {
+        return await this.initializeRunFromSnapshot(createDefinitionSnapshot(workflow), workflow.name, state, options);
+    }
+    async initializeRunFromSnapshot(snapshot, workflowName, state, options = {}) {
         assertValidRunId(state.runId);
         if (!this.contexts.has(state.runId)) {
             const reserved = this.readRunRow(state.runId);
@@ -68,7 +262,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);
@@ -89,14 +282,23 @@ export class WorkflowRunStore {
                     acceptedRevision = revision;
                     state.traceSeq = revision;
                     state.updatedAt = at;
-                    insertRunEvent(this.state, reserved.resourceId, revision, at, {
+                    const traceEvent = {
+                        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;
@@ -107,7 +309,7 @@ export class WorkflowRunStore {
                definition_digest, workflow_name, definition_hash, created_at
              ) 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(
                resource_id, resource_type, aggregate_key, revision, created_at, updated_at
@@ -130,14 +332,18 @@ export class WorkflowRunStore {
                created_at, updated_at, finished_at
              ) VALUES (?, ?, NULL, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
                     .run(state.runId, resourceId, state.parentRunId ?? null, definitionDigest, state.workflowName, launchOptionsHash, state.runTitle ?? null, state.status, state.paused === true ? 1 : 0, state.statusDetail ?? null, inputHash, finalOutputHash, errorHash, Date.parse(state.startedAt), 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() });
@@ -165,6 +371,7 @@ export class WorkflowRunStore {
              initial_hash, current_hash, created_at, updated_at
            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
                 .run(scopeId, resourceId, originRunId, options.runId, options.mountPath, options.invocation, settingsHash, settingsHash, now, now);
+            recordViewerDeltas(this.state, options.runId, this.viewerInspectorTargets(options.runId), now);
             return this.settingsScopeRecord(this.requireSettingsScopeRow(scopeId));
         });
     }
@@ -295,6 +502,7 @@ export class WorkflowRunStore {
                     database.connection
                         .prepare(`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;
                 }, {
                     payload: {
@@ -371,6 +579,7 @@ export class WorkflowRunStore {
                    created_at, updated_at
                  ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'queued', ?, ?)`)
                         .run(followUpId, resourceId, queue.resourceId, request.runId, request.requestId, order, request.targetSessionId, request.actor.type, request.actor.id ?? null, request.source, promptHash, now, now);
+                    recordViewerDeltas(this.state, request.runId, this.viewerInspectorTargets(request.runId), now);
                     return followUpId;
                 }, { payload: { runId: request.runId, requestId: request.requestId } });
                 return {
@@ -416,6 +625,7 @@ 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 } });
         return this.followUpRecord(this.requireFollowUpRow(request.followUpId));
     }
@@ -503,6 +713,7 @@ export class WorkflowRunStore {
                     .prepare(`UPDATE workflow_follow_ups SET status = 'ready', updated_at = ?
              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 } });
         }
         catch (error) {
@@ -569,6 +780,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 } });
         return this.followUpRecord(this.requireFollowUpRow(followUpId));
     }
@@ -599,14 +811,19 @@ export class WorkflowRunStore {
            SET status = 'interrupted', updated_at = ?
            WHERE run_id = ? AND status IN ('pending', 'running', 'waiting')`)
                 .run(now, runId);
-            insertRunEvent(this.state, row.resourceId, nextRevision, at, {
+            const traceEvent = {
+                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 });
@@ -625,6 +842,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;
@@ -638,68 +856,72 @@ export class WorkflowRunStore {
         return this.readRun(runId, { includeTrace: true });
     }
     async publishUpdate(runId, state, nodeId, attemptId, update, options = {}) {
-        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);
-            const updateId = createUpdateId();
-            let acceptedEvent;
-            let acceptedRecord;
-            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 = {
-                    seq: revision,
-                    at,
-                    runId,
-                    scope: "node",
-                    type: "update_published",
-                    nodeId,
-                    attemptId,
-                    payload: { updateId, type: update.type, key: update.key, data },
-                };
-                const record = {
-                    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, state, nodeId, attemptId, update, options = {}) {
+        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);
+        const updateId = createUpdateId();
+        let acceptedEvent;
+        let acceptedRecord;
+        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 = {
+                seq: revision,
+                at,
+                runId,
+                scope: "node",
+                type: "update_published",
+                nodeId,
+                attemptId,
+                payload: { updateId, type: update.type, key: update.key, data },
+            };
+            const record = {
+                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(runId, state, event) {
         return await this.withRunLock(runId, async () => {
@@ -720,6 +942,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;
             });
@@ -747,6 +977,7 @@ export class WorkflowRunStore {
             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);
@@ -781,7 +1012,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 = {
                     seq: revision,
                     at,
                     runId,
@@ -791,11 +1022,34 @@ 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;
             });
         });
@@ -806,18 +1060,51 @@ 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 (?, ?, ?, ?, ?)`)
-                .run(segment.segmentId, sequence, entryId, entryHash, now);
+                .prepare(`INSERT INTO session_entries(
+             segment_id, run_id, entry_seq, run_seq, entry_id, entry_hash, recorded_at
+           ) VALUES (?, ?, ?, ?, ?, ?, ?)`)
+                .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);
             this.bumpResource(segmentResourceId(segment), revision, now);
             insertGenericEvent(this.state, segmentResourceId(segment), revision + 1, "session.entry_appended", "session", segment.sessionId, 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;
         });
     }
@@ -831,6 +1118,16 @@ export class WorkflowRunStore {
             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 = [];
             for (const record of records) {
                 validateSessionEventRecord(record);
                 if (record.seq !== expected) {
@@ -842,17 +1139,166 @@ export class WorkflowRunStore {
                 const payloadHash = this.state.putJson(record.payload, Date.parse(record.at));
                 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 (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
-                    .run(current.segmentId, record.seq, record.type, record.nodeId, record.attemptId, record.turnId ?? null, record.messageId ?? null, record.toolCallId ?? null, payloadHash, Date.parse(record.at));
+             ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                    .run(current.segmentId, runId, record.seq, runSequence, record.type, record.nodeId, record.attemptId, record.turnId ?? null, record.messageId ?? null, record.toolCallId ?? null, 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);
         });
     }
+    recordSessionReplayCheckpoints(runId, firstRunSequence, newRecords, now) {
+        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;
+        }
+    }
+    sessionEventRecords(runId, afterSequence, beforeSequence) {
+        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 }),
+            };
+        });
+    }
+    viewerSessionCapture(runId) {
+        const segments = this.segmentRows(runId);
+        let status = "complete";
+        let 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, capture, attemptId) {
         validateSessionCapture(capture);
         const segment = this.requireSegment(segmentIdFor(runId, attemptId));
@@ -875,6 +1321,20 @@ export class WorkflowRunStore {
             this.bumpResource(resourceId, revision, now);
             const payloadHash = this.state.putJson(capture, now);
             insertGenericEvent(this.state, resourceId, revision + 1, "session.capture_updated", "session", segment.sessionId, 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);
         });
     }
     async sessionCounts(runId, attemptId) {
@@ -982,10 +1442,6 @@ export class WorkflowRunStore {
             throw new Error("Resource revision conflict");
     }
     assertWriteAuthority(run, expectedRevision) {
-        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,
                 token_hash AS tokenHash, expires_at AS expiresAt
@@ -994,18 +1450,41 @@ export class WorkflowRunStore {
         /* 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}`);
         }
     }
     persistRunState(run, state, expectedRevision, now) {
@@ -1058,6 +1537,72 @@ export class WorkflowRunStore {
             .run(effectId, effectResourceId, runResourceId, sourceRevision, effectType, idempotencyKey, payloadHash, now, now);
         insertGenericEvent(this.state, effectResourceId, 1, "effect.created", "system", null, payloadHash, now);
     }
+    viewerInspectorTargets(runId) {
+        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 },
+                ],
+            },
+        ];
+    }
     initializeRunSettingsAndFollowUps(state, initialSettings, now) {
         const childQueueResourceId = this.ensureFollowUpQueue(state.runId, now);
         if (state.parentRunId !== undefined) {
@@ -1424,6 +1969,17 @@ 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);
     }
@@ -1686,6 +2242,13 @@ 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, activeAttempt?.settingsHash ?? null),
             ...(row.statusDetail === null ? {} : { statusDetail: row.statusDetail }),
             ...(humanDecision === undefined ? {} : { humanDecision }),
@@ -1803,7 +2366,7 @@ export class WorkflowRunStore {
     readActiveAttempt(runId) {
         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
@@ -2046,10 +2609,148 @@ export class WorkflowRunStore {
                 this.bumpResource(resourceId, revision, now);
                 const payloadHash = this.state.putJson(capture, now);
                 insertGenericEvent(this.state, resourceId, revision + 1, "session.capture_failed", "system", null, 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, traceEvent) {
+    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) => ({
+        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();
+    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();
+    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 = [
+        { 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 = [
+        { 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, options = {}) {
     const store = new WorkflowRunStore(options.databasePath ?? workflowStatePath(), {
         readOnly: true,
@@ -2249,6 +2950,20 @@ function emptySegment() {
         integrity: { status: "unavailable", diagnostics: [] },
     };
 }
+function assertSessionEventType(value) {
+    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) {
     if (!Number.isSafeInteger(record.seq) || record.seq < 1) {
         throw new Error("Session event seq must be a positive safe integer");
@@ -2416,12 +3131,51 @@ function isStatusRow(value) {
 function isCountRow(value) {
     return isRecord(value) && typeof value.count === "number";
 }
+function isStepIndexRow(value) {
+    return isRecord(value) && typeof value.stepIndex === "number";
+}
 function isLeaseExpiryRow(value) {
     return isRecord(value) && (typeof value.expiresAt === "number" || value.expiresAt === null);
 }
 function isNextOrderRow(value) {
     return isRecord(value) && typeof value.nextOrder === "number";
 }
+function isViewerSessionCheckpointRow(value) {
+    return isRecord(value) && typeof value.eventSeq === "number" && Buffer.isBuffer(value.stateHash);
+}
+function isViewerSessionEventRow(value) {
+    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) {
+    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) {
+    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) {
     if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/.test(runId)) {
         throw new Error(`Invalid workflow run id: ${JSON.stringify(runId)}`);
@@ -2514,6 +3268,46 @@ function isSessionEventRow(value) {
 function isLeaseAuthorityRow(value) {
     return isRecord(value);
 }
+function isApplyingEffectRow(value) {
+    return (isRecord(value) &&
+        typeof value.effectId === "string" &&
+        typeof value.resourceId === "string" &&
+        Buffer.isBuffer(value.payloadHash) &&
+        typeof value.attemptCount === "number");
+}
+function effectRecoveryFromPayload(value) {
+    return typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        value.recovery === "idempotent"
+        ? "idempotent"
+        : "manual";
+}
+function isWorkflowEffectRow(value) {
+    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) {
+    return (isRecord(value) && typeof value.resourceId === "string" && typeof value.status === "string");
+}
+function isResourceIdRow(value) {
+    return isRecord(value) && typeof value.resourceId === "string";
+}
+function workflowEffectId(sourceResourceId, effectType, idempotencyKey) {
+    const digest = createHash("sha256")
+        .update(`${sourceResourceId}\0${effectType}\0${idempotencyKey}`)
+        .digest("hex")
+        .slice(0, 40);
+    return `effect-${digest}`;
+}
+function requireBoundedEffectText(value, label) {
+    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) {
     const metadata = compositionMetadata(workflow);
     const composition = metadata?.snapshot;
@@ -2590,8 +3384,13 @@ function snapshotNode(workflow, nodeId, node) {
             ...(typeof node.humanDecision.onTimeout === "function" ? { dynamicTimeout: true } : {}),
         };
     }
-    if (node.nodeType === "action")
+    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;
 }
 function snapshotSettings(settings) {