@osolmaz/pi-workflows 0.13.1 → 0.13.3

package/src/workflows/store.ts

@@ -1,18 +1,50 @@
 import { createHash, randomUUID } from "node:crypto";
 import { StateDatabase, workflowStatePath } from "../state/database.js";
-import { canonicalJson } from "../state/json.js";
-import { resourceIdFor, tokenHash, type MutationActor, type OwnerType } from "../state/mutation.js";
+import { canonicalJson, type JsonValue } from "../state/json.js";
+import {
+  StateMutationStore,
+  StaleResourceError,
+  resourceIdFor,
+  tokenHash,
+  type ActorType,
+  type LeaseClaim,
+  type MutationActor,
+  type OwnerType,
+} from "../state/mutation.js";
 import { compositionMetadata } from "./composition.js";
+import { applyJsonPatch, validateJsonPatch } from "./json-patch.js";
+import {
+  applyWorkflowSettingsPatch,
+  workflowSettingsScopeId,
+  type InitialWorkflowSettingsScope,
+  type WorkflowFollowUpQueueRecord,
+  type WorkflowFollowUpRecord,
+  type WorkflowFollowUpState,
+  type WorkflowPresentationState,
+  type WorkflowQueueFollowUpRequest,
+  type WorkflowRemoveFollowUpRequest,
+  type WorkflowSettingsChangeRecord,
+  type WorkflowSettingsChangeRequest,
+  type WorkflowSettingsChangeResult,
+  type WorkflowSettingsDefinition,
+  type WorkflowSettingsScopeRecord,
+} from "./settings.js";
 import type {
   WorkflowDefinition,
   WorkflowDefinitionSnapshot,
+  HumanDecisionReceipt,
   WorkflowNodeDefinition,
+  WorkflowNodeResult,
   WorkflowNodeSnapshot,
   WorkflowRunState,
+  WorkflowSource,
+  WorkflowMountedSource,
+  WorkflowStepRecord,
   WorkflowSessionBinding,
   WorkflowSessionCapture,
   WorkflowSessionEntryRecord,
   WorkflowSessionEventRecord,
+  WorkflowSettingsSnapshot,
   WorkflowTraceEvent,
   WorkflowTraceEventDraft,
   WorkflowUpdateInput,
@@ -27,6 +59,19 @@ export const SESSION_EVENT_SCHEMA = "pi-workflows.session-event.v1" as const;
 export const SESSION_CAPTURE_SCHEMA = "pi-workflows.session-capture.v1" as const;
 export const SESSION_EVENT_MAX_BYTES = 1024 * 1024;
 
+const FOLLOW_UP_ROW_SELECT = `
+  SELECT f.follow_up_id AS followUpId, f.resource_id AS resourceId,
+         f.queue_resource_id AS queueResourceId, f.run_id AS runId,
+         f.request_id AS requestId, f.order_number AS orderNumber,
+         f.target_session_id AS targetSessionId, f.actor_type AS actorType,
+         f.actor_id AS actorId, f.source_type AS sourceType,
+         f.prompt_hash AS promptHash, f.status,
+         f.session_entry_id AS sessionEntryId, f.reason_hash AS reasonHash,
+         f.created_at AS createdAt, f.updated_at AS updatedAt, f.sent_at AS sentAt,
+         r.revision
+  FROM workflow_follow_ups f
+  JOIN resources r ON r.resource_id = f.resource_id`;
+
 export function workflowStateDatabasePath(homeDir?: string): string {
   return workflowStatePath(homeDir);
 }
@@ -58,9 +103,62 @@ type RunContext = {
 type RunRow = {
   runId: string;
   resourceId: string;
-  stateHash: Buffer;
   definitionHash: Buffer;
+  definitionDigest: Buffer;
+  workflowRef: string;
+  parentRunId: string | null;
+  title: string | null;
+  status: string;
+  paused: number;
+  statusDetail: string | null;
+  inputHash: Buffer;
+  finalOutputHash: Buffer | null;
+  errorHash: Buffer | null;
+  createdAt: number;
+  updatedAt: number;
+  finishedAt: number | null;
+};
+
+type RunSourceRow = {
+  mountPath: string;
+  sourceType: "builtin" | "file";
+  sourceRef: string;
+  sourceRevision: string;
+};
+
+type StoredAttemptReceipt = Pick<WorkflowStepRecord, "action" | "assistantMessage">;
+
+type StepRow = {
+  stepIndex: number;
+  attemptId: string;
+  nodeId: string;
+  nodeType: WorkflowStepRecord["nodeType"];
   status: string;
+  promptHash: Buffer | null;
+  outputHash: Buffer | null;
+  outputOverrideHash: Buffer | null;
+  receiptHash: Buffer | null;
+  promptEntryHash: Buffer | null;
+  responseEntryHash: Buffer | null;
+  firstEntryId: string | null;
+  lastEntryId: string | null;
+  errorHash: Buffer | null;
+  settingsScopeId: string | null;
+  settingsChangeNumber: number | null;
+  settingsHash: Buffer | null;
+  startedAt: number;
+  finishedAt: number;
+};
+
+type UpdateRow = {
+  updateId: string;
+  runRevision: number;
+  nodeId: string;
+  attemptId: string;
+  updateType: string;
+  updateKey: string;
+  dataHash: Buffer;
+  recordedAt: number;
 };
 
 type EventRow = {
@@ -70,6 +168,79 @@ type EventRow = {
   recordedAt: number;
 };
 
+type SettingsScopeRow = {
+  scopeId: string;
+  resourceId: string;
+  originRunId: string;
+  activeRunId: string;
+  mountPath: string;
+  invocation: number;
+  currentHash: Buffer;
+  revision: number;
+  createdAt: number;
+  updatedAt: number;
+};
+
+type SettingsProjectionRow = {
+  scopeId: string;
+  initialHash: Buffer;
+  currentHash: Buffer;
+  revision: number;
+};
+
+type SettingsProjectionChangeRow = {
+  changeNumber: number;
+  patchHash: Buffer;
+  beforeHash: Buffer;
+  afterHash: Buffer;
+};
+
+type SettingsChangeRow = {
+  changeId: string;
+  scopeId: string;
+  requestId: string;
+  changeNumber: number;
+  actorType: string;
+  actorId: string | null;
+  sourceType: string;
+  patchHash: Buffer;
+  beforeHash: Buffer;
+  afterHash: Buffer;
+  acceptedAt: number;
+};
+
+type FollowUpQueueRow = {
+  runId: string;
+  resourceId: string;
+  originSessionId: string | null;
+  presentationState: string;
+  presentationEntryId: string | null;
+  presentationAssistantEntryId: string | null;
+  presentationReasonHash: Buffer | null;
+  revision: number;
+};
+
+type FollowUpRow = {
+  followUpId: string;
+  resourceId: string;
+  queueResourceId: string;
+  runId: string;
+  requestId: string;
+  orderNumber: number;
+  targetSessionId: string;
+  actorType: string;
+  actorId: string | null;
+  sourceType: string;
+  promptHash: Buffer;
+  status: string;
+  sessionEntryId: string | null;
+  reasonHash: Buffer | null;
+  createdAt: number;
+  updatedAt: number;
+  sentAt: number | null;
+  revision: number;
+};
+
 type SegmentRow = {
   segmentId: string;
   runId: string;
@@ -128,12 +299,18 @@ export type LoadedWorkflowRun = {
   sessionCapture: WorkflowSessionCapture | null;
   sessionIntegrity: SessionCaptureIntegrity;
   sessionSegments: SessionCaptureSegment[];
+  settingsScopes?: WorkflowSettingsScopeRecord[];
+  followUpQueue?: WorkflowFollowUpQueueRecord | null;
 };
 
 export type ReadWorkflowRunOptions = {
   includeTrace?: boolean;
 };
 
+export type InitializeWorkflowRunOptions = {
+  initialSettings?: InitialWorkflowSettingsScope[];
+};
+
 export class WorkflowRunStore {
   readonly databasePath: string;
   readonly state: StateDatabase;
@@ -142,6 +319,7 @@ export class WorkflowRunStore {
     | undefined;
   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;
@@ -154,13 +332,18 @@ export class WorkflowRunStore {
         checkLegacyState: databasePath === workflowStatePath(),
       });
     this.databasePath = this.state.filePath;
+    this.mutations = new StateMutationStore(this.state);
   }
 
   close(): void {
     if (this.ownsState) this.state.close();
   }
 
-  async initializeRun(workflow: WorkflowDefinition, state: WorkflowRunState): Promise<string> {
+  async initializeRun(
+    workflow: WorkflowDefinition,
+    state: WorkflowRunState,
+    options: InitializeWorkflowRunOptions = {},
+  ): Promise<string> {
     assertValidRunId(state.runId);
     if (!this.contexts.has(state.runId)) {
       const reserved = this.readRunRow(state.runId);
@@ -200,7 +383,9 @@ export class WorkflowRunStore {
             payload: { workflowName: workflow.name },
           });
           this.persistRunState(reserved, state, revision, now);
+          this.initializeRunSettingsAndFollowUps(state, options.initialSettings ?? [], now);
           this.syncNodeAttempts(state, snapshot, now);
+          this.syncContinuationIdentity(state);
           context.revision = revision;
           return;
         }
@@ -226,19 +411,18 @@ export class WorkflowRunStore {
         state.traceSeq = 1;
         state.updatedAt = at;
         const inputHash = this.state.putJson(state.input, now);
-        const workflowSourceHash = this.state.putJson(state.workflowSource ?? source, now);
         const launchOptionsHash = this.state.putJson({}, now);
-        const stateHash = this.state.putJson(state, now);
+        const finalOutputHash =
+          state.finalOutput === undefined ? null : this.state.putJson(state.finalOutput, now);
         const errorHash = state.error === undefined ? null : this.state.putText(state.error, now);
         this.state.connection
           .prepare(
             `INSERT INTO runs(
                run_id, resource_id, project_id, parent_run_id, definition_digest,
-               workflow_ref, workflow_source_hash, launch_options_hash,
-               source_type, source_ref, source_revision, title, status, paused,
-               status_detail, input_hash, output_hash, error_hash,
+               workflow_ref, launch_options_hash, title, status, paused,
+               status_detail, input_hash, final_output_hash, error_hash,
                created_at, updated_at, finished_at
-             ) VALUES (?, ?, NULL, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+             ) VALUES (?, ?, NULL, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
           )
           .run(
             state.runId,
@@ -246,27 +430,26 @@ export class WorkflowRunStore {
             state.parentRunId ?? null,
             definitionDigest,
             state.workflowName,
-            workflowSourceHash,
             launchOptionsHash,
-            source.type,
-            source.ref,
-            source.revision,
             state.runTitle ?? null,
             state.status,
             state.paused === true ? 1 : 0,
             state.statusDetail ?? null,
             inputHash,
-            stateHash,
+            finalOutputHash,
             errorHash,
             Date.parse(state.startedAt),
             now,
             state.finishedAt === undefined ? null : Date.parse(state.finishedAt),
           );
+        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 },
         });
+        this.initializeRunSettingsAndFollowUps(state, options.initialSettings ?? [], now);
         this.syncNodeAttempts(state, snapshot, now);
       });
       this.contexts.set(state.runId, { revision: acceptedRevision, lock: Promise.resolve() });
@@ -274,12 +457,603 @@ export class WorkflowRunStore {
     });
   }
 
+  ensureSettingsScope(options: {
+    runId: string;
+    mountPath: string;
+    invocation: number;
+    settings: JsonValue;
+  }): WorkflowSettingsScopeRecord {
+    const now = Date.now();
+    return this.state.transaction(() => {
+      this.requireRunAcceptsSettings(options.runId, false);
+      const originRunId = this.logicalOriginRunId(options.runId);
+      const scopeId = workflowSettingsScopeId(originRunId, options.mountPath, options.invocation);
+      const existing = this.settingsScopeRow(scopeId);
+      if (existing !== undefined) {
+        if (existing.activeRunId !== options.runId) {
+          throw new Error(`Workflow settings scope belongs to another active run: ${scopeId}`);
+        }
+        return this.settingsScopeRecord(existing);
+      }
+      const resourceId = this.mutations.ensureResource("settings", scopeId, now);
+      const settingsHash = this.state.putJson(options.settings, now);
+      this.state.connection
+        .prepare(
+          `INSERT INTO workflow_settings(
+             scope_id, resource_id, origin_run_id, active_run_id, mount_path, invocation,
+             initial_hash, current_hash, created_at, updated_at
+           ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+        )
+        .run(
+          scopeId,
+          resourceId,
+          originRunId,
+          options.runId,
+          options.mountPath,
+          options.invocation,
+          settingsHash,
+          settingsHash,
+          now,
+          now,
+        );
+      return this.settingsScopeRecord(this.requireSettingsScopeRow(scopeId));
+    });
+  }
+
+  getSettingsScope(scopeId: string): WorkflowSettingsScopeRecord | undefined {
+    const row = this.settingsScopeRow(scopeId);
+    return row === undefined ? undefined : this.settingsScopeRecord(row);
+  }
+
+  getSettingsScopeAtChange(
+    scopeId: string,
+    changeNumber: number,
+  ): WorkflowSettingsScopeRecord | undefined {
+    if (!Number.isInteger(changeNumber) || changeNumber < 0) {
+      throw new Error("Workflow settings change number must be a non-negative integer");
+    }
+    const row = this.settingsScopeRow(scopeId);
+    if (row === undefined) return undefined;
+    if (changeNumber > row.revision) {
+      throw new Error(`Workflow settings change ${changeNumber} does not exist for ${scopeId}`);
+    }
+    if (changeNumber === row.revision) return this.settingsScopeRecord(row);
+    const saved =
+      changeNumber === 0
+        ? this.state.connection
+            .prepare(
+              "SELECT initial_hash AS settingsHash FROM workflow_settings WHERE scope_id = ?",
+            )
+            .get(scopeId)
+        : this.state.connection
+            .prepare(
+              `SELECT after_hash AS settingsHash FROM workflow_setting_changes
+               WHERE scope_id = ? AND change_number = ?`,
+            )
+            .get(scopeId, changeNumber);
+    if (!isRecord(saved) || !Buffer.isBuffer(saved.settingsHash)) {
+      throw new Error(`Workflow settings change ${changeNumber} is missing for ${scopeId}`);
+    }
+    return this.settingsScopeRecord(row, changeNumber, saved.settingsHash);
+  }
+
+  listSettingsScopes(runId: string): WorkflowSettingsScopeRecord[] {
+    return 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) => this.settingsScopeRecord(row));
+  }
+
+  private settingsScopesForRunView(runId: string): WorkflowSettingsScopeRecord[] {
+    const originRunId = this.logicalOriginRunId(runId);
+    return 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.origin_run_id = ? OR s.active_run_id = ?
+         ORDER BY s.mount_path, s.invocation`,
+      )
+      .all(originRunId, runId)
+      .filter(isSettingsScopeRow)
+      .map((row) => this.settingsScopeRecord(row));
+  }
+
+  findSettingsScope(
+    runId: string,
+    mountPath: string,
+    invocation: number,
+  ): WorkflowSettingsScopeRecord | undefined {
+    const row = 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 = ? AND s.mount_path = ? AND s.invocation = ?`,
+      )
+      .get(runId, mountPath, invocation);
+    return isSettingsScopeRow(row) ? this.settingsScopeRecord(row) : undefined;
+  }
+
+  async changeSettings<TSettings, TInput = unknown>(
+    definition: WorkflowSettingsDefinition<TSettings, TInput>,
+    request: WorkflowSettingsChangeRequest,
+  ): Promise<WorkflowSettingsChangeResult> {
+    assertRequestId(request.requestId);
+    assertSourceType(request.source);
+    const patch = validateJsonPatch(request.patch);
+    const patchJson = canonicalJson(patch);
+    const patchDigest = createHash("sha256").update(patchJson).digest();
+    for (let attempt = 0; attempt < 8; attempt += 1) {
+      const prior = this.settingsChangeRow(request.scopeId, request.requestId);
+      if (prior !== undefined) {
+        this.assertSameSettingsChange(prior, request, patchDigest);
+        return {
+          scope: this.settingsScopeRecord(this.requireSettingsScopeRow(request.scopeId)),
+          change: this.settingsChangeRecord(prior),
+          adopted: true,
+        };
+      }
+      const scope = this.requireSettingsScopeRow(request.scopeId);
+      if (scope.activeRunId !== request.runId) {
+        throw new Error(`Workflow settings scope is not active for run ${request.runId}`);
+      }
+      this.requireRunAcceptsSettings(request.runId, true);
+      if (
+        request.expectedChangeNumber !== undefined &&
+        request.expectedChangeNumber !== scope.revision
+      ) {
+        throw new StaleResourceError(
+          `Workflow settings changed: expected ${request.expectedChangeNumber}, current ${scope.revision}`,
+        );
+      }
+      const before = this.state.readJson(scope.currentHash);
+      const applied = await applyWorkflowSettingsPatch(
+        definition,
+        before,
+        patch,
+        request.actor,
+        request.source,
+      );
+      const beforeHash = scope.currentHash;
+      const afterHash = createHash("sha256").update(canonicalJson(applied.json)).digest();
+      try {
+        const mutation = this.mutations.mutate(
+          {
+            resourceId: scope.resourceId,
+            operation: "settings.change",
+            actor: request.actor,
+            expectedRevision: scope.revision,
+          },
+          "settings.changed",
+          ({ database, nextRevision, now }) => {
+            this.requireRunAcceptsSettings(request.runId, true);
+            const current = this.requireSettingsScopeRow(request.scopeId);
+            if (current.activeRunId !== request.runId || !current.currentHash.equals(beforeHash)) {
+              throw new StaleResourceError("Workflow settings changed before the patch committed");
+            }
+            const patchHash = database.putJson(applied.patch, now);
+            const savedAfterHash = database.putJson(applied.json, now);
+            const changeId = `setting-change-${randomUUID()}`;
+            database.connection
+              .prepare(
+                `INSERT INTO workflow_setting_changes(
+                   change_id, scope_id, request_id, change_number,
+                   actor_type, actor_id, source_type, patch_hash,
+                   before_hash, after_hash, accepted_at
+                 ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+              )
+              .run(
+                changeId,
+                request.scopeId,
+                request.requestId,
+                nextRevision,
+                request.actor.type,
+                request.actor.id ?? null,
+                request.source,
+                patchHash,
+                beforeHash,
+                savedAfterHash,
+                now,
+              );
+            database.connection
+              .prepare(
+                `UPDATE workflow_settings SET current_hash = ?, updated_at = ? WHERE scope_id = ?`,
+              )
+              .run(savedAfterHash, now, request.scopeId);
+            return changeId;
+          },
+          {
+            payload: {
+              scopeId: request.scopeId,
+              requestId: request.requestId,
+              source: request.source,
+              beforeHash: beforeHash.toString("hex"),
+              afterHash: afterHash.toString("hex"),
+            },
+          },
+        );
+        const row = this.settingsChangeRow(request.scopeId, request.requestId);
+        if (row === undefined || row.changeId !== mutation.value) {
+          throw new Error("Accepted workflow settings change is missing");
+        }
+        return {
+          scope: this.settingsScopeRecord(this.requireSettingsScopeRow(request.scopeId)),
+          change: this.settingsChangeRecord(row),
+          adopted: false,
+        };
+      } catch (error) {
+        if (!(error instanceof StaleResourceError) || request.expectedChangeNumber !== undefined) {
+          throw error;
+        }
+      }
+    }
+    throw new StaleResourceError("Workflow settings kept changing; retry with an expected number");
+  }
+
+  queueFollowUp(request: WorkflowQueueFollowUpRequest): {
+    followUp: WorkflowFollowUpRecord;
+    adopted: boolean;
+  } {
+    assertRequestId(request.requestId);
+    assertSourceType(request.source);
+    if (typeof request.prompt !== "string" || request.prompt.trim().length === 0) {
+      throw new Error("Workflow follow-up prompt must be a non-empty string");
+    }
+    if (Buffer.byteLength(request.prompt, "utf8") > 64 * 1024) {
+      throw new Error("Workflow follow-up prompt cannot exceed 65536 bytes");
+    }
+    for (let attempt = 0; attempt < 8; attempt += 1) {
+      const prior = this.followUpRowByRequest(request.runId, request.requestId);
+      if (prior !== undefined) {
+        this.assertSameFollowUp(prior, request);
+        return { followUp: this.followUpRecord(prior), adopted: true };
+      }
+      this.requireRunAcceptsSettings(request.runId, true);
+      const queue = this.requireFollowUpQueueRow(request.runId);
+      try {
+        const result = this.mutations.mutate(
+          {
+            resourceId: queue.resourceId,
+            operation: "follow-up.queue",
+            actor: request.actor,
+            expectedRevision: queue.revision,
+          },
+          "follow-up.queued",
+          ({ database, now }) => {
+            this.requireRunAcceptsSettings(request.runId, true);
+            const currentQueue = this.requireFollowUpQueueRow(request.runId);
+            if (
+              currentQueue.originSessionId !== null &&
+              currentQueue.originSessionId !== request.targetSessionId
+            ) {
+              throw new Error("Workflow follow-ups must target the run's origin Pi session");
+            }
+            if (currentQueue.originSessionId === null) {
+              database.connection
+                .prepare(
+                  `UPDATE workflow_follow_up_queues
+                   SET origin_session_id = ?, updated_at = ? WHERE run_id = ?`,
+                )
+                .run(request.targetSessionId, now, request.runId);
+            }
+            const order = this.nextFollowUpOrder(request.runId);
+            const followUpId = followUpIdFor(request.runId, request.requestId);
+            const resourceId = this.mutations.ensureResource("follow_up", followUpId, now);
+            const promptHash = database.putText(request.prompt, now);
+            database.connection
+              .prepare(
+                `INSERT INTO workflow_follow_ups(
+                   follow_up_id, resource_id, queue_resource_id, run_id,
+                   request_id, order_number, target_session_id,
+                   actor_type, actor_id, source_type, prompt_hash, status,
+                   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,
+              );
+            return followUpId;
+          },
+          { payload: { runId: request.runId, requestId: request.requestId } },
+        );
+        return {
+          followUp: this.followUpRecord(this.requireFollowUpRow(result.value)),
+          adopted: false,
+        };
+      } catch (error) {
+        if (!(error instanceof StaleResourceError)) throw error;
+      }
+    }
+    throw new StaleResourceError("Workflow follow-up queue kept changing; retry the request");
+  }
+
+  removeFollowUp(request: WorkflowRemoveFollowUpRequest): WorkflowFollowUpRecord {
+    assertSourceType(request.source);
+    const row = this.requireFollowUpRow(request.followUpId);
+    if (row.runId !== request.runId) {
+      throw new Error(`Workflow follow-up is not part of run ${request.runId}`);
+    }
+    if (row.status === "removed") return this.followUpRecord(row);
+    if (row.status === "sent" || row.status === "cancelled") {
+      throw new Error(`Workflow follow-up cannot be removed after it is ${row.status}`);
+    }
+    this.assertFollowUpRemovalAuthority(row, request.actor, request.source);
+    if (this.hasLiveLease(row.resourceId)) {
+      throw new Error("Workflow follow-up is being delivered and cannot be removed");
+    }
+    const reason = "Removed before delivery";
+    this.mutations.mutate(
+      {
+        resourceId: row.resourceId,
+        operation: "follow-up.remove",
+        actor: request.actor,
+        expectedRevision: row.revision,
+      },
+      "follow-up.removed",
+      ({ database, now }) => {
+        const reasonHash = database.putText(reason, now);
+        const update = database.connection
+          .prepare(
+            `UPDATE workflow_follow_ups
+             SET status = 'removed', reason_hash = ?, updated_at = ?
+             WHERE follow_up_id = ? AND status IN ('queued', 'pending_presentation', 'ready')`,
+          )
+          .run(reasonHash, now, request.followUpId);
+        if (update.changes !== 1) {
+          throw new StaleResourceError("Workflow follow-up changed before removal");
+        }
+      },
+      { payload: { followUpId: request.followUpId, source: request.source } },
+    );
+    return this.followUpRecord(this.requireFollowUpRow(request.followUpId));
+  }
+
+  originSessionId(runId: string): string | undefined {
+    const row = this.state.connection
+      .prepare(
+        `SELECT COALESCE(q.origin_session_id, b.origin_session_id) AS originSessionId
+         FROM runs r
+         LEFT JOIN workflow_follow_up_queues q ON q.run_id = r.run_id
+         LEFT JOIN run_bindings b ON b.run_id = r.run_id
+         WHERE r.run_id = ?`,
+      )
+      .get(runId);
+    return isRecord(row) && typeof row.originSessionId === "string"
+      ? row.originSessionId
+      : undefined;
+  }
+
+  readFollowUpQueue(runId: string): WorkflowFollowUpQueueRecord | undefined {
+    const queue = this.followUpQueueRow(runId);
+    if (queue === undefined) return undefined;
+    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) => this.followUpRecord(row));
+    return {
+      runId,
+      ...(queue.originSessionId !== null ? { originSessionId: queue.originSessionId } : {}),
+      presentationState: assertPresentationState(queue.presentationState),
+      ...(queue.presentationEntryId !== null
+        ? { presentationEntryId: queue.presentationEntryId }
+        : {}),
+      ...(queue.presentationAssistantEntryId !== null
+        ? { presentationAssistantEntryId: queue.presentationAssistantEntryId }
+        : {}),
+      ...(queue.presentationReasonHash !== null
+        ? { presentationReason: this.readText(queue.presentationReasonHash) }
+        : {}),
+      followUps,
+    };
+  }
+
+  listPendingPresentations(targetSessionId: string): string[] {
+    return this.state.connection
+      .prepare(
+        `SELECT run_id AS runId FROM workflow_follow_up_queues
+         WHERE origin_session_id = ? AND presentation_state = 'pending'
+         ORDER BY created_at`,
+      )
+      .all(targetSessionId)
+      .flatMap((row) => (isRecord(row) && typeof row.runId === "string" ? [row.runId] : []));
+  }
+
+  settleFollowUpPresentation(options: {
+    runId: string;
+    state: "settled" | "unavailable";
+    presentationEntryId?: string;
+    assistantEntryId?: string;
+    reason?: string;
+  }): WorkflowFollowUpQueueRecord {
+    const queue = this.requireFollowUpQueueRow(options.runId);
+    if (queue.presentationState === options.state) {
+      return this.readFollowUpQueue(options.runId) as WorkflowFollowUpQueueRecord;
+    }
+    if (queue.presentationState !== "pending") {
+      throw new Error(
+        `Workflow presentation is ${queue.presentationState}, not pending for ${options.runId}`,
+      );
+    }
+    if (
+      options.state === "settled" &&
+      (options.presentationEntryId === undefined || options.assistantEntryId === undefined)
+    ) {
+      throw new Error("Settled workflow presentation requires both session entry IDs");
+    }
+    if (options.state === "unavailable" && !options.reason?.trim()) {
+      throw new Error("Unavailable workflow presentation requires a reason");
+    }
+    try {
+      this.mutations.mutate(
+        {
+          resourceId: queue.resourceId,
+          operation: "follow-up.presentation",
+          actor: {
+            type: "session",
+            ...(queue.originSessionId !== null ? { id: queue.originSessionId } : {}),
+          },
+          expectedRevision: queue.revision,
+        },
+        `follow-up.presentation-${options.state}`,
+        ({ database, now }) => {
+          const reasonHash =
+            options.state === "unavailable"
+              ? database.putText(options.reason as string, now)
+              : null;
+          database.connection
+            .prepare(
+              `UPDATE workflow_follow_up_queues
+             SET presentation_state = ?, presentation_entry_id = ?,
+                 presentation_assistant_entry_id = ?, presentation_reason_hash = ?,
+                 presentation_updated_at = ?, updated_at = ?
+             WHERE run_id = ? AND presentation_state = 'pending'`,
+            )
+            .run(
+              options.state,
+              options.presentationEntryId ?? null,
+              options.assistantEntryId ?? null,
+              reasonHash,
+              now,
+              now,
+              options.runId,
+            );
+          database.connection
+            .prepare(
+              `UPDATE workflow_follow_ups SET status = 'ready', updated_at = ?
+             WHERE run_id = ? AND status = 'pending_presentation'`,
+            )
+            .run(now, options.runId);
+        },
+        { payload: { runId: options.runId, state: options.state } },
+      );
+    } catch (error) {
+      if (error instanceof StaleResourceError) {
+        const current = this.requireFollowUpQueueRow(options.runId);
+        if (current.presentationState === options.state) {
+          return this.readFollowUpQueue(options.runId) as WorkflowFollowUpQueueRecord;
+        }
+      }
+      throw error;
+    }
+    return this.readFollowUpQueue(options.runId) as WorkflowFollowUpQueueRecord;
+  }
+
+  claimNextFollowUp(
+    targetSessionId: string,
+    ownerId: string,
+    leaseMs = 30_000,
+  ): { followUp: WorkflowFollowUpRecord; claim: LeaseClaim } | undefined {
+    const rows = this.state.connection
+      .prepare(
+        `${FOLLOW_UP_ROW_SELECT}
+         WHERE f.target_session_id = ? AND f.status = 'ready'
+         ORDER BY f.created_at, f.order_number LIMIT 16`,
+      )
+      .all(targetSessionId)
+      .filter(isFollowUpRow);
+    for (const row of rows) {
+      let claim: LeaseClaim | undefined;
+      try {
+        claim = this.mutations.claim({
+          resourceId: row.resourceId,
+          ownerType: "session",
+          ownerId,
+          expectedRevision: row.revision,
+          leaseMs,
+        });
+      } catch (error) {
+        if (error instanceof StaleResourceError) continue;
+        throw error;
+      }
+      if (claim === undefined) continue;
+      const current = this.requireFollowUpRow(row.followUpId);
+      if (current.status !== "ready") {
+        this.mutations.release(claim, claim.resourceRevision);
+        continue;
+      }
+      return { followUp: this.followUpRecord(current), claim };
+    }
+    return undefined;
+  }
+
+  markFollowUpSent(
+    followUpId: string,
+    claim: LeaseClaim,
+    sessionEntryId: string,
+  ): WorkflowFollowUpRecord {
+    const row = this.requireFollowUpRow(followUpId);
+    if (row.status === "sent") return this.followUpRecord(row);
+    this.mutations.mutate(
+      {
+        resourceId: row.resourceId,
+        operation: "follow-up.sent",
+        actor: { type: "session", id: claim.ownerId },
+        expectedRevision: claim.resourceRevision,
+        lease: claim,
+      },
+      "follow-up.sent",
+      ({ database, now }) => {
+        const update = database.connection
+          .prepare(
+            `UPDATE workflow_follow_ups
+             SET status = 'sent', session_entry_id = ?, sent_at = ?, updated_at = ?
+             WHERE follow_up_id = ? AND status = 'ready'`,
+          )
+          .run(sessionEntryId, now, now, followUpId);
+        if (update.changes !== 1) {
+          throw new StaleResourceError("Workflow follow-up changed before delivery completed");
+        }
+      },
+      { payload: { followUpId, sessionEntryId } },
+    );
+    return this.followUpRecord(this.requireFollowUpRow(followUpId));
+  }
+
+  releaseFollowUpClaim(claim: LeaseClaim): void {
+    const revision = this.requireResourceRevision(claim.resourceId);
+    this.mutations.release(claim, revision);
+  }
+
   async prepareRunResume(runId: string): Promise<LoadedWorkflowRun> {
     const loaded = this.readRun(runId, { includeTrace: true });
     if (loaded === null) throw new Error(`Cannot resume unreadable workflow run: ${runId}`);
     if (loaded.state.status !== "running") {
       throw new Error(`Cannot resume workflow run ${runId} with status ${loaded.state.status}`);
     }
+    this.verifySettingsProjections(runId);
     const revision = this.resourceRevision(runId);
     this.contexts.set(runId, { revision, lock: Promise.resolve() });
     this.finalizeRecordingCaptures(runId, "Workflow host stopped before the run finished");
@@ -293,10 +1067,10 @@ export class WorkflowRunStore {
       this.state.connection
         .prepare(
           `UPDATE node_attempts
-           SET status = 'cancelled', finished_at = ?, updated_at = ?
+           SET status = 'interrupted', updated_at = ?
            WHERE run_id = ? AND status IN ('pending', 'running', 'waiting')`,
         )
-        .run(now, now, runId);
+        .run(now, runId);
       insertRunEvent(this.state, row.resourceId, nextRevision, at, {
         scope: "run",
         type: "run_resume_prepared",
@@ -325,6 +1099,9 @@ export class WorkflowRunStore {
     delete loaded.state.currentNode;
     delete loaded.state.currentAttemptId;
     delete loaded.state.currentNodeStartedAt;
+    delete loaded.state.currentSettingsScopeId;
+    delete loaded.state.currentSettingsChangeNumber;
+    delete loaded.state.currentSettingsHash;
     delete loaded.state.statusDetail;
     delete loaded.state.paused;
     await this.writeSnapshot(runId, loaded.state, {
@@ -393,10 +1170,20 @@ export class WorkflowRunStore {
         this.state.connection
           .prepare(
             `INSERT INTO workflow_updates(
-               update_id, attempt_id, update_seq, update_type, update_key, data_hash, recorded_at
-             ) VALUES (?, ?, ?, ?, ?, ?, ?)`,
+               update_id, attempt_id, update_seq, run_revision,
+               update_type, update_key, data_hash, recorded_at
+             ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
           )
-          .run(updateId, attemptId, nextUpdateSeq, update.type, update.key, dataHash, Date.now());
+          .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;
@@ -424,12 +1211,14 @@ export class WorkflowRunStore {
         const revision = context.revision + 1;
         const now = Date.now();
         const at = new Date(now).toISOString();
+        const snapshot = this.readDefinition(run.definitionHash);
+        this.assertSettingsRouteCurrent(event, snapshot);
         const traceEvent: WorkflowTraceEvent = { seq: revision, at, runId, ...event };
         state.traceSeq = revision;
         state.updatedAt = at;
         insertRunEvent(this.state, run.resourceId, revision, at, traceEvent);
         this.persistRunState(run, state, revision, now);
-        const snapshot = this.readDefinition(run.definitionHash);
+        this.transitionFollowUpsForRunState(state, event, now);
         this.syncNodeAttempts(state, snapshot, now);
         context.revision = revision;
         accepted = traceEvent;
@@ -515,6 +1304,13 @@ export class WorkflowRunStore {
              ON CONFLICT(run_id) DO NOTHING`,
           )
           .run(runId, binding.piSessionId, now);
+        this.state.connection
+          .prepare(
+            `UPDATE workflow_follow_up_queues
+             SET origin_session_id = COALESCE(origin_session_id, ?), updated_at = ?
+             WHERE run_id = ?`,
+          )
+          .run(binding.piSessionId, now, runId);
         const revision = context.revision + 1;
         const at = new Date(now).toISOString();
         insertRunEvent(this.state, run.resourceId, revision, at, {
@@ -528,7 +1324,7 @@ export class WorkflowRunStore {
             ...(attemptId !== undefined ? { captureAttemptId: attemptId } : {}),
           },
         });
-        const current = this.readState(run.stateHash);
+        const current = this.readRunState(run, this.readDefinition(run.definitionHash));
         current.traceSeq = revision;
         current.updatedAt = at;
         this.persistRunState(run, current, revision, now);
@@ -567,7 +1363,7 @@ export class WorkflowRunStore {
         "session.entry_appended",
         "session",
         segment.sessionId,
-        entryHash,
+        null,
         now,
       );
       return sequence;
@@ -616,24 +1412,9 @@ export class WorkflowRunStore {
           );
         expected += 1;
       }
-      const now = Date.now();
       this.state.connection
         .prepare("UPDATE session_segments SET event_count = ? WHERE segment_id = ?")
         .run(expected - 1, current.segmentId);
-      const resourceId = segmentResourceId(current);
-      const revision = this.requireResourceRevision(resourceId);
-      this.bumpResource(resourceId, revision, now);
-      const payloadHash = this.state.putJson({ count: records.length, lastSeq: expected - 1 }, now);
-      insertGenericEvent(
-        this.state,
-        resourceId,
-        revision + 1,
-        "session.events_appended",
-        "session",
-        current.sessionId,
-        payloadHash,
-        now,
-      );
     });
   }
 
@@ -698,8 +1479,8 @@ export class WorkflowRunStore {
   readRun(runId: string, options: ReadWorkflowRunOptions = {}): LoadedWorkflowRun | null {
     const row = this.readRunRow(runId);
     if (row === undefined) return null;
-    const state = this.readState(row.stateHash);
     const snapshot = this.readDefinition(row.definitionHash);
+    const state = this.readRunState(row, snapshot);
     const segments = this.segmentRows(runId).map((segment) => this.loadSegment(segment, state));
     const flat = segments.find((segment) => segment.attemptId === "") ?? emptySegment();
     return {
@@ -713,6 +1494,8 @@ export class WorkflowRunStore {
       sessionCapture: flat.capture,
       sessionIntegrity: flat.integrity,
       sessionSegments: segments.filter((segment) => segment.attemptId !== ""),
+      settingsScopes: this.settingsScopesForRunView(runId),
+      followUpQueue: this.readFollowUpQueue(runId) ?? null,
     };
   }
 
@@ -831,13 +1614,14 @@ export class WorkflowRunStore {
     now: number,
   ): void {
     this.bumpResource(run.resourceId, expectedRevision - 1, now);
-    const stateHash = this.state.putJson(state, now);
+    const finalOutputHash =
+      state.finalOutput === undefined ? null : this.state.putJson(state.finalOutput, now);
     const errorHash = state.error === undefined ? null : this.state.putText(state.error, now);
     const update = this.state.connection
       .prepare(
         `UPDATE runs
-         SET title = ?, status = ?, paused = ?, status_detail = ?, output_hash = ?,
-             error_hash = ?, updated_at = ?, finished_at = ?
+         SET title = ?, status = ?, paused = ?, status_detail = ?,
+             final_output_hash = ?, error_hash = ?, updated_at = ?, finished_at = ?
          WHERE run_id = ?`,
       )
       .run(
@@ -845,7 +1629,7 @@ export class WorkflowRunStore {
         state.status,
         state.paused === true ? 1 : 0,
         state.statusDetail ?? null,
-        stateHash,
+        finalOutputHash,
         errorHash,
         now,
         state.finishedAt === undefined ? null : Date.parse(state.finishedAt),
@@ -855,7 +1639,6 @@ export class WorkflowRunStore {
     if (state.status !== "running") {
       this.enqueueRunSettlementEffect(run.resourceId, expectedRevision, state, now);
     }
-    run.stateHash = stateHash;
   }
 
   private enqueueRunSettlementEffect(
@@ -925,96 +1708,686 @@ export class WorkflowRunStore {
     );
   }
 
-  private syncNodeAttempts(
+  private initializeRunSettingsAndFollowUps(
     state: WorkflowRunState,
-    snapshot: WorkflowDefinitionSnapshot,
+    initialSettings: InitialWorkflowSettingsScope[],
     now: number,
   ): void {
-    for (const step of state.steps.slice(state.carriedStepCount ?? 0)) {
-      const resultHash = this.state.putJson(step, now);
-      const outputHash = step.output === undefined ? null : this.state.putJson(step.output, now);
-      const errorHash = step.error === undefined ? null : this.state.putText(step.error, now);
-      const promptHash = step.prompt === null ? null : this.state.putJson(step.prompt, now);
-      const existing = this.state.connection
-        .prepare("SELECT attempt_id AS attemptId FROM node_attempts WHERE attempt_id = ?")
-        .get(step.attemptId);
-      if (existing === undefined) {
-        const attemptNumber = this.nextAttemptNumber(state.runId, step.nodeId);
+    const childQueueResourceId = this.ensureFollowUpQueue(state.runId, now);
+    if (state.parentRunId !== undefined) {
+      const parentQueue = this.followUpQueueRow(state.parentRunId);
+      if (parentQueue !== undefined) {
         this.state.connection
           .prepare(
-            `INSERT INTO node_attempts(
-               attempt_id, run_id, node_id, attempt_number, node_type, status,
-               presentation_hash, output_hash, result_hash, error_hash,
-               started_at, finished_at, created_at, updated_at
-             ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+            `UPDATE workflow_follow_up_queues
+             SET origin_session_id = COALESCE(origin_session_id, ?), updated_at = ?
+             WHERE run_id = ?`,
           )
-          .run(
-            step.attemptId,
-            state.runId,
-            step.nodeId,
-            attemptNumber,
-            step.nodeType,
-            outcomeStatus(step.outcome),
-            promptHash,
-            outputHash,
-            resultHash,
-            errorHash,
-            Date.parse(step.startedAt),
-            Date.parse(step.finishedAt),
-            Date.parse(step.startedAt),
-            now,
-          );
-      } else {
+          .run(parentQueue.originSessionId, now, state.runId);
         this.state.connection
           .prepare(
-            `UPDATE node_attempts
-             SET status = ?, presentation_hash = ?, output_hash = ?, result_hash = ?,
-                 error_hash = ?, finished_at = ?, updated_at = ?
-             WHERE attempt_id = ?`,
+            `UPDATE workflow_follow_ups
+             SET run_id = ?, queue_resource_id = ?, updated_at = ?
+             WHERE run_id = ? AND status = 'queued'`,
           )
-          .run(
-            outcomeStatus(step.outcome),
-            promptHash,
-            outputHash,
-            resultHash,
-            errorHash,
-            Date.parse(step.finishedAt),
-            now,
-            step.attemptId,
-          );
+          .run(state.runId, childQueueResourceId, now, state.parentRunId);
       }
+      this.state.connection
+        .prepare(
+          `UPDATE workflow_settings SET active_run_id = ?, updated_at = ? WHERE active_run_id = ?`,
+        )
+        .run(state.runId, now, state.parentRunId);
     }
-    if (state.currentAttemptId !== undefined && state.currentNode !== undefined) {
-      this.ensureAttempt(state, state.currentNode, state.currentAttemptId, now, snapshot);
-    }
-  }
-
-  private ensureAttempt(
-    state: WorkflowRunState,
-    nodeId: string,
-    attemptId: string,
-    now: number,
-    snapshot?: WorkflowDefinitionSnapshot,
-  ): void {
     const existing = this.state.connection
-      .prepare("SELECT attempt_id AS attemptId FROM node_attempts WHERE attempt_id = ?")
-      .get(attemptId);
-    const status = state.status === "waiting" ? "waiting" : "running";
-    if (existing !== undefined) {
+      .prepare("SELECT COUNT(*) AS count FROM workflow_settings WHERE active_run_id = ?")
+      .get(state.runId);
+    const hasSettings = isCountRow(existing) && existing.count > 0;
+    if (hasSettings) return;
+    for (const scope of initialSettings) {
+      const originRunId = this.logicalOriginRunId(state.runId);
+      const scopeId = workflowSettingsScopeId(originRunId, scope.mountPath, scope.invocation);
+      const resourceId = this.mutations.ensureResource("settings", scopeId, now);
+      const settingsHash = this.state.putJson(scope.settings, now);
       this.state.connection
-        .prepare("UPDATE node_attempts SET status = ?, updated_at = ? WHERE attempt_id = ?")
-        .run(status, now, attemptId);
-      return;
+        .prepare(
+          `INSERT INTO workflow_settings(
+             scope_id, resource_id, origin_run_id, active_run_id, mount_path, invocation,
+             initial_hash, current_hash, created_at, updated_at
+           ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+           ON CONFLICT(scope_id) DO NOTHING`,
+        )
+        .run(
+          scopeId,
+          resourceId,
+          originRunId,
+          state.runId,
+          scope.mountPath,
+          scope.invocation,
+          settingsHash,
+          settingsHash,
+          now,
+          now,
+        );
+    }
+  }
+
+  private ensureFollowUpQueue(runId: string, now: number): string {
+    const resourceId = this.mutations.ensureResource("follow_up_queue", runId, now);
+    this.state.connection
+      .prepare(
+        `INSERT INTO workflow_follow_up_queues(
+           run_id, resource_id, created_at, updated_at
+         ) VALUES (?, ?, ?, ?)
+         ON CONFLICT(run_id) DO NOTHING`,
+      )
+      .run(runId, resourceId, now, now);
+    return resourceId;
+  }
+
+  private logicalOriginRunId(runId: string): string {
+    let current = runId;
+    for (let depth = 0; depth < 100; depth += 1) {
+      const row = this.state.connection
+        .prepare("SELECT parent_run_id AS parentRunId FROM runs WHERE run_id = ?")
+        .get(current);
+      if (!isParentRunRow(row)) return current;
+      if (row.parentRunId === null) return current;
+      current = row.parentRunId;
+    }
+    throw new Error(`Workflow continuation chain is too deep for run ${runId}`);
+  }
+
+  private requireRunAcceptsSettings(runId: string, allowWaiting: boolean): void {
+    const row = this.state.connection
+      .prepare("SELECT status FROM runs WHERE run_id = ?")
+      .get(runId);
+    if (!isStatusRow(row)) throw new Error(`Workflow run is missing: ${runId}`);
+    if (row.status !== "running" && !(allowWaiting && row.status === "waiting")) {
+      throw new Error(`Workflow run ${runId} does not accept changes with status ${row.status}`);
+    }
+  }
+
+  private verifySettingsProjections(runId: string): void {
+    const scopes = this.state.connection
+      .prepare(
+        `SELECT s.scope_id AS scopeId, s.initial_hash AS initialHash,
+                s.current_hash AS currentHash, r.revision
+         FROM workflow_settings s
+         JOIN resources r ON r.resource_id = s.resource_id
+         WHERE s.active_run_id = ?`,
+      )
+      .all(runId);
+    for (const value of scopes) {
+      if (!isSettingsProjectionRow(value)) {
+        throw new Error("Workflow settings projection row is invalid");
+      }
+      let current = this.state.readJson(value.initialHash);
+      let currentHash = value.initialHash;
+      const changes = this.state.connection
+        .prepare(
+          `SELECT change_number AS changeNumber, patch_hash AS patchHash,
+                  before_hash AS beforeHash, after_hash AS afterHash
+           FROM workflow_setting_changes WHERE scope_id = ? ORDER BY change_number`,
+        )
+        .all(value.scopeId);
+      let expected = 1;
+      for (const change of changes) {
+        if (!isSettingsProjectionChangeRow(change) || change.changeNumber !== expected) {
+          throw new Error(`Workflow settings changes are not contiguous for ${value.scopeId}`);
+        }
+        if (!change.beforeHash.equals(currentHash)) {
+          throw new Error(`Workflow settings change has a wrong old value for ${value.scopeId}`);
+        }
+        current = applyJsonPatch(current, this.state.readJson(change.patchHash));
+        currentHash = createHash("sha256").update(canonicalJson(current)).digest();
+        if (!currentHash.equals(change.afterHash)) {
+          throw new Error(`Workflow settings change has a wrong new value for ${value.scopeId}`);
+        }
+        expected += 1;
+      }
+      if (value.revision !== expected - 1 || !value.currentHash.equals(currentHash)) {
+        throw new Error(
+          `Workflow settings projection does not match saved changes for ${value.scopeId}`,
+        );
+      }
+    }
+  }
+
+  private settingsScopeRow(scopeId: string): SettingsScopeRow | undefined {
+    const row = 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.scope_id = ?`,
+      )
+      .get(scopeId);
+    return isSettingsScopeRow(row) ? row : undefined;
+  }
+
+  private requireSettingsScopeRow(scopeId: string): SettingsScopeRow {
+    const row = this.settingsScopeRow(scopeId);
+    if (row === undefined) throw new Error(`Workflow settings scope not found: ${scopeId}`);
+    return row;
+  }
+
+  private settingsScopeRecord(
+    row: SettingsScopeRow,
+    changeNumber = row.revision,
+    settingsHash = row.currentHash,
+  ): WorkflowSettingsScopeRecord {
+    return {
+      scopeId: row.scopeId,
+      originRunId: row.originRunId,
+      activeRunId: row.activeRunId,
+      mountPath: row.mountPath,
+      invocation: row.invocation,
+      changeNumber,
+      settings: this.state.readJson(settingsHash),
+      settingsHash: settingsHash.toString("hex"),
+      createdAt: new Date(row.createdAt).toISOString(),
+      updatedAt: new Date(row.updatedAt).toISOString(),
+    };
+  }
+
+  private settingsChangeRow(scopeId: string, requestId: string): SettingsChangeRow | undefined {
+    const row = this.state.connection
+      .prepare(
+        `SELECT change_id AS changeId, scope_id AS scopeId, request_id AS requestId,
+                change_number AS changeNumber, actor_type AS actorType, actor_id AS actorId,
+                source_type AS sourceType, patch_hash AS patchHash,
+                before_hash AS beforeHash, after_hash AS afterHash,
+                accepted_at AS acceptedAt
+         FROM workflow_setting_changes WHERE scope_id = ? AND request_id = ?`,
+      )
+      .get(scopeId, requestId);
+    return isSettingsChangeRow(row) ? row : undefined;
+  }
+
+  private settingsChangeRecord(row: SettingsChangeRow): WorkflowSettingsChangeRecord {
+    return {
+      changeId: row.changeId,
+      scopeId: row.scopeId,
+      requestId: row.requestId,
+      changeNumber: row.changeNumber,
+      actor: {
+        type: assertActorType(row.actorType),
+        ...(row.actorId !== null ? { id: row.actorId } : {}),
+      },
+      source: row.sourceType,
+      patch: validateJsonPatch(this.state.readJson(row.patchHash)),
+      beforeHash: row.beforeHash.toString("hex"),
+      afterHash: row.afterHash.toString("hex"),
+      acceptedAt: new Date(row.acceptedAt).toISOString(),
+    };
+  }
+
+  private assertSameSettingsChange(
+    row: SettingsChangeRow,
+    request: WorkflowSettingsChangeRequest,
+    patchDigest: Buffer,
+  ): void {
+    if (
+      !row.patchHash.equals(patchDigest) ||
+      row.actorType !== request.actor.type ||
+      row.actorId !== (request.actor.id ?? null) ||
+      row.sourceType !== request.source
+    ) {
+      throw new Error(`Workflow settings request ID was reused with different content`);
+    }
+  }
+
+  private followUpQueueRow(runId: string): FollowUpQueueRow | undefined {
+    const row = this.state.connection
+      .prepare(
+        `SELECT q.run_id AS runId, q.resource_id AS resourceId,
+                q.origin_session_id AS originSessionId,
+                q.presentation_state AS presentationState,
+                q.presentation_entry_id AS presentationEntryId,
+                q.presentation_assistant_entry_id AS presentationAssistantEntryId,
+                q.presentation_reason_hash AS presentationReasonHash,
+                r.revision
+         FROM workflow_follow_up_queues q
+         JOIN resources r ON r.resource_id = q.resource_id
+         WHERE q.run_id = ?`,
+      )
+      .get(runId);
+    return isFollowUpQueueRow(row) ? row : undefined;
+  }
+
+  private requireFollowUpQueueRow(runId: string): FollowUpQueueRow {
+    const row = this.followUpQueueRow(runId);
+    if (row === undefined) throw new Error(`Workflow follow-up queue not found: ${runId}`);
+    return row;
+  }
+
+  private followUpRowByRequest(runId: string, requestId: string): FollowUpRow | undefined {
+    const row = this.state.connection
+      .prepare(`${FOLLOW_UP_ROW_SELECT} WHERE f.run_id = ? AND f.request_id = ?`)
+      .get(runId, requestId);
+    return isFollowUpRow(row) ? row : undefined;
+  }
+
+  private followUpRow(followUpId: string): FollowUpRow | undefined {
+    const row = this.state.connection
+      .prepare(`${FOLLOW_UP_ROW_SELECT} WHERE f.follow_up_id = ?`)
+      .get(followUpId);
+    return isFollowUpRow(row) ? row : undefined;
+  }
+
+  private requireFollowUpRow(followUpId: string): FollowUpRow {
+    const row = this.followUpRow(followUpId);
+    if (row === undefined) throw new Error(`Workflow follow-up not found: ${followUpId}`);
+    return row;
+  }
+
+  private followUpRecord(row: FollowUpRow): WorkflowFollowUpRecord {
+    return {
+      followUpId: row.followUpId,
+      runId: row.runId,
+      requestId: row.requestId,
+      order: row.orderNumber,
+      targetSessionId: row.targetSessionId,
+      actor: {
+        type: assertActorType(row.actorType),
+        ...(row.actorId !== null ? { id: row.actorId } : {}),
+      },
+      source: row.sourceType,
+      prompt: this.readText(row.promptHash),
+      state: assertFollowUpState(row.status),
+      ...(row.sessionEntryId !== null ? { sessionEntryId: row.sessionEntryId } : {}),
+      ...(row.reasonHash !== null ? { reason: this.readText(row.reasonHash) } : {}),
+      createdAt: new Date(row.createdAt).toISOString(),
+      updatedAt: new Date(row.updatedAt).toISOString(),
+      ...(row.sentAt !== null ? { sentAt: new Date(row.sentAt).toISOString() } : {}),
+    };
+  }
+
+  private assertSameFollowUp(row: FollowUpRow, request: WorkflowQueueFollowUpRequest): void {
+    const promptHash = createHash("sha256").update(request.prompt).digest();
+    if (
+      !row.promptHash.equals(promptHash) ||
+      row.targetSessionId !== request.targetSessionId ||
+      row.actorType !== request.actor.type ||
+      row.actorId !== (request.actor.id ?? null) ||
+      row.sourceType !== request.source
+    ) {
+      throw new Error("Workflow follow-up request ID was reused with different content");
+    }
+  }
+
+  private assertFollowUpRemovalAuthority(
+    row: FollowUpRow,
+    actor: MutationActor,
+    source: string,
+  ): void {
+    if (actor.type === "human") return;
+    if (
+      (actor.type === "session" || actor.type === "controller") &&
+      row.actorType === actor.type &&
+      row.actorId === (actor.id ?? null) &&
+      row.sourceType === source
+    ) {
+      return;
+    }
+    throw new Error("Workflow follow-up can be removed only by its source or a verified human");
+  }
+
+  private hasLiveLease(resourceId: string): boolean {
+    const row = this.state.connection
+      .prepare("SELECT expires_at AS expiresAt FROM leases WHERE resource_id = ?")
+      .get(resourceId);
+    return isLeaseExpiryRow(row) && row.expiresAt !== null && row.expiresAt > Date.now();
+  }
+
+  private nextFollowUpOrder(runId: string): number {
+    const row = this.state.connection
+      .prepare(
+        `SELECT COALESCE(MAX(order_number), 0) + 1 AS nextOrder
+         FROM workflow_follow_ups WHERE run_id = ?`,
+      )
+      .get(runId);
+    if (!isNextOrderRow(row)) throw new Error("Could not allocate workflow follow-up order");
+    return row.nextOrder;
+  }
+
+  private assertSettingsRouteCurrent(
+    event: WorkflowTraceEventDraft,
+    snapshot: WorkflowDefinitionSnapshot,
+  ): void {
+    if (event.type !== "node_finished" || event.nodeId === undefined) return;
+    if (snapshot.nodes[event.nodeId]?.settingsRoute !== true) return;
+    const scopeId = event.payload.settingsScopeId;
+    const changeNumber = event.payload.settingsChangeNumber;
+    if (typeof scopeId !== "string" || typeof changeNumber !== "number") {
+      throw new Error(`Settings route ${event.nodeId} has no saved settings binding`);
+    }
+    const scope = this.requireSettingsScopeRow(scopeId);
+    if (scope.revision !== changeNumber) {
+      throw new StaleResourceError(
+        `Settings route ${event.nodeId} used change ${changeNumber}, current change is ${scope.revision}`,
+      );
+    }
+  }
+
+  private transitionFollowUpsForRunState(
+    state: WorkflowRunState,
+    event: WorkflowTraceEventDraft,
+    now: number,
+  ): void {
+    if (state.status === "running" || state.status === "waiting") return;
+    const queue = this.followUpQueueRow(state.runId);
+    if (queue === undefined || queue.presentationState !== "none") return;
+    let presentationState: WorkflowPresentationState = "not-needed";
+    let followUpState: WorkflowFollowUpState = "cancelled";
+    let reasonHash: Buffer | null = null;
+    if (state.status === "completed") {
+      const required = event.payload.presentationRequired === true;
+      presentationState = required ? "pending" : "not-needed";
+      followUpState = required ? "pending_presentation" : "ready";
+    } else {
+      reasonHash = this.state.putText(
+        state.error ?? `Workflow ended with status ${state.status}`,
+        now,
+      );
+    }
+    this.state.connection
+      .prepare(
+        `UPDATE workflow_follow_up_queues
+         SET presentation_state = ?, presentation_updated_at = ?, updated_at = ?
+         WHERE run_id = ? AND presentation_state = 'none'`,
+      )
+      .run(presentationState, now, now, state.runId);
+    this.state.connection
+      .prepare(
+        `UPDATE workflow_follow_ups
+         SET status = ?, reason_hash = ?, updated_at = ?
+         WHERE run_id = ? AND status IN ('queued', 'pending_presentation', 'ready')`,
+      )
+      .run(followUpState, reasonHash, now, state.runId);
+    const revision = this.requireResourceRevision(queue.resourceId);
+    this.bumpResource(queue.resourceId, revision, now);
+    const payloadHash = this.state.putJson(
+      { runId: state.runId, state: presentationState, followUps: followUpState },
+      now,
+    );
+    insertGenericEvent(
+      this.state,
+      queue.resourceId,
+      revision + 1,
+      "follow-up.run-finished",
+      "system",
+      null,
+      payloadHash,
+      now,
+    );
+  }
+
+  private syncNodeAttempts(
+    state: WorkflowRunState,
+    snapshot: WorkflowDefinitionSnapshot,
+    now: number,
+  ): void {
+    for (const step of state.steps.slice(state.carriedStepCount ?? 0)) {
+      const promptEntryId = this.findAttemptPromptEntry(state.runId, step.attemptId);
+      const promptHash =
+        promptEntryId === undefined && step.prompt !== null
+          ? this.state.putText(step.prompt, now)
+          : null;
+      const receipt = attemptReceipt(step);
+      const receiptHash =
+        Object.keys(receipt).length === 0 ? null : this.state.putJson(receipt, now);
+      const outputHash = step.output === undefined ? null : this.state.putJson(step.output, now);
+      const errorHash = step.error === undefined ? null : this.state.putText(step.error, now);
+      const existing = this.state.connection
+        .prepare("SELECT attempt_id AS attemptId FROM node_attempts WHERE attempt_id = ?")
+        .get(step.attemptId);
+      if (existing === undefined) {
+        const attemptNumber = this.nextAttemptNumber(state.runId, step.nodeId);
+        this.state.connection
+          .prepare(
+            `INSERT INTO node_attempts(
+               attempt_id, run_id, node_id, attempt_number, node_type, status,
+               prompt_hash, output_hash, receipt_hash, error_hash,
+               settings_scope_id, settings_change_number, settings_hash,
+               started_at, finished_at, created_at, updated_at
+             ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+          )
+          .run(
+            step.attemptId,
+            state.runId,
+            step.nodeId,
+            attemptNumber,
+            step.nodeType,
+            outcomeStatus(step.outcome),
+            promptHash,
+            outputHash,
+            receiptHash,
+            errorHash,
+            step.settingsScopeId ?? null,
+            step.settingsChangeNumber ?? null,
+            step.settingsHash === undefined ? null : Buffer.from(step.settingsHash, "hex"),
+            Date.parse(step.startedAt),
+            Date.parse(step.finishedAt),
+            Date.parse(step.startedAt),
+            now,
+          );
+      } else {
+        this.state.connection
+          .prepare(
+            `UPDATE node_attempts
+             SET status = ?, prompt_hash = ?, output_hash = ?, receipt_hash = ?, error_hash = ?,
+                 settings_scope_id = ?, settings_change_number = ?,
+                 settings_hash = ?, finished_at = ?, updated_at = ?
+             WHERE attempt_id = ?`,
+          )
+          .run(
+            outcomeStatus(step.outcome),
+            promptHash,
+            outputHash,
+            receiptHash,
+            errorHash,
+            step.settingsScopeId ?? null,
+            step.settingsChangeNumber ?? null,
+            step.settingsHash === undefined ? null : Buffer.from(step.settingsHash, "hex"),
+            Date.parse(step.finishedAt),
+            now,
+            step.attemptId,
+          );
+      }
+      if (this.syncAttemptEntries(state.runId, step, promptEntryId)) {
+        this.state.connection
+          .prepare("UPDATE node_attempts SET output_hash = NULL WHERE attempt_id = ?")
+          .run(step.attemptId);
+      }
+    }
+    if (state.currentAttemptId !== undefined && state.currentNode !== undefined) {
+      this.ensureAttempt(state, state.currentNode, state.currentAttemptId, now, snapshot);
+    }
+    this.syncRunSteps(state, now);
+  }
+
+  private syncRunSteps(state: WorkflowRunState, now: number): void {
+    const existingRows = this.state.connection
+      .prepare(
+        `SELECT step_index AS stepIndex, attempt_id AS attemptId
+         FROM run_steps WHERE run_id = ? ORDER BY step_index`,
+      )
+      .all(state.runId)
+      .filter(isRunStepIdentityRow);
+    if (existingRows.length > state.steps.length) {
+      throw new Error(`Workflow run steps cannot shrink: ${state.runId}`);
+    }
+    for (const existing of existingRows) {
+      if (state.steps[existing.stepIndex]?.attemptId !== existing.attemptId) {
+        throw new Error(`Workflow run step history changed at index ${existing.stepIndex}`);
+      }
+    }
+    for (let stepIndex = existingRows.length; stepIndex < state.steps.length; stepIndex += 1) {
+      const step = state.steps[stepIndex];
+      /* istanbul ignore if -- array index follows a checked bound */
+      if (step === undefined) throw new Error("Workflow run step became unavailable");
+      const attemptOutput = this.readAttemptOutput(step.attemptId);
+      const carried = stepIndex < (state.carriedStepCount ?? 0);
+      const outputOverrideHash =
+        carried && canonicalJson(attemptOutput) !== canonicalJson(step.output)
+          ? this.state.putJson(step.output, now)
+          : null;
+      this.state.connection
+        .prepare(
+          `INSERT INTO run_steps(run_id, step_index, attempt_id, output_override_hash)
+           VALUES (?, ?, ?, ?)`,
+        )
+        .run(state.runId, stepIndex, step.attemptId, outputOverrideHash);
+    }
+  }
+
+  private syncAttemptEntries(
+    runId: string,
+    step: WorkflowStepRecord,
+    promptEntryId: string | undefined,
+  ): boolean {
+    const links: Array<["prompt" | "response" | "first" | "last", string]> = [];
+    if (promptEntryId !== undefined) links.push(["prompt", promptEntryId]);
+    if (step.conversation !== undefined) {
+      links.push(
+        ["first", step.conversation.firstEntryId],
+        ["last", step.conversation.lastEntryId],
+      );
+    }
+    if (step.assistantMessage?.entryId !== undefined) {
+      links.push(["response", step.assistantMessage.entryId]);
+    }
+    let responseLinked = false;
+    for (const [role, entryId] of links) {
+      const row = this.state.connection
+        .prepare(
+          `SELECT e.segment_id AS segmentId, e.entry_hash AS entryHash
+           FROM session_entries e
+           JOIN session_segments s ON s.segment_id = e.segment_id
+           WHERE s.run_id = ? AND e.entry_id = ?
+           ORDER BY e.recorded_at DESC LIMIT 1`,
+        )
+        .get(runId, entryId);
+      if (!isSegmentIdentityRow(row)) continue;
+      if (role === "response") {
+        const output = assistantOutputFromEntry(
+          this.state.readJson(row.entryHash),
+          step.assistantMessage?.maxChars,
+        );
+        if (
+          canonicalJson(output) !== canonicalJson(step.output) ||
+          createHash("sha256").update(output).digest("hex") !== step.assistantMessage?.sha256
+        ) {
+          throw new Error(`Assistant response entry conflicts with attempt ${step.attemptId}`);
+        }
+      }
+      this.state.connection
+        .prepare(
+          `INSERT INTO attempt_entries(attempt_id, role, segment_id, entry_id)
+           VALUES (?, ?, ?, ?)
+           ON CONFLICT(attempt_id, role) DO UPDATE SET
+             segment_id = excluded.segment_id, entry_id = excluded.entry_id`,
+        )
+        .run(step.attemptId, role, row.segmentId, entryId);
+      if (role === "response") responseLinked = true;
+    }
+    return responseLinked;
+  }
+
+  private findAttemptPromptEntry(runId: string, attemptId: string): string | undefined {
+    const row = this.state.connection
+      .prepare(
+        `SELECT e.entry_id AS entryId
+         FROM session_entries e
+         JOIN session_segments s ON s.segment_id = e.segment_id
+         JOIN blobs b ON b.blob_hash = e.entry_hash
+         WHERE s.run_id = ?
+           AND json_extract(CAST(b.content AS TEXT), '$.customType') = 'pi-workflows-agent-step'
+           AND json_extract(CAST(b.content AS TEXT), '$.details.contract.attemptId') = ?
+         ORDER BY e.recorded_at DESC LIMIT 1`,
+      )
+      .get(runId, attemptId);
+    return isEntryIdentityRow(row) ? row.entryId : undefined;
+  }
+
+  private readAttemptOutput(attemptId: string): unknown {
+    const row = this.state.connection
+      .prepare(
+        `SELECT a.output_hash AS outputHash, a.receipt_hash AS receiptHash,
+                e.entry_hash AS responseEntryHash
+         FROM node_attempts a
+         LEFT JOIN attempt_entries l ON l.attempt_id = a.attempt_id AND l.role = 'response'
+         LEFT JOIN session_entries e
+           ON e.segment_id = l.segment_id AND e.entry_id = l.entry_id
+         WHERE a.attempt_id = ?`,
+      )
+      .get(attemptId);
+    if (!isAttemptValueRow(row)) {
+      throw new Error(`Workflow node attempt is missing: ${attemptId}`);
+    }
+    if (row.outputHash !== null) return this.state.readJson(row.outputHash);
+    if (row.responseEntryHash === null) return null;
+    const receipt =
+      row.receiptHash === null ? {} : this.readJsonAs<StoredAttemptReceipt>(row.receiptHash);
+    return assistantOutputFromEntry(
+      this.state.readJson(row.responseEntryHash),
+      receipt.assistantMessage?.maxChars,
+    );
+  }
+
+  private ensureAttempt(
+    state: WorkflowRunState,
+    nodeId: string,
+    attemptId: string,
+    now: number,
+    snapshot?: WorkflowDefinitionSnapshot,
+  ): void {
+    const existing = this.state.connection
+      .prepare("SELECT attempt_id AS attemptId FROM node_attempts WHERE attempt_id = ?")
+      .get(attemptId);
+    const status = state.status === "waiting" ? "waiting" : "running";
+    if (existing !== undefined) {
+      this.state.connection
+        .prepare(
+          `UPDATE node_attempts
+           SET status = ?, settings_scope_id = ?, settings_change_number = ?,
+               settings_hash = ?, updated_at = ?
+           WHERE attempt_id = ?`,
+        )
+        .run(
+          status,
+          state.currentSettingsScopeId ?? null,
+          state.currentSettingsChangeNumber ?? null,
+          state.currentSettingsHash === undefined
+            ? null
+            : Buffer.from(state.currentSettingsHash, "hex"),
+          now,
+          attemptId,
+        );
+      return;
     }
     const definition =
       snapshot ?? this.readDefinition(this.requireRunRow(state.runId).definitionHash);
     const nodeType = definition.nodes[nodeId]?.nodeType ?? "agent";
+    this.state.connection
+      .prepare(
+        `UPDATE node_attempts
+         SET status = 'cancelled', finished_at = COALESCE(finished_at, ?), updated_at = ?
+         WHERE run_id = ? AND status = 'interrupted'`,
+      )
+      .run(now, now, state.runId);
     this.state.connection
       .prepare(
         `INSERT INTO node_attempts(
            attempt_id, run_id, node_id, attempt_number, node_type, status,
+           settings_scope_id, settings_change_number, settings_hash,
            started_at, created_at, updated_at
-         ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+         ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
       )
       .run(
         attemptId,
@@ -1023,6 +2396,11 @@ export class WorkflowRunStore {
         this.nextAttemptNumber(state.runId, nodeId),
         nodeType,
         status,
+        state.currentSettingsScopeId ?? null,
+        state.currentSettingsChangeNumber ?? null,
+        state.currentSettingsHash === undefined
+          ? null
+          : Buffer.from(state.currentSettingsHash, "hex"),
         state.currentNodeStartedAt === undefined ? now : Date.parse(state.currentNodeStartedAt),
         now,
         now,
@@ -1053,12 +2431,60 @@ export class WorkflowRunStore {
     return row.updateSeq;
   }
 
+  private insertRunSources(
+    runId: string,
+    root: { type: "builtin" | "file"; ref: string; revision: string },
+    mounted: WorkflowMountedSource[],
+  ): void {
+    const insert = this.state.connection.prepare(
+      `INSERT INTO run_sources(run_id, mount_path, source_type, source_ref, source_revision)
+       VALUES (?, ?, ?, ?, ?)`,
+    );
+    insert.run(runId, "", root.type, root.ref, root.revision);
+    for (const item of mounted) {
+      const source = sourceParts(item.source);
+      insert.run(runId, item.mountPath.join("/"), source.type, source.ref, source.revision);
+    }
+  }
+
+  private syncContinuationIdentity(state: WorkflowRunState): void {
+    if (state.parentRunId === undefined || state.humanDecision === undefined) return;
+    const createdAt = Date.parse(state.humanDecision.acceptedAt);
+    this.state.connection
+      .prepare(
+        `INSERT INTO continuations(
+           decision_id, parent_run_id, continuation_run_id, created_at
+         ) VALUES (?, ?, ?, ?)
+         ON CONFLICT(decision_id) DO NOTHING`,
+      )
+      .run(state.humanDecision.decisionId, state.parentRunId, state.runId, createdAt);
+    const row = this.state.connection
+      .prepare(
+        `SELECT parent_run_id AS parentRunId, continuation_run_id AS continuationRunId,
+                created_at AS createdAt
+         FROM continuations WHERE decision_id = ?`,
+      )
+      .get(state.humanDecision.decisionId);
+    if (
+      !isContinuationIdentityRow(row) ||
+      row.parentRunId !== state.parentRunId ||
+      row.continuationRunId !== state.runId ||
+      row.createdAt !== createdAt
+    ) {
+      throw new Error("Immutable human decision continuation conflicts");
+    }
+  }
+
   private readRunRow(runId: string): RunRow | undefined {
     const row = this.state.connection
       .prepare(
         `SELECT r.run_id AS runId, r.resource_id AS resourceId,
-                r.output_hash AS stateHash, d.definition_hash AS definitionHash,
-                r.status
+                d.definition_hash AS definitionHash, r.definition_digest AS definitionDigest,
+                d.workflow_name AS workflowRef, r.parent_run_id AS parentRunId,
+                r.title, r.status, r.paused, r.status_detail AS statusDetail,
+                r.input_hash AS inputHash, r.final_output_hash AS finalOutputHash,
+                r.error_hash AS errorHash,
+                r.created_at AS createdAt, r.updated_at AS updatedAt, r.finished_at AS finishedAt
          FROM runs r
          JOIN workflow_definitions d ON d.definition_digest = r.definition_digest
          WHERE r.run_id = ?`,
@@ -1073,12 +2499,308 @@ export class WorkflowRunStore {
     return row;
   }
 
-  private readState(hash: Buffer): WorkflowRunState {
-    const value = this.state.readJson(hash);
-    if (!isRecord(value) || value.schema !== RUN_STATE_SCHEMA) {
-      throw new Error("Workflow run state has an incompatible schema");
+  private readRunState(row: RunRow, snapshot: WorkflowDefinitionSnapshot): WorkflowRunState {
+    const steps = this.readSteps(row.runId);
+    const sources = this.readRunSources(row.runId, snapshot);
+    const carriedStepCount = this.carriedStepCount(row.runId);
+    const activeAttempt = row.status === "running" ? this.readActiveAttempt(row.runId) : undefined;
+    const humanDecision = this.readHumanDecisionReceipt(row.runId);
+    const outputs: Record<string, unknown> = {};
+    const results: Record<string, WorkflowNodeResult> = {};
+    for (const step of steps) {
+      const result = resultForStep(step);
+      results[step.nodeId] = result;
+      if (step.outcome === "ok") outputs[step.nodeId] = step.output;
+      else delete outputs[step.nodeId];
+      const node = snapshot.nodes[step.nodeId];
+      const mountPath =
+        node?.includeTransition === "exit" && node.mountPath !== undefined
+          ? node.mountPath.join("/")
+          : undefined;
+      if (mountPath !== undefined && step.outcome === "ok") {
+        outputs[mountPath] = step.output;
+        results[mountPath] = { ...result, nodeId: mountPath };
+      }
     }
-    return value as WorkflowRunState;
+    const revision = this.requireResourceRevision(row.resourceId);
+    return {
+      schema: RUN_STATE_SCHEMA,
+      traceSeq: revision,
+      runId: row.runId,
+      workflowName: row.workflowRef,
+      ...(row.parentRunId === null ? {} : { parentRunId: row.parentRunId }),
+      ...(carriedStepCount === 0 ? {} : { carriedStepCount }),
+      ...(row.title === null ? {} : { runTitle: row.title }),
+      ...(sources.root === undefined ? {} : { workflowSource: sources.root }),
+      ...(sources.mounted.length === 0 ? {} : { workflowSources: sources.mounted }),
+      ...(sources.mounted.length !== 0 || snapshot.composition?.mounts.length
+        ? { definitionDigest: `sha256:${row.definitionDigest.toString("hex")}` }
+        : {}),
+      startedAt: new Date(row.createdAt).toISOString(),
+      ...(row.finishedAt === null ? {} : { finishedAt: new Date(row.finishedAt).toISOString() }),
+      updatedAt: new Date(row.updatedAt).toISOString(),
+      status: row.status as WorkflowRunState["status"],
+      input: this.state.readJson(row.inputHash),
+      outputs,
+      results,
+      steps,
+      ...this.readUpdates(row.runId),
+      ...(activeAttempt === undefined ? {} : { currentNode: activeAttempt.nodeId }),
+      ...(activeAttempt === undefined ? {} : { currentAttemptId: activeAttempt.attemptId }),
+      ...(activeAttempt?.startedAt === null || activeAttempt === undefined
+        ? {}
+        : { currentNodeStartedAt: new Date(activeAttempt.startedAt).toISOString() }),
+      ...savedCurrentSettingsBinding(
+        activeAttempt?.settingsScopeId ?? null,
+        activeAttempt?.settingsChangeNumber ?? null,
+        activeAttempt?.settingsHash ?? null,
+      ),
+      ...(row.statusDetail === null ? {} : { statusDetail: row.statusDetail }),
+      ...(humanDecision === undefined ? {} : { humanDecision }),
+      ...(row.paused === 0 ? {} : { paused: true }),
+      ...(row.status === "waiting" && steps.at(-1) !== undefined
+        ? { waitingOn: steps.at(-1)?.nodeId as string }
+        : {}),
+      ...(row.finalOutputHash === null
+        ? {}
+        : { finalOutput: this.state.readJson(row.finalOutputHash) }),
+      ...(row.errorHash === null ? {} : { error: this.readText(row.errorHash) }),
+    };
+  }
+
+  private readSteps(runId: string): WorkflowStepRecord[] {
+    const rows = this.state.connection
+      .prepare(
+        `SELECT s.step_index AS stepIndex, a.attempt_id AS attemptId, a.node_id AS nodeId,
+                a.node_type AS nodeType, a.status,
+                a.prompt_hash AS promptHash, a.output_hash AS outputHash,
+                s.output_override_hash AS outputOverrideHash,
+                a.receipt_hash AS receiptHash, a.error_hash AS errorHash,
+                prompt_entry.entry_hash AS promptEntryHash,
+                response_entry.entry_hash AS responseEntryHash,
+                first_link.entry_id AS firstEntryId, last_link.entry_id AS lastEntryId,
+                a.settings_scope_id AS settingsScopeId,
+                a.settings_change_number AS settingsChangeNumber,
+                a.settings_hash AS settingsHash,
+                a.started_at AS startedAt, a.finished_at AS finishedAt
+         FROM run_steps s
+         JOIN node_attempts a ON a.attempt_id = s.attempt_id
+         LEFT JOIN attempt_entries prompt_link
+           ON prompt_link.attempt_id = a.attempt_id AND prompt_link.role = 'prompt'
+         LEFT JOIN session_entries prompt_entry
+           ON prompt_entry.segment_id = prompt_link.segment_id
+          AND prompt_entry.entry_id = prompt_link.entry_id
+         LEFT JOIN attempt_entries response_link
+           ON response_link.attempt_id = a.attempt_id AND response_link.role = 'response'
+         LEFT JOIN session_entries response_entry
+           ON response_entry.segment_id = response_link.segment_id
+          AND response_entry.entry_id = response_link.entry_id
+         LEFT JOIN attempt_entries first_link
+           ON first_link.attempt_id = a.attempt_id AND first_link.role = 'first'
+         LEFT JOIN attempt_entries last_link
+           ON last_link.attempt_id = a.attempt_id AND last_link.role = 'last'
+         WHERE s.run_id = ? ORDER BY s.step_index`,
+      )
+      .all(runId)
+      .filter(isStepRow);
+    return rows.map((row, index) => {
+      if (row.stepIndex !== index)
+        throw new Error(`Workflow run step sequence has a gap: ${runId}`);
+      const receipt =
+        row.receiptHash === null ? {} : this.readJsonAs<StoredAttemptReceipt>(row.receiptHash);
+      const prompt =
+        row.promptEntryHash !== null
+          ? promptFromEntry(this.state.readJson(row.promptEntryHash))
+          : row.promptHash === null
+            ? null
+            : this.readText(row.promptHash);
+      const outputHash = row.outputOverrideHash ?? row.outputHash;
+      const output =
+        outputHash !== null
+          ? this.state.readJson(outputHash)
+          : row.responseEntryHash === null
+            ? null
+            : assistantOutputFromEntry(
+                this.state.readJson(row.responseEntryHash),
+                receipt.assistantMessage?.maxChars,
+              );
+      const error = row.errorHash === null ? undefined : this.readText(row.errorHash);
+      const conversation =
+        row.firstEntryId === null || row.lastEntryId === null
+          ? undefined
+          : { firstEntryId: row.firstEntryId, lastEntryId: row.lastEntryId };
+      return {
+        attemptId: row.attemptId,
+        nodeId: row.nodeId,
+        nodeType: row.nodeType,
+        outcome: outcomeForStatus(row.status),
+        startedAt: new Date(row.startedAt).toISOString(),
+        finishedAt: new Date(row.finishedAt).toISOString(),
+        prompt,
+        output,
+        ...(error === undefined ? {} : { error }),
+        ...savedStepSettingsBinding(
+          row.settingsScopeId,
+          row.settingsChangeNumber,
+          row.settingsHash,
+        ),
+        ...receipt,
+        ...(conversation === undefined ? {} : { conversation }),
+      };
+    });
+  }
+
+  private readRunSources(
+    runId: string,
+    snapshot: WorkflowDefinitionSnapshot,
+  ): { root?: WorkflowSource; mounted: WorkflowMountedSource[] } {
+    const rows = this.state.connection
+      .prepare(
+        `SELECT mount_path AS mountPath, source_type AS sourceType,
+                source_ref AS sourceRef, source_revision AS sourceRevision
+         FROM run_sources WHERE run_id = ? ORDER BY mount_path`,
+      )
+      .all(runId)
+      .filter(isRunSourceRow);
+    const rootRow = rows.find((row) => row.mountPath === "");
+    const root =
+      rootRow === undefined ||
+      (rootRow.sourceType === "file" && rootRow.sourceRef.startsWith("inline:"))
+        ? undefined
+        : workflowSourceFromRow(rootRow);
+    const mountNames = new Map(
+      (snapshot.composition?.mounts ?? []).map((mount) => [
+        mount.mountPath.join("/"),
+        mount.workflowName,
+      ]),
+    );
+    const mounted = rows
+      .filter((row) => row.mountPath !== "")
+      .map((row) => ({
+        mountPath: row.mountPath.split("/"),
+        workflowName: mountNames.get(row.mountPath) ?? row.mountPath,
+        source: workflowSourceFromRow(row),
+      }));
+    return { ...(root === undefined ? {} : { root }), mounted };
+  }
+
+  private carriedStepCount(runId: string): number {
+    const row = this.state.connection
+      .prepare(
+        `SELECT count(*) AS count
+         FROM run_steps s JOIN node_attempts a ON a.attempt_id = s.attempt_id
+         WHERE s.run_id = ? AND a.run_id <> s.run_id`,
+      )
+      .get(runId);
+    return isCountRow(row) ? row.count : 0;
+  }
+
+  private readActiveAttempt(runId: string):
+    | {
+        attemptId: string;
+        nodeId: string;
+        startedAt: number | null;
+        settingsScopeId: string | null;
+        settingsChangeNumber: number | null;
+        settingsHash: Buffer | null;
+      }
+    | undefined {
+    const row = this.state.connection
+      .prepare(
+        `SELECT attempt_id AS attemptId, node_id AS nodeId, started_at AS startedAt,
+                settings_scope_id AS settingsScopeId,
+                settings_change_number AS settingsChangeNumber,
+                settings_hash AS settingsHash
+         FROM node_attempts
+         WHERE run_id = ? AND status IN ('pending', 'running', 'waiting', 'interrupted')`,
+      )
+      .get(runId);
+    return isActiveAttemptRow(row) ? row : undefined;
+  }
+
+  private readHumanDecisionReceipt(runId: string): HumanDecisionReceipt | undefined {
+    const row = this.state.connection
+      .prepare(
+        `SELECT d.request_hash AS requestHash, r.response_hash AS responseHash
+         FROM continuations c
+         JOIN human_decisions d ON d.decision_id = c.decision_id
+         JOIN human_decision_resolutions r ON r.decision_id = c.decision_id
+         WHERE c.continuation_run_id = ? AND r.outcome = 'accepted'`,
+      )
+      .get(runId);
+    if (!isDecisionReceiptRow(row)) return undefined;
+    const request = this.readJsonAs<Record<string, unknown>>(row.requestHash);
+    const decision = this.readJsonAs<Record<string, unknown>>(row.responseHash);
+    if (
+      typeof request.decisionId !== "string" ||
+      typeof request.requestDigest !== "string" ||
+      typeof request.nodeId !== "string" ||
+      typeof decision.provenance !== "string" ||
+      typeof decision.acceptedAt !== "string" ||
+      typeof decision.answerDigest !== "string" ||
+      typeof decision.subjectDigest !== "string" ||
+      typeof decision.presentationDigest !== "string" ||
+      typeof decision.revision !== "number" ||
+      decision.response === undefined
+    ) {
+      throw new Error(`Human decision receipt is invalid for run ${runId}`);
+    }
+    return {
+      schema: "pi-workflows.human-decision-receipt.v1",
+      decisionId: request.decisionId,
+      requestDigest: request.requestDigest,
+      nodeId: request.nodeId,
+      response: decision.response as HumanDecisionReceipt["response"],
+      provenance: decision.provenance === "timeout" ? "timeout" : "human",
+      acceptedAt: decision.acceptedAt,
+      answerDigest: decision.answerDigest,
+      subjectDigest: decision.subjectDigest,
+      presentationDigest: decision.presentationDigest,
+      revision: decision.revision,
+    };
+  }
+
+  private readUpdates(runId: string): Pick<WorkflowRunState, "updates"> {
+    const rows = this.state.connection
+      .prepare(
+        `SELECT u.update_id AS updateId, u.run_revision AS runRevision,
+                a.node_id AS nodeId, u.attempt_id AS attemptId,
+                u.update_type AS updateType, u.update_key AS updateKey,
+                u.data_hash AS dataHash, u.recorded_at AS recordedAt
+         FROM workflow_updates u
+         JOIN node_attempts a ON a.attempt_id = u.attempt_id
+         WHERE a.run_id = ? ORDER BY u.run_revision`,
+      )
+      .all(runId)
+      .filter(isUpdateRow);
+    if (rows.length === 0) return {};
+    let updates: WorkflowUpdateRecord[] | undefined;
+    for (const row of rows) {
+      updates = updateProjection(updates, {
+        updateId: row.updateId,
+        seq: row.runRevision,
+        at: new Date(row.recordedAt).toISOString(),
+        runId,
+        nodeId: row.nodeId,
+        attemptId: row.attemptId,
+        type: row.updateType,
+        key: row.updateKey,
+        data: this.readJsonAs<Record<string, unknown>>(row.dataHash),
+      });
+    }
+    return updates === undefined ? {} : { updates };
+  }
+
+  private readJsonAs<T>(hash: Buffer): T {
+    return this.state.readJson(hash) as T;
+  }
+
+  private readText(hash: Buffer): string {
+    const blob = this.state.readBlob(hash);
+    if (blob === undefined || blob.mediaType !== "text/plain") {
+      throw new Error("Text blob is missing or has the wrong media type");
+    }
+    return blob.content.toString("utf8");
   }
 
   private readDefinition(hash: Buffer): WorkflowDefinitionSnapshot {
@@ -1318,12 +3040,13 @@ function insertRunEvent(
   at: string,
   event: WorkflowTraceEventDraft | WorkflowTraceEvent,
 ): void {
+  const payload = compactTracePayload(event.type, event.payload);
   const payloadHash = state.putJson(
     {
       scope: event.scope,
       ...(event.nodeId === undefined ? {} : { nodeId: event.nodeId }),
       ...(event.attemptId === undefined ? {} : { attemptId: event.attemptId }),
-      payload: event.payload,
+      payload,
     },
     Date.parse(at),
   );
@@ -1339,6 +3062,40 @@ function insertRunEvent(
   );
 }
 
+function compactTracePayload(
+  eventType: string,
+  payload: Record<string, unknown>,
+): Record<string, unknown> {
+  if (eventType === "agent_prompt_sent" && Object.hasOwn(payload, "prompt")) {
+    const { prompt: _prompt, ...rest } = payload;
+    return { ...rest, promptStored: true };
+  }
+  if (eventType === "node_finished" || eventType === "node_failed") {
+    const {
+      output: _output,
+      action: _action,
+      assistantMessage: _assistantMessage,
+      conversation: _conversation,
+      error: _error,
+      ...rest
+    } = payload;
+    return { ...rest, ...(Object.hasOwn(payload, "output") ? { outputStored: true } : {}) };
+  }
+  if (eventType === "include_exited" && Object.hasOwn(payload, "output")) {
+    const { output: _output, ...rest } = payload;
+    return { ...rest, outputStored: true };
+  }
+  if (eventType === "run_started" && Object.hasOwn(payload, "input")) {
+    const { input: _input, ...rest } = payload;
+    return { ...rest, inputStored: true };
+  }
+  if (Object.hasOwn(payload, "finalOutput")) {
+    const { finalOutput: _finalOutput, ...rest } = payload;
+    return { ...rest, finalOutputStored: true };
+  }
+  return payload;
+}
+
 function insertGenericEvent(
   state: StateDatabase,
   resourceId: string,
@@ -1383,6 +3140,22 @@ function sourceForState(
   };
 }
 
+function sourceParts(source: WorkflowSource): {
+  type: "builtin" | "file";
+  ref: string;
+  revision: string;
+} {
+  return source.kind === "builtin"
+    ? { type: "builtin", ref: source.id, revision: source.revision }
+    : { type: "file", ref: source.path, revision: source.hash };
+}
+
+function workflowSourceFromRow(row: RunSourceRow): WorkflowSource {
+  return row.sourceType === "builtin"
+    ? { kind: "builtin", id: row.sourceRef, revision: row.sourceRevision }
+    : { kind: "file", path: row.sourceRef, hash: row.sourceRevision };
+}
+
 function segmentIdFor(runId: string, attemptId?: string): string {
   return `segment-${createHash("sha256")
     .update(`${runId}\0${attemptId ?? ""}`)
@@ -1407,6 +3180,74 @@ function outcomeStatus(outcome: string): string {
   }
 }
 
+function outcomeForStatus(status: string): WorkflowStepRecord["outcome"] {
+  switch (status) {
+    case "completed":
+      return "ok";
+    case "timed_out":
+      return "timed_out";
+    case "cancelled":
+      return "cancelled";
+    case "failed":
+      return "failed";
+    default:
+      throw new Error(`Workflow step has nonterminal status: ${status}`);
+  }
+}
+
+function attemptReceipt(step: WorkflowStepRecord): StoredAttemptReceipt {
+  return {
+    ...(step.action === undefined ? {} : { action: step.action }),
+    ...(step.assistantMessage === undefined ? {} : { assistantMessage: step.assistantMessage }),
+  };
+}
+
+function promptFromEntry(value: unknown): string | null {
+  if (!isRecord(value)) return null;
+  const content = value.content;
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return null;
+  return content
+    .filter(isRecord)
+    .map((part) => (typeof part.text === "string" ? part.text : ""))
+    .filter((text) => text.length !== 0)
+    .join("\n");
+}
+
+function assistantOutputFromEntry(value: unknown, maxChars?: number): string {
+  if (!isRecord(value) || !isRecord(value.message)) {
+    throw new Error("Assistant response entry is invalid");
+  }
+  const message = value.message;
+  if (message.role !== "assistant" || !Array.isArray(message.content)) {
+    throw new Error("Assistant response entry does not contain an assistant message");
+  }
+  const text = message.content
+    .filter(isRecord)
+    .filter((part) => part.type === "text" && typeof part.text === "string")
+    .map((part) => part.text as string)
+    .join("\n");
+  if (text.trim().length === 0) throw new Error("Assistant response entry has no visible text");
+  if (maxChars !== undefined && text.length > maxChars) {
+    throw new Error(`Assistant response exceeds its stored limit of ${maxChars} characters`);
+  }
+  return text;
+}
+
+function resultForStep(step: WorkflowStepRecord): WorkflowNodeResult {
+  return {
+    attemptId: step.attemptId,
+    nodeId: step.nodeId,
+    nodeType: step.nodeType,
+    outcome: step.outcome,
+    startedAt: step.startedAt,
+    finishedAt: step.finishedAt,
+    durationMs: Date.parse(step.finishedAt) - Date.parse(step.startedAt),
+    ...(step.outcome === "ok" ? { output: step.output } : {}),
+    ...(step.error === undefined ? {} : { error: step.error }),
+  };
+}
+
 function traceScope(value: unknown): WorkflowTraceEvent["scope"] {
   return value === "node" || value === "agent" || value === "action" || value === "session"
     ? value
@@ -1438,6 +3279,12 @@ function validateSessionEventRecord(record: WorkflowSessionEventRecord): void {
   ) {
     throw new Error("Session event is missing required envelope fields");
   }
+  if (
+    record.type === "assistant_event" &&
+    ["text_delta", "thinking_delta", "toolcall_delta"].includes(String(record.payload.type))
+  ) {
+    throw new Error("Incremental assistant events are not durable session facts");
+  }
 }
 
 function validateSessionCapture(capture: WorkflowSessionCapture): void {
@@ -1462,6 +3309,178 @@ function validateSessionCapture(capture: WorkflowSessionCapture): void {
   }
 }
 
+function followUpIdFor(runId: string, requestId: string): string {
+  const digest = createHash("sha256").update(`${runId}\0${requestId}`).digest("hex").slice(0, 40);
+  return `follow-up-${digest}`;
+}
+
+function assertRequestId(requestId: string): void {
+  if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,511}$/u.test(requestId)) {
+    throw new Error("Workflow request ID must be a stable identifier of at most 512 characters");
+  }
+}
+
+function assertSourceType(source: string): void {
+  if (typeof source !== "string" || source.trim().length === 0 || source.length > 128) {
+    throw new Error("Workflow change source must be a non-empty string of at most 128 characters");
+  }
+}
+
+function assertActorType(value: string): ActorType {
+  if (
+    value !== "session" &&
+    value !== "host" &&
+    value !== "controller" &&
+    value !== "channel" &&
+    value !== "human" &&
+    value !== "policy" &&
+    value !== "control" &&
+    value !== "system"
+  ) {
+    throw new Error(`Unknown saved actor type: ${value}`);
+  }
+  return value;
+}
+
+function assertFollowUpState(value: string): WorkflowFollowUpState {
+  if (
+    value !== "queued" &&
+    value !== "pending_presentation" &&
+    value !== "ready" &&
+    value !== "sent" &&
+    value !== "removed" &&
+    value !== "cancelled"
+  ) {
+    throw new Error(`Unknown workflow follow-up state: ${value}`);
+  }
+  return value;
+}
+
+function assertPresentationState(value: string): WorkflowPresentationState {
+  if (
+    value !== "none" &&
+    value !== "not-needed" &&
+    value !== "pending" &&
+    value !== "settled" &&
+    value !== "unavailable"
+  ) {
+    throw new Error(`Unknown workflow presentation state: ${value}`);
+  }
+  return value;
+}
+
+function isSettingsScopeRow(value: unknown): value is SettingsScopeRow {
+  return (
+    isRecord(value) &&
+    typeof value.scopeId === "string" &&
+    typeof value.resourceId === "string" &&
+    typeof value.originRunId === "string" &&
+    typeof value.activeRunId === "string" &&
+    typeof value.mountPath === "string" &&
+    typeof value.invocation === "number" &&
+    Buffer.isBuffer(value.currentHash) &&
+    typeof value.revision === "number" &&
+    typeof value.createdAt === "number" &&
+    typeof value.updatedAt === "number"
+  );
+}
+
+function isSettingsProjectionRow(value: unknown): value is SettingsProjectionRow {
+  return (
+    isRecord(value) &&
+    typeof value.scopeId === "string" &&
+    Buffer.isBuffer(value.initialHash) &&
+    Buffer.isBuffer(value.currentHash) &&
+    typeof value.revision === "number"
+  );
+}
+
+function isSettingsProjectionChangeRow(value: unknown): value is SettingsProjectionChangeRow {
+  return (
+    isRecord(value) &&
+    typeof value.changeNumber === "number" &&
+    Buffer.isBuffer(value.patchHash) &&
+    Buffer.isBuffer(value.beforeHash) &&
+    Buffer.isBuffer(value.afterHash)
+  );
+}
+
+function isSettingsChangeRow(value: unknown): value is SettingsChangeRow {
+  return (
+    isRecord(value) &&
+    typeof value.changeId === "string" &&
+    typeof value.scopeId === "string" &&
+    typeof value.requestId === "string" &&
+    typeof value.changeNumber === "number" &&
+    typeof value.actorType === "string" &&
+    (typeof value.actorId === "string" || value.actorId === null) &&
+    typeof value.sourceType === "string" &&
+    Buffer.isBuffer(value.patchHash) &&
+    Buffer.isBuffer(value.beforeHash) &&
+    Buffer.isBuffer(value.afterHash) &&
+    typeof value.acceptedAt === "number"
+  );
+}
+
+function isFollowUpQueueRow(value: unknown): value is FollowUpQueueRow {
+  return (
+    isRecord(value) &&
+    typeof value.runId === "string" &&
+    typeof value.resourceId === "string" &&
+    (typeof value.originSessionId === "string" || value.originSessionId === null) &&
+    typeof value.presentationState === "string" &&
+    (typeof value.presentationEntryId === "string" || value.presentationEntryId === null) &&
+    (typeof value.presentationAssistantEntryId === "string" ||
+      value.presentationAssistantEntryId === null) &&
+    (Buffer.isBuffer(value.presentationReasonHash) || value.presentationReasonHash === null) &&
+    typeof value.revision === "number"
+  );
+}
+
+function isFollowUpRow(value: unknown): value is FollowUpRow {
+  return (
+    isRecord(value) &&
+    typeof value.followUpId === "string" &&
+    typeof value.resourceId === "string" &&
+    typeof value.queueResourceId === "string" &&
+    typeof value.runId === "string" &&
+    typeof value.requestId === "string" &&
+    typeof value.orderNumber === "number" &&
+    typeof value.targetSessionId === "string" &&
+    typeof value.actorType === "string" &&
+    (typeof value.actorId === "string" || value.actorId === null) &&
+    typeof value.sourceType === "string" &&
+    Buffer.isBuffer(value.promptHash) &&
+    typeof value.status === "string" &&
+    (typeof value.sessionEntryId === "string" || value.sessionEntryId === null) &&
+    (Buffer.isBuffer(value.reasonHash) || value.reasonHash === null) &&
+    typeof value.createdAt === "number" &&
+    typeof value.updatedAt === "number" &&
+    (typeof value.sentAt === "number" || value.sentAt === null) &&
+    typeof value.revision === "number"
+  );
+}
+
+function isParentRunRow(value: unknown): value is { parentRunId: string | null } {
+  return isRecord(value) && (typeof value.parentRunId === "string" || value.parentRunId === null);
+}
+
+function isStatusRow(value: unknown): value is { status: string } {
+  return isRecord(value) && typeof value.status === "string";
+}
+
+function isCountRow(value: unknown): value is { count: number } {
+  return isRecord(value) && typeof value.count === "number";
+}
+
+function isLeaseExpiryRow(value: unknown): value is { expiresAt: number | null } {
+  return isRecord(value) && (typeof value.expiresAt === "number" || value.expiresAt === null);
+}
+
+function isNextOrderRow(value: unknown): value is { nextOrder: number } {
+  return isRecord(value) && typeof value.nextOrder === "number";
+}
+
 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)}`);
@@ -1476,10 +3495,108 @@ function isRunRow(value: unknown): value is RunRow {
   return isRecord(value);
 }
 
+function savedCurrentSettingsBinding(
+  scopeId: string | null,
+  changeNumber: number | null,
+  settingsHash: Buffer | null,
+): Pick<
+  WorkflowRunState,
+  "currentSettingsScopeId" | "currentSettingsChangeNumber" | "currentSettingsHash"
+> {
+  if (scopeId === null && changeNumber === null && settingsHash === null) return {};
+  if (scopeId === null || changeNumber === null || settingsHash === null) {
+    throw new Error("Saved current workflow settings binding is incomplete");
+  }
+  return {
+    currentSettingsScopeId: scopeId,
+    currentSettingsChangeNumber: changeNumber,
+    currentSettingsHash: settingsHash.toString("hex"),
+  };
+}
+
+function savedStepSettingsBinding(
+  scopeId: string | null,
+  changeNumber: number | null,
+  settingsHash: Buffer | null,
+): Pick<WorkflowStepRecord, "settingsScopeId" | "settingsChangeNumber" | "settingsHash"> {
+  if (scopeId === null && changeNumber === null && settingsHash === null) return {};
+  if (scopeId === null || changeNumber === null || settingsHash === null) {
+    throw new Error("Saved workflow step settings binding is incomplete");
+  }
+  return {
+    settingsScopeId: scopeId,
+    settingsChangeNumber: changeNumber,
+    settingsHash: settingsHash.toString("hex"),
+  };
+}
+
 function isRunIdRow(value: unknown): value is { runId: string } {
   return isRecord(value);
 }
 
+function isRunStepIdentityRow(value: unknown): value is {
+  stepIndex: number;
+  attemptId: string;
+} {
+  return isRecord(value);
+}
+
+function isStepRow(value: unknown): value is StepRow {
+  return isRecord(value);
+}
+
+function isRunSourceRow(value: unknown): value is RunSourceRow {
+  return isRecord(value);
+}
+
+function isSegmentIdentityRow(value: unknown): value is { segmentId: string; entryHash: Buffer } {
+  return isRecord(value) && typeof value.segmentId === "string" && Buffer.isBuffer(value.entryHash);
+}
+
+function isEntryIdentityRow(value: unknown): value is { entryId: string } {
+  return isRecord(value) && typeof value.entryId === "string";
+}
+
+function isAttemptValueRow(value: unknown): value is {
+  outputHash: Buffer | null;
+  receiptHash: Buffer | null;
+  responseEntryHash: Buffer | null;
+} {
+  return isRecord(value);
+}
+
+function isActiveAttemptRow(value: unknown): value is {
+  attemptId: string;
+  nodeId: string;
+  startedAt: number | null;
+  settingsScopeId: string | null;
+  settingsChangeNumber: number | null;
+  settingsHash: Buffer | null;
+} {
+  return isRecord(value);
+}
+
+function isDecisionReceiptRow(value: unknown): value is {
+  requestHash: Buffer;
+  responseHash: Buffer;
+} {
+  return (
+    isRecord(value) && Buffer.isBuffer(value.requestHash) && Buffer.isBuffer(value.responseHash)
+  );
+}
+
+function isContinuationIdentityRow(value: unknown): value is {
+  parentRunId: string;
+  continuationRunId: string;
+  createdAt: number;
+} {
+  return isRecord(value);
+}
+
+function isUpdateRow(value: unknown): value is UpdateRow {
+  return isRecord(value);
+}
+
 function isRevisionRow(value: unknown): value is { revision: number } {
   return isRecord(value);
 }
@@ -1519,7 +3636,15 @@ function isLeaseAuthorityRow(value: unknown): value is {
 }
 
 export function createDefinitionSnapshot(workflow: WorkflowDefinition): WorkflowDefinitionSnapshot {
-  const composition = compositionMetadata(workflow)?.snapshot;
+  const metadata = compositionMetadata(workflow);
+  const composition = metadata?.snapshot;
+  const settingsScopes = Object.values(metadata?.scopes ?? {})
+    .filter((scope) => scope.path !== "" && scope.settings !== undefined)
+    .sort((left, right) => left.path.localeCompare(right.path))
+    .map((scope) => ({
+      mountPath: scope.path.split("/"),
+      settings: snapshotSettings(scope.settings!),
+    }));
   return {
     schema: DEFINITION_SNAPSHOT_SCHEMA,
     name: workflow.name,
@@ -1533,6 +3658,8 @@ export function createDefinitionSnapshot(workflow: WorkflowDefinition): Workflow
     ),
     edges: structuredClone(workflow.edges),
     ...(composition !== undefined ? { composition: structuredClone(composition) } : {}),
+    ...(workflow.settings !== undefined ? { settings: snapshotSettings(workflow.settings) } : {}),
+    ...(settingsScopes.length > 0 ? { settingsScopes } : {}),
   };
 }
 
@@ -1573,6 +3700,9 @@ function snapshotNode(
   if (node.nodeType === "agent" && node.expectedOutput !== undefined) {
     common.expectedOutput = node.expectedOutput;
   }
+  if (node.nodeType === "compute" && node.settingsRoute === true) {
+    common.settingsRoute = true;
+  }
   if (node.nodeType === "notify") common.summary = node.kind ?? "progress";
   if (node.nodeType === "checkpoint" && node.summary !== undefined) common.summary = node.summary;
   if (node.nodeType === "checkpoint" && node.humanDecision !== undefined) {
@@ -1591,3 +3721,20 @@ function snapshotNode(
   if (node.nodeType === "action") common.actionExecution = "exec" in node ? "shell" : "function";
   return common;
 }
+
+function snapshotSettings(
+  settings: NonNullable<WorkflowDefinition["settings"]>,
+): WorkflowSettingsSnapshot {
+  return {
+    ...(settings.description !== undefined ? { description: settings.description } : {}),
+    paths: settings.paths.map((rule) => ({
+      path: rule.path,
+      permissions: Object.fromEntries(
+        Object.entries(rule.permissions).map(([permission, actors]) => [
+          permission,
+          actors === undefined ? [] : [...actors],
+        ]),
+      ),
+    })),
+  };
+}