@osolmaz/pi-workflows 0.14.0 → 0.15.0

package/src/viewer/cli.ts

@@ -4,6 +4,7 @@ import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { SqliteControllerStore } from "../controllers/sqlite.js";
 import { syncHerdrPlugin } from "../herdr/setup.js";
+import { WorkflowHostClient } from "../host/client.js";
 import { sanitizeText } from "../render/ansi.js";
 import { StateDatabase } from "../state/database.js";
 import { pruneState } from "../state/prune.js";
@@ -28,7 +29,10 @@ Usage:
   pi-workflows state backup <destination>
   pi-workflows state prune --before <timestamp> --dry-run
   pi-workflows state prune --before <timestamp> --backup <absolute-path> --apply
-  pi-workflows host [--project <dir>] [-- <extra pi args>]
+  pi-workflows host start
+  pi-workflows host status
+  pi-workflows host stop
+  pi-workflows host run [-- <extra pi args>]
   pi-workflows herdr sync [--json]
   pi-workflows herdr setup [--json]
 
@@ -41,13 +45,13 @@ export type CliArgs = {
   controllerName?: string;
   resourceKey?: string;
   herdrAction?: string;
+  hostAction?: "start" | "status" | "stop" | "run";
   stateAction?: "status" | "verify" | "backup" | "prune";
   backupDestination?: string;
   pruneBefore?: string;
   pruneApply?: boolean;
   once: boolean;
   json: boolean;
-  project?: string | undefined;
   piArgs?: string[] | undefined;
 };
 
@@ -80,7 +84,18 @@ export function parseCliArgs(argv: string[]): CliArgs {
   }
 
   if (command !== "herdr" && json) throw new Error("--json is available only for herdr sync");
-  if (command === "host") return { command, once, json, project, piArgs };
+  if (command === "host") {
+    if (project !== undefined) throw new Error("The global host does not accept --project");
+    const action = positionals[0];
+    if (action !== "start" && action !== "status" && action !== "stop" && action !== "run") {
+      throw new Error("host requires start, status, stop, or run");
+    }
+    if (positionals.length !== 1) throw new Error("host accepts one lifecycle action");
+    if (piArgs.length > 0 && action !== "run") {
+      throw new Error("Extra Pi arguments are available only for host run");
+    }
+    return { command, hostAction: action, once, json, piArgs };
+  }
   if (command === "controller") {
     if (positionals.length !== 2) throw new Error("controller requires <controller> and <key>");
     return {
@@ -266,7 +281,9 @@ export async function main(argv = process.argv.slice(2)): Promise<number> {
       await runStateCommand(databasePath, args);
       return 0;
     }
-    if (args.command === "host") return await runHost(args.project ?? process.cwd(), args.piArgs);
+    if (args.command === "host") {
+      return await runHost(args.hostAction as "start" | "status" | "stop" | "run", args.piArgs);
+    }
     if (args.command === "herdr") {
       const result = syncHerdrPlugin(packageRoot());
       process.stdout.write(args.json ? `${JSON.stringify(result)}\n` : `${result.message}\n`);
@@ -333,20 +350,35 @@ async function runStateCommand(databasePath: string, args: CliArgs): Promise<voi
   }
 }
 
-async function runHost(project: string, piArgs: string[] | undefined): Promise<number> {
-  const { WorkflowHost } = await import("../host/runner.js");
-  const host = new WorkflowHost({
-    cwd: project,
-    piArgs: piArgs ?? [],
-    onLog: (message) => process.stdout.write(`[host] ${message}\n`),
-  });
-  await host.start();
-  await new Promise<void>((resolve) => {
-    const shutdown = () => void host.stop().then(resolve);
-    process.once("SIGTERM", shutdown);
-    process.once("SIGINT", shutdown);
+async function runHost(
+  action: "start" | "status" | "stop" | "run",
+  piArgs: string[] | undefined,
+): Promise<number> {
+  if (action === "run") {
+    const { WorkflowHost } = await import("../host/runner.js");
+    const host = new WorkflowHost({
+      piArgs: piArgs ?? [],
+      onLog: (message) => process.stdout.write(`[host] ${message}\n`),
+    });
+    await host.start();
+    await new Promise<void>((resolve) => {
+      const shutdown = () => void host.stop().then(resolve);
+      process.once("SIGTERM", shutdown);
+      process.once("SIGINT", shutdown);
+    });
+    return 0;
+  }
+  const client = new WorkflowHostClient();
+  if (action === "start") {
+    const response = await client.ensureRunning();
+    process.stdout.write(`${JSON.stringify(response.receipt ?? {})}\n`);
+    return response.outcome === "accepted" || response.outcome === "adopted" ? 0 : 1;
+  }
+  const response = await client.request({
+    operation: action === "status" ? "host.status" : "host.stop",
   });
-  return 0;
+  process.stdout.write(`${JSON.stringify(response.receipt ?? {})}\n`);
+  return response.outcome === "accepted" || response.outcome === "adopted" ? 0 : 1;
 }
 
 function openControllerStore(databasePath: string): SqliteControllerStore | undefined {

package/src/workflows/composition.ts

@@ -14,6 +14,7 @@ import type {
   WorkflowEdge,
   WorkflowExitDefinition,
   WorkflowIncludeDefinition,
+  WorkflowManagedEffect,
   WorkflowMountedSource,
   WorkflowMountSnapshot,
   WorkflowNodeContext,
@@ -539,10 +540,18 @@ function wrapNode(
         return {
           ...common,
           nodeType: "action",
-          exec: (context) => shell.exec(project(context)),
+          ...(wrappedEffect(shell, project) === undefined
+            ? {}
+            : { effect: wrappedEffect(shell, project) }),
+          exec: (context) =>
+            shell.exec(projectActionContext(context, scopePath, scopes, entries, exits)),
           ...(shell.parse !== undefined
             ? {
-                parse: (result, context) => shell.parse?.(result, project(context)),
+                parse: (result, context) =>
+                  shell.parse?.(
+                    result,
+                    projectActionContext(context, scopePath, scopes, entries, exits),
+                  ),
               }
             : {}),
           ...(shell.updates !== undefined
@@ -564,6 +573,9 @@ function wrapNode(
       return {
         ...common,
         nodeType: "action",
+        ...(wrappedEffect(node, project) === undefined
+          ? {}
+          : { effect: wrappedEffect(node, project) }),
         run: (context) =>
           (node as FunctionActionNodeDefinition).run(
             projectActionContext(context, scopePath, scopes, entries, exits),
@@ -572,6 +584,27 @@ function wrapNode(
   }
 }
 
+function wrappedEffect(
+  node: ActionNodeDefinition,
+  project: (context: WorkflowNodeContext) => WorkflowNodeContext,
+): WorkflowManagedEffect | undefined {
+  if (node.effect === undefined) return undefined;
+  const idempotencyKey = node.effect.idempotencyKey;
+  const request = node.effect.request;
+  return {
+    type: node.effect.type,
+    recovery: node.effect.recovery,
+    idempotencyKey:
+      typeof idempotencyKey === "function"
+        ? (context: WorkflowNodeContext) => idempotencyKey(project(context))
+        : idempotencyKey,
+    request:
+      typeof request === "function"
+        ? (context: WorkflowNodeContext) => request(project(context))
+        : request,
+  };
+}
+
 function projectActionContext(
   context: WorkflowActionContext,
   scopePath: string,
@@ -581,6 +614,7 @@ function projectActionContext(
 ): WorkflowActionContext {
   return {
     ...projectWorkflowContext(context, scopePath, scopes, entries, exits),
+    effect: context.effect,
     publishUpdate: context.publishUpdate,
   };
 }

package/src/workflows/definition.ts

@@ -25,6 +25,7 @@ import type {
   WorkflowIncludedResult,
   WorkflowIncludeMap,
   WorkflowInputOf,
+  WorkflowManagedEffect,
   WorkflowNodeContext,
   WorkflowNodeDefinition,
   WorkflowSettingsOf,
@@ -171,6 +172,37 @@ export function isWorkflowDefinition(value: unknown): value is WorkflowDefinitio
   );
 }
 
+export function manualEffect(type: string): WorkflowManagedEffect {
+  return workflowEffect(type, "manual");
+}
+
+export function idempotentEffect(type: string): WorkflowManagedEffect {
+  return workflowEffect(type, "idempotent");
+}
+
+function workflowEffect(
+  type: string,
+  recovery: WorkflowManagedEffect["recovery"],
+): WorkflowManagedEffect {
+  const normalized = type.trim();
+  if (normalized.length === 0 || normalized.length > 256) {
+    throw new Error("Managed effect type must be nonempty text of at most 256 characters");
+  }
+  return {
+    type: normalized,
+    recovery,
+    idempotencyKey: ({ state }: WorkflowNodeContext) => {
+      const nodeId = state.currentNode;
+      if (nodeId === undefined) {
+        throw new Error("Managed effect resolution requires an active workflow node");
+      }
+      const nodeInvocation = state.steps.filter((step) => step.nodeId === nodeId).length + 1;
+      return `${state.runId}:${normalized}:${nodeId}:${nodeInvocation}`;
+    },
+    request: ({ input, outputs }: WorkflowNodeContext) => ({ input, outputs }),
+  };
+}
+
 export function assistantMessage(options: { maxChars?: number } = {}): AssistantMessageOutput {
   if (options === null || typeof options !== "object" || Array.isArray(options)) {
     throw new Error("Invalid workflow definition: assistantMessage options must be an object");

package/src/workflows/engine.ts

@@ -1,6 +1,6 @@
 import { createHash, randomUUID } from "node:crypto";
 import { isDeepStrictEqual } from "node:util";
-import { canonicalJson } from "../state/json.js";
+import { canonicalJson, type JsonValue } from "../state/json.js";
 import { StaleResourceError } from "../state/mutation.js";
 import {
   compileWorkflowDefinition,
@@ -18,11 +18,7 @@ import {
   WorkflowSourceChangedError,
 } from "./errors.js";
 import { resolveNext, resolveNextForOutcome, validateWorkflowDefinition } from "./graph.js";
-import {
-  HumanDecisionStore,
-  createHumanDecisionRequest,
-  validateHumanDecisionResponse,
-} from "./human-decision.js";
+import { createHumanDecisionRequest, validateHumanDecisionResponse } from "./human-decision.js";
 import { extractJsonValue } from "./json.js";
 import {
   parseWorkflowSettingsValue,
@@ -35,6 +31,7 @@ import {
   WorkflowRunStore,
   createDefinitionSnapshot,
   createRunId,
+  type WorkflowExecutionStore,
 } from "./store.js";
 import type {
   ResolvedHumanDecision,
@@ -104,6 +101,7 @@ type ResumedNodeAttempt = {
   nodeId: string;
   attemptId: string;
   startedAt: string;
+  deadlineAt?: string | null;
   settings?: WorkflowSettingsScopeRecord;
 };
 
@@ -116,7 +114,7 @@ type ResumedNodeAttempt = {
 export class WorkflowEngine {
   private readonly executor: AgentStepExecutor;
   private readonly notificationSink: WorkflowNotificationSink | undefined;
-  private readonly store: WorkflowRunStore;
+  private readonly store: WorkflowExecutionStore;
   private readonly defaultNodeTimeoutMs: number;
   private readonly maxSteps: number;
   private readonly onEvent?: WorkflowEngineOptions["onEvent"];
@@ -306,6 +304,7 @@ export class WorkflowEngine {
     try {
       await this.executeGraph(workflow, state, runId);
     } catch (error) {
+      if (isClaimLostError(error)) throw error;
       if (isRunParkedError(error) || this.parked) {
         return { runId, state };
       }
@@ -323,7 +322,11 @@ export class WorkflowEngine {
   async resumeRun(
     workflow: WorkflowDefinition,
     runId: string,
-    options: { workflowSource?: WorkflowSource; force?: boolean } = {},
+    options: {
+      workflowSource?: WorkflowSource;
+      force?: boolean;
+      resumeInteractionAttemptId?: string;
+    } = {},
   ): Promise<WorkflowRunResult> {
     workflow = isCompiledWorkflow(workflow) ? workflow : compileWorkflowDefinition(workflow);
     validateWorkflowDefinition(workflow);
@@ -349,25 +352,30 @@ export class WorkflowEngine {
       state.currentAttemptId !== undefined &&
       state.currentNodeStartedAt !== undefined &&
       interruptedNode?.nodeType === "agent" &&
-      assistantMessageConfig(interruptedNode) !== undefined
+      (assistantMessageConfig(interruptedNode) !== undefined ||
+        options.resumeInteractionAttemptId === state.currentAttemptId)
     ) {
-      const resumedSettings = this.persistedSettingsBinding(state);
+      const resumedSettings = await this.persistedSettingsBinding(state);
       resumedAttempt = {
         nodeId: state.currentNode,
         attemptId: state.currentAttemptId,
         startedAt: state.currentNodeStartedAt,
+        ...(state.currentNodeDeadlineAt === undefined
+          ? {}
+          : { deadlineAt: state.currentNodeDeadlineAt }),
         ...(resumedSettings !== undefined ? { settings: resumedSettings } : {}),
       };
     }
-    // A resumed run starts unpaused. Submitted and non-agent nodes discard
-    // stale in-flight markers and start a new attempt. Assistant-message
-    // nodes keep their attempt id so the origin session can adopt an already
-    // visible response without showing it twice.
+    // A resumed run starts unpaused. Submitted and non-agent nodes normally
+    // discard stale in-flight markers and start a new attempt. A submitted
+    // interaction and an assistant-message node keep their exact attempt id
+    // so durable origin-session work is never detached from its contract.
     delete state.paused;
     if (resumedAttempt === undefined) {
       delete state.currentNode;
       delete state.currentAttemptId;
       delete state.currentNodeStartedAt;
+      delete state.currentNodeDeadlineAt;
       delete state.currentSettingsScopeId;
       delete state.currentSettingsChangeNumber;
       delete state.currentSettingsHash;
@@ -416,6 +424,7 @@ export class WorkflowEngine {
         resumedAttempt,
       );
     } catch (error) {
+      if (isClaimLostError(error)) throw error;
       if (isRunParkedError(error) || this.parked) {
         return { runId, state };
       }
@@ -447,7 +456,7 @@ export class WorkflowEngine {
     this.cancelled = false;
     this.paused = false;
     this.parked = false;
-    const parent = this.store.readRun(parentRunId);
+    const parent = await this.store.readRun(parentRunId);
     if (parent === null) {
       throw new Error(`Cannot continue from unreadable workflow run: ${parentRunId}`);
     }
@@ -480,9 +489,7 @@ export class WorkflowEngine {
       ) {
         throw new Error("Accepted human decision does not match the waiting request");
       }
-      const durableDecision = await new HumanDecisionStore(this.store.databasePath, {
-        state: this.store.state,
-      }).readResolved(request.decisionId);
+      const durableDecision = await this.store.readResolvedHumanDecision(request.decisionId);
       if (durableDecision === null || !isDeepStrictEqual(durableDecision, options.humanDecision)) {
         throw new Error("Accepted human decision does not match the durable decision record");
       }
@@ -572,6 +579,7 @@ export class WorkflowEngine {
         point.lastOutput,
       );
     } catch (error) {
+      if (isClaimLostError(error)) throw error;
       if (isRunParkedError(error) || this.parked) {
         return { runId, state };
       }
@@ -992,6 +1000,7 @@ export class WorkflowEngine {
     delete state.currentNode;
     delete state.currentAttemptId;
     delete state.currentNodeStartedAt;
+    delete state.currentNodeDeadlineAt;
     delete state.currentSettingsScopeId;
     delete state.currentSettingsChangeNumber;
     delete state.currentSettingsHash;
@@ -1055,6 +1064,7 @@ export class WorkflowEngine {
         node,
         meta,
         settings,
+        resumedAttempt?.deadlineAt,
       );
       return {
         result: this.createNodeResult(nodeId, node, attemptId, startedAt, "ok", execution.output),
@@ -1062,6 +1072,7 @@ export class WorkflowEngine {
         ...(settings !== undefined ? { settings } : {}),
       };
     } catch (error) {
+      if (isRunParkedError(error) || isClaimLostError(error)) throw error;
       const outcome = this.outcomeForError(error);
       return {
         result: {
@@ -1121,6 +1132,7 @@ export class WorkflowEngine {
     node: WorkflowNodeDefinition,
     meta: NodeExecutionMeta,
     settings?: WorkflowSettingsScopeRecord,
+    persistedDeadlineAt?: string | null,
   ): Promise<NodeExecution> {
     const abort = new AbortController();
     const context = this.createNodeContext(state, abort.signal, settings);
@@ -1137,13 +1149,49 @@ export class WorkflowEngine {
         throw new CancelledError();
       }
 
-      const timeoutMs = await this.resolveNodeTimeout(node, context, abort);
+      let timeoutMs: number | null;
+      let timeoutErrorMs: number | null;
+      if (persistedDeadlineAt === undefined) {
+        timeoutMs = await this.resolveNodeTimeout(node, context, abort);
+        timeoutErrorMs = timeoutMs;
+        if (node.nodeType === "agent" && this.executor.preservesDeadlineWhileParked === true) {
+          state.currentNodeDeadlineAt =
+            timeoutMs === null ? null : new Date(Date.now() + timeoutMs).toISOString();
+          await this.persist(runId, state, {
+            scope: "node",
+            type: "node_deadline_set",
+            nodeId,
+            attemptId,
+            payload: { deadlineAt: state.currentNodeDeadlineAt },
+          });
+          if (state.currentNodeDeadlineAt !== null && timeoutErrorMs !== null) {
+            timeoutMs = Date.parse(state.currentNodeDeadlineAt) - Date.now();
+            if (timeoutMs <= 0) throw new TimeoutError(timeoutErrorMs);
+          }
+        } else {
+          delete state.currentNodeDeadlineAt;
+        }
+      } else if (persistedDeadlineAt === null) {
+        state.currentNodeDeadlineAt = null;
+        timeoutMs = null;
+        timeoutErrorMs = null;
+      } else {
+        const deadline = Date.parse(persistedDeadlineAt);
+        const started = Date.parse(state.currentNodeStartedAt ?? persistedDeadlineAt);
+        if (!Number.isFinite(deadline) || !Number.isFinite(started)) {
+          throw new Error("Persisted node deadline is invalid");
+        }
+        state.currentNodeDeadlineAt = persistedDeadlineAt;
+        timeoutMs = deadline - Date.now();
+        timeoutErrorMs = Math.max(1, deadline - started);
+        if (timeoutMs <= 0) throw new TimeoutError(timeoutErrorMs);
+      }
       if (abort.signal.aborted) {
         throw abortError(abort.signal);
       }
-      if (timeoutMs !== null) {
+      if (timeoutMs !== null && timeoutErrorMs !== null) {
         timer = setTimeout(() => {
-          abort.abort(new TimeoutError(timeoutMs));
+          abort.abort(new TimeoutError(timeoutErrorMs));
         }, timeoutMs);
       }
       this.activeAttempt = {
@@ -1323,7 +1371,7 @@ export class WorkflowEngine {
     }
     if (definition === undefined) return undefined;
     const invocation = mountPath === "" ? 1 : currentMountInvocation(state, mountPath);
-    const existing = this.store.findSettingsScope(state.runId, mountPath, invocation);
+    const existing = await this.store.findSettingsScope(state.runId, mountPath, invocation);
     if (existing !== undefined) return existing;
     const input = mountPath === "" ? state.input : currentMountInput(state, mountPath);
     const mappedSettings =
@@ -1331,7 +1379,7 @@ export class WorkflowEngine {
     const initial = mappedSettings.present
       ? await parseWorkflowSettingsValue(definition, mappedSettings.value)
       : await resolveInitialWorkflowSettings(definition, input);
-    return this.store.ensureSettingsScope({
+    return await this.store.ensureSettingsScope({
       runId: state.runId,
       mountPath,
       invocation,
@@ -1339,9 +1387,9 @@ export class WorkflowEngine {
     });
   }
 
-  private persistedSettingsBinding(
+  private async persistedSettingsBinding(
     state: WorkflowRunState,
-  ): WorkflowSettingsScopeRecord | undefined {
+  ): Promise<WorkflowSettingsScopeRecord | undefined> {
     if (state.currentSettingsScopeId === undefined) return undefined;
     if (
       state.currentSettingsChangeNumber === undefined ||
@@ -1349,7 +1397,7 @@ export class WorkflowEngine {
     ) {
       throw new Error("Saved workflow settings binding is incomplete");
     }
-    const scope = this.store.getSettingsScopeAtChange(
+    const scope = await this.store.getSettingsScopeAtChange(
       state.currentSettingsScopeId,
       state.currentSettingsChangeNumber,
     );
@@ -1508,16 +1556,78 @@ export class WorkflowEngine {
     signal: AbortSignal,
     meta: NodeExecutionMeta,
   ): Promise<NodeExecution> {
+    /* istanbul ignore if -- graph validation rejects action nodes without managed effects */
+    if (node.effect === undefined) {
+      throw new Error(
+        `Action node ${nodeId} must declare a managed effect with an explicit recovery policy`,
+      );
+    }
+    const effectType = node.effect.type.trim();
+    const idempotencyKey =
+      typeof node.effect.idempotencyKey === "function"
+        ? await node.effect.idempotencyKey(context)
+        : node.effect.idempotencyKey;
+    const request =
+      typeof node.effect.request === "function"
+        ? await node.effect.request(context)
+        : node.effect.request;
+    /* istanbul ignore if -- definition validation and effect helpers reject empty fields */
+    if (effectType.length === 0 || idempotencyKey.trim().length === 0) {
+      throw new Error("Managed effect type and idempotency key must be nonempty text");
+    }
+    canonicalJson(request);
+    const reservation = await this.store.reserveEffect({
+      runId: context.state.runId,
+      attemptId,
+      effectType,
+      idempotencyKey,
+      request: request as JsonValue,
+      recovery: node.effect.recovery,
+    });
+    if (reservation.disposition === "ambiguous") throw new RunParkedError();
+    if (reservation.disposition === "adopted") {
+      const adopted = reservation.result;
+      if (adopted === null || typeof adopted !== "object" || Array.isArray(adopted)) {
+        throw new Error("Managed effect receipt is invalid");
+      }
+      const execution = adopted as NodeExecution;
+      if (execution.action !== undefined) meta.action = execution.action;
+      return execution;
+    }
     const actionContext: WorkflowActionContext = {
       ...context,
+      effect: { type: effectType, idempotencyKey, recovery: node.effect.recovery },
       publishUpdate: async (update) => await this.publishUpdate(nodeId, attemptId, update),
     };
-    if ("exec" in node) {
-      return await runShellActionNode(node, context, actionContext, signal, meta);
+    try {
+      let execution: NodeExecution;
+      if ("exec" in node) {
+        execution = await runShellActionNode(node, actionContext, signal, meta);
+      } else {
+        meta.action = { actionType: "function" };
+        const output = await node.run(actionContext);
+        execution = { output, promptText: null, action: { actionType: "function" } };
+      }
+      canonicalJson(execution);
+      await this.store.settleEffect({
+        runId: context.state.runId,
+        effectId: reservation.effectId,
+        attemptNumber: reservation.attemptNumber,
+        outcome: "applied",
+        result: execution as JsonValue,
+      });
+      return execution;
+    } catch (error) {
+      if (isRunParkedError(error) || isClaimLostError(error)) throw error;
+      await this.store.settleEffect({
+        runId: context.state.runId,
+        effectId: reservation.effectId,
+        attemptNumber: reservation.attemptNumber,
+        outcome: "rejected",
+        error: errorMessage(error),
+      });
+      throw error;
     }
-    meta.action = { actionType: "function" };
-    const output = await node.run(actionContext);
-    return { output, promptText: null, action: { actionType: "function" } };
   }
 
   private async persist(
@@ -1532,6 +1642,7 @@ export class WorkflowEngine {
       // Observers (UI updates, loggers) must never determine workflow
       // correctness; a throwing observer would otherwise fail the run.
     }
+    await new Promise<void>((resolve) => setImmediate(resolve));
   }
 
   private async finishRun(
@@ -1543,13 +1654,6 @@ export class WorkflowEngine {
     if (status === "failed" && state.status === "timed_out") {
       status = "timed_out";
     }
-    // Let observers (e.g. the session recorder) stop and drain before the
-    // terminal event exists, so the terminal fact is immutable from that point on.
-    try {
-      await this.onRunFinishing?.(runId, state);
-    } catch {
-      // Finishing the run wins over observer failures.
-    }
     state.status = status;
     state.finishedAt = new Date().toISOString();
     if (fields.error !== undefined) {
@@ -1564,9 +1668,17 @@ export class WorkflowEngine {
     delete state.currentNode;
     delete state.currentAttemptId;
     delete state.currentNodeStartedAt;
+    delete state.currentNodeDeadlineAt;
     delete state.currentSettingsScopeId;
     delete state.currentSettingsChangeNumber;
     delete state.currentSettingsHash;
+    // Let observers stop, drain, and prepare terminal delivery from the final
+    // in-memory state before the immutable terminal event is committed.
+    try {
+      await this.onRunFinishing?.(runId, state);
+    } catch {
+      // Finishing the run wins over observer failures.
+    }
     await this.persist(runId, state, {
       scope: "run",
       type: `run_${status}`,
@@ -1585,7 +1697,7 @@ async function runCheckpointNode(
   node: CheckpointNodeDefinition,
   context: WorkflowNodeContext,
   execution: {
-    store: WorkflowRunStore;
+    store: WorkflowExecutionStore;
     workflowName: string;
     nodeId: string;
     attemptId: string;
@@ -1610,9 +1722,7 @@ async function runCheckpointNode(
       prompt,
       ...(timeout !== undefined ? { timeout } : {}),
     });
-    await new HumanDecisionStore(execution.store.databasePath, {
-      state: execution.store.state,
-    }).createRequest(request);
+    await execution.store.createHumanDecisionRequest(request);
     return { output: request, promptText: null };
   }
   const output = node.run ? await node.run(context) : { summary: node.summary ?? "checkpoint" };
@@ -1633,12 +1743,11 @@ function shellReceipt(result: ShellActionResult): WorkflowActionReceipt {
 
 async function runShellActionNode(
   node: ShellActionNodeDefinition,
-  context: WorkflowNodeContext,
   actionContext: WorkflowActionContext,
   signal: AbortSignal,
   meta: NodeExecutionMeta,
 ): Promise<NodeExecution> {
-  const spec = await node.exec(context);
+  const spec = await node.exec(actionContext);
   const streams = new Set(node.updates?.streams ?? ["stdout"]);
   let result: ShellActionResult;
   try {
@@ -1664,7 +1773,7 @@ async function runShellActionNode(
     throw error;
   }
   meta.action = shellReceipt(result);
-  const output = node.parse ? await node.parse(result, context) : result;
+  const output = node.parse ? await node.parse(result, actionContext) : result;
   return { output, promptText: null, action: shellReceipt(result) };
 }
 
@@ -1882,7 +1991,7 @@ function appendLiveControlInstructions(
   nodeId: string,
   context: WorkflowNodeContext,
 ): string {
-  const lines = [prompt.trimEnd(), "", "Workflow changes during this run:"];
+  const lines = [prompt.trimEnd(), "", "Workflow context for this run:"];
   if (
     context.settingsScopeId !== undefined &&
     context.settingsChangeNumber !== undefined &&
@@ -1906,18 +2015,12 @@ function appendLiveControlInstructions(
         ? [`- Settings purpose: ${definition.description}`]
         : []),
       `- Current settings: ${summary}`,
-      `- Changes allowed from this model step: ${allowed || "none"}`,
-      "- Treat the current settings as authoritative for future behavior in this workflow scope.",
-      "- To change future workflow settings, use the workflow tool with action change-settings, this scopeId, an RFC 6902 patch, and optionally expectedChangeNumber.",
+      `- Settings permissions: ${allowed || "none"}`,
+      "- Treat the current settings as authoritative for this workflow scope.",
     );
   } else {
     lines.push("- This workflow scope has no editable settings.");
   }
-  lines.push(
-    "- To save normal user work for after successful completion, use workflow action queue-follow-up once for each prompt.",
-    "- To remove an unsent prompt that this model queued, use workflow action remove-follow-up with its followUpId.",
-    "- Setting changes affect only future node attempts and future settings routes. They do not change this running attempt or completed work.",
-  );
   return lines.join("\n");
 }