@stigmer/runner 3.40.1 → 3.41.0

package/src/workflow-engine/__tests__/tasks/human-input.test.ts

@@ -1,5 +1,8 @@
 import { describe, it, expect, vi } from "vitest";
-import { executeHumanInputTask } from "../../tasks/human-input.js";
+import {
+  HUMAN_INPUT_FAIL_TIMEOUT_RESOLVED_PATCH,
+  executeHumanInputTask,
+} from "../../tasks/human-input.js";
 import { createState } from "../../state.js";
 import { evaluateExpressionBatch } from "../../expression.js";
 import { TaskStatusAccumulator } from "../../task-status-accumulator.js";
@@ -8,6 +11,7 @@ import type {
   TaskExecutionContext,
   HumanInputExecutionConfig,
   HumanInputResult,
+  HumanInputTimeout,
   AwaitHumanInputFn,
   EmitEventsFn,
   ExpressionEvaluator,
@@ -17,12 +21,16 @@ import type {
 
 const notAvailable = () => { throw new Error("not available in test"); };
 
+/** What the workflow layer reports when the gate's timer wins. */
+const TIMED_OUT: HumanInputTimeout = { timedOut: true };
+
 interface CtxOptions {
   readonly awaitFn?: AwaitHumanInputFn;
   readonly emitFn?: EmitEventsFn;
   readonly evaluateExpressions?: ExpressionEvaluator;
   readonly promoteTaskOutput?: PromoteTaskOutputFn;
   readonly taskStatusAccumulator?: TaskStatusAccumulator;
+  readonly isPatched?: (changeId: string) => boolean;
 }
 
 function makeCtx(
@@ -45,6 +53,7 @@ function makeCtx(
     emitEvents: emitFn,
     promoteTaskOutput: options?.promoteTaskOutput,
     taskStatusAccumulator: options?.taskStatusAccumulator,
+    isPatched: options?.isPatched,
   };
 }
 
@@ -156,11 +165,11 @@ describe("executeHumanInputTask", () => {
       expect(capturedConfig!.timeoutSeconds).toBe(0);
     });
 
-    it("passes onTimeout policy from config", async () => {
+    it("hands the wait only the signal and the timeout; the policy stays with the kernel", async () => {
       let capturedConfig: HumanInputExecutionConfig | undefined;
       const awaitFn: AwaitHumanInputFn = async (config) => {
         capturedConfig = config;
-        return { outcome: "approve", auto_resolved: true, reason: "timeout" };
+        return { outcome: "approve" };
       };
 
       const taskDef: HumanInputTaskDef = {
@@ -170,31 +179,27 @@ describe("executeHumanInputTask", () => {
 
       await executeHumanInputTask(taskDef, "t", createState(), makeCtx(awaitFn));
 
-      expect(capturedConfig!.onTimeout).toBe("approve");
+      expect(capturedConfig).toEqual({ signalName: "human_input_t", timeoutSeconds: 60 });
     });
 
-    it("defaults onTimeout to 'fail' when not set", async () => {
-      let capturedConfig: HumanInputExecutionConfig | undefined;
-      const awaitFn: AwaitHumanInputFn = async (config) => {
-        capturedConfig = config;
-        return { outcome: "approve" };
-      };
-
+    it("fails the task on a timeout when onTimeout is not set", async () => {
       const taskDef: HumanInputTaskDef = {
         kind: "human_input",
         humanInput: { prompt: "Review", timeout: 60 },
       };
 
-      await executeHumanInputTask(taskDef, "t", createState(), makeCtx(awaitFn));
-
-      expect(capturedConfig!.onTimeout).toBe("fail");
+      await expect(
+        executeHumanInputTask(taskDef, "t", createState(), makeCtx(async () => TIMED_OUT)),
+      ).rejects.toThrow("human_input task timed out waiting for signal 'human_input_t'");
     });
   });
 
   describe("error propagation", () => {
-    it("propagates timeout failure errors from orchestrator", async () => {
+    it("propagates an error from the wait untouched and logs no resolution", async () => {
+      const emitted: WorkflowEventDescriptor[][] = [];
+      const emitFn: EmitEventsFn = async (events) => { emitted.push(events); };
       const awaitFn: AwaitHumanInputFn = async () => {
-        throw new Error("human_input task timed out");
+        throw new Error("workflow cancelled");
       };
 
       const taskDef: HumanInputTaskDef = {
@@ -203,18 +208,86 @@ describe("executeHumanInputTask", () => {
       };
 
       await expect(
-        executeHumanInputTask(taskDef, "t", createState(), makeCtx(awaitFn)),
+        executeHumanInputTask(taskDef, "t", createState(), makeCtx(awaitFn, emitFn)),
+      ).rejects.toThrow("workflow cancelled");
+      expect(emitted.flat().map((e) => e.type)).toEqual(["approval_requested"]);
+    });
+  });
+
+  // A fail-policy timeout ends the gate without a decision. It still closes
+  // the approval in the event log, so a reader never sees a request left
+  // open, and then fails the task with the error it always raised
+  // (stigmer/stigmer#1442).
+  describe("fail-policy timeout", () => {
+    const taskDef: HumanInputTaskDef = {
+      kind: "human_input",
+      humanInput: { prompt: "Review", timeout: 10, onTimeout: "fail" },
+    };
+
+    it("logs one approval_resolved with auto_resolved and no outcome, then fails the task", async () => {
+      const emitted: WorkflowEventDescriptor[][] = [];
+      const emitFn: EmitEventsFn = async (events) => { emitted.push(events); };
+      const state = createState();
+
+      await expect(
+        executeHumanInputTask(taskDef, "gate", state, makeCtx(async () => TIMED_OUT, emitFn)),
+      ).rejects.toThrow("human_input task timed out waiting for signal 'human_input_gate'");
+
+      const resolutions = emitted.flat().filter((e) => e.type === "approval_resolved");
+      expect(resolutions).toHaveLength(1);
+      expect(resolutions[0]).toMatchObject({
+        taskName: "gate",
+        outcome: "",
+        resolvedBy: "",
+        resolvedByActor: undefined,
+        comment: "",
+        autoResolved: true,
+      });
+      expect(state.data.gate, "a failed gate records no decision").toBeUndefined();
+    });
+
+    it("asks the patch gate by its pinned id before logging", async () => {
+      const isPatched = vi.fn(() => true);
+
+      await expect(
+        executeHumanInputTask(taskDef, "gate", createState(), makeCtx(async () => TIMED_OUT, undefined, { isPatched })),
       ).rejects.toThrow("timed out");
+
+      expect(HUMAN_INPUT_FAIL_TIMEOUT_RESOLVED_PATCH).toBe("human-input-fail-timeout-resolved");
+      expect(isPatched).toHaveBeenCalledWith(HUMAN_INPUT_FAIL_TIMEOUT_RESOLVED_PATCH);
+    });
+
+    it("replays a history from before the patch in the old order: no resolution, the same failure", async () => {
+      const emitted: WorkflowEventDescriptor[][] = [];
+      const emitFn: EmitEventsFn = async (events) => { emitted.push(events); };
+
+      await expect(
+        executeHumanInputTask(
+          taskDef, "gate", createState(),
+          makeCtx(async () => TIMED_OUT, emitFn, { isPatched: () => false }),
+        ),
+      ).rejects.toThrow("human_input task timed out waiting for signal 'human_input_gate'");
+
+      expect(emitted.flat().map((e) => e.type)).toEqual(["approval_requested"]);
+    });
+
+    it("never asks the patch gate for a gate a policy or a reviewer decided", async () => {
+      const isPatched = vi.fn(() => true);
+      const approveOnTimeout: HumanInputTaskDef = {
+        kind: "human_input",
+        humanInput: { prompt: "Review", timeout: 10, onTimeout: "approve" },
+      };
+
+      await executeHumanInputTask(approveOnTimeout, "a", createState(), makeCtx(async () => TIMED_OUT, undefined, { isPatched }));
+      await executeHumanInputTask(taskDef, "b", createState(), makeCtx(async () => ({ outcome: "approve" }), undefined, { isPatched }));
+
+      expect(isPatched).not.toHaveBeenCalled();
     });
   });
 
   describe("auto-resolved results", () => {
     it("handles auto-approve timeout result", async () => {
-      const awaitFn: AwaitHumanInputFn = async () => ({
-        outcome: "approve",
-        auto_resolved: true,
-        reason: "timeout",
-      });
+      const awaitFn: AwaitHumanInputFn = async () => TIMED_OUT;
 
       const taskDef: HumanInputTaskDef = {
         kind: "human_input",
@@ -229,11 +302,7 @@ describe("executeHumanInputTask", () => {
     });
 
     it("handles auto-deny timeout result", async () => {
-      const awaitFn: AwaitHumanInputFn = async () => ({
-        outcome: "deny",
-        auto_resolved: true,
-        reason: "timeout",
-      });
+      const awaitFn: AwaitHumanInputFn = async () => TIMED_OUT;
 
       const taskDef: HumanInputTaskDef = {
         kind: "human_input",
@@ -260,11 +329,7 @@ describe("executeHumanInputTask", () => {
     ];
 
     it("maps timeout auto-approve to the FIRST outcome and routes its then", async () => {
-      const awaitFn: AwaitHumanInputFn = async () => ({
-        outcome: "approve",
-        auto_resolved: true,
-        reason: "timeout",
-      });
+      const awaitFn: AwaitHumanInputFn = async () => TIMED_OUT;
 
       const taskDef: HumanInputTaskDef = {
         kind: "human_input",
@@ -288,11 +353,7 @@ describe("executeHumanInputTask", () => {
     });
 
     it("maps timeout auto-deny to the LAST outcome", async () => {
-      const awaitFn: AwaitHumanInputFn = async () => ({
-        outcome: "deny",
-        auto_resolved: true,
-        reason: "timeout",
-      });
+      const awaitFn: AwaitHumanInputFn = async () => TIMED_OUT;
 
       const taskDef: HumanInputTaskDef = {
         kind: "human_input",
@@ -310,11 +371,7 @@ describe("executeHumanInputTask", () => {
     // — the ordinary name lookup finds the "escalate" outcome and routes its
     // `then`, regardless of the outcome's position in the list.
     it("resolves timeout escalate to the escalate-named outcome and routes its then", async () => {
-      const awaitFn: AwaitHumanInputFn = async () => ({
-        outcome: "escalate",
-        auto_resolved: true,
-        reason: "timeout",
-      });
+      const awaitFn: AwaitHumanInputFn = async () => TIMED_OUT;
 
       const escalateOutcomes = [
         { name: "proceed", label: "Proceed", then: "deployStep" },
@@ -347,11 +404,7 @@ describe("executeHumanInputTask", () => {
     it("reports the mapped outcome on the approval_resolved event", async () => {
       const emitted: WorkflowEventDescriptor[][] = [];
       const emitFn: EmitEventsFn = async (events) => { emitted.push(events); };
-      const awaitFn: AwaitHumanInputFn = async () => ({
-        outcome: "approve",
-        auto_resolved: true,
-        reason: "timeout",
-      });
+      const awaitFn: AwaitHumanInputFn = async () => TIMED_OUT;
 
       const taskDef: HumanInputTaskDef = {
         kind: "human_input",
@@ -385,11 +438,7 @@ describe("executeHumanInputTask", () => {
     });
 
     it("keeps plain approve/deny for binary gates without custom outcomes", async () => {
-      const awaitFn: AwaitHumanInputFn = async () => ({
-        outcome: "approve",
-        auto_resolved: true,
-        reason: "timeout",
-      });
+      const awaitFn: AwaitHumanInputFn = async () => TIMED_OUT;
 
       const taskDef: HumanInputTaskDef = {
         kind: "human_input",
@@ -474,10 +523,40 @@ describe("executeHumanInputTask", () => {
       expect(resolved.outcome).toBe("reject");
       expect(resolved.resolvedBy).toBe("carol");
       expect(resolved.resolvedByActor).toBeUndefined();
+      expect(resolved.comment).toBe("");
       expect(resolved.autoResolved).toBe(false);
       expect(resolved.waitDurationMs).toBeGreaterThanOrEqual(0);
     });
 
+    it("carries the reviewer's comment into approval_resolved and the task output", async () => {
+      const emitted: WorkflowEventDescriptor[][] = [];
+      const emitFn: EmitEventsFn = async (events) => { emitted.push(events); };
+      const awaitFn: AwaitHumanInputFn = async () => ({
+        outcome: "deny",
+        reviewer: "ida_01abc",
+        comment: "Rollback plan is missing",
+        responded_at: "2026-05-20T10:00:00Z",
+      });
+
+      const taskDef: HumanInputTaskDef = {
+        kind: "human_input",
+        humanInput: { prompt: "Confirm?" },
+      };
+
+      const state = createState();
+      await executeHumanInputTask(taskDef, "gate", state, makeCtx(awaitFn, emitFn));
+
+      const resolved = emitted[1][0];
+      if (resolved.type !== "approval_resolved") throw new Error("unexpected");
+      expect(resolved.comment).toBe("Rollback plan is missing");
+      expect(state.data.gate).toEqual({
+        outcome: "deny",
+        reviewer: "ida_01abc",
+        comment: "Rollback plan is missing",
+        responded_at: "2026-05-20T10:00:00Z",
+      });
+    });
+
     it("carries the reviewer_actor display snapshot into approval_resolved and the task output", async () => {
       const emitted: WorkflowEventDescriptor[][] = [];
       const emitFn: EmitEventsFn = async (events) => { emitted.push(events); };
@@ -607,11 +686,7 @@ describe("executeHumanInputTask", () => {
     it("emits approval_resolved with autoResolved true on timeout auto-approve", async () => {
       const emitted: WorkflowEventDescriptor[][] = [];
       const emitFn: EmitEventsFn = async (events) => { emitted.push(events); };
-      const awaitFn: AwaitHumanInputFn = async () => ({
-        outcome: "approve",
-        auto_resolved: true,
-        reason: "timeout",
-      });
+      const awaitFn: AwaitHumanInputFn = async () => TIMED_OUT;
 
       const taskDef: HumanInputTaskDef = {
         kind: "human_input",
@@ -625,6 +700,7 @@ describe("executeHumanInputTask", () => {
 
       expect(resolved.autoResolved).toBe(true);
       expect(resolved.outcome).toBe("approve");
+      expect(resolved.comment).toBe("");
     });
   });
 

package/src/workflow-engine/tasks/human-input.ts

@@ -32,6 +32,16 @@
  * activation and attached to the approval_requested event — inline when
  * small, as an artifact reference when at/above the promotion threshold —
  * so the approval record captures exactly what the reviewer saw.
+ *
+ * Timeout policy lives here, whole. `ctx.awaitHumanInput()` only reports
+ * that the timer won; this module decides what that means. approve, deny and
+ * escalate resolve the gate to a declared outcome. fail logs an
+ * approval_resolved with `auto_resolved` set and no outcome, then fails the
+ * task with the error it has always raised, so every approval_requested in
+ * the event log is closed by an approval_resolved (stigmer/stigmer#1442).
+ * That emit is a new workflow command on an existing path, so it runs behind
+ * {@link HUMAN_INPUT_FAIL_TIMEOUT_RESOLVED_PATCH}: a history recorded before
+ * it replays the old order (no emit, then the throw).
  */
 
 import type {
@@ -41,6 +51,9 @@ import type {
   WorkflowState,
   TaskExecutionContext,
   HumanInputResult,
+  HumanInputResponse,
+  HumanInputTimeout,
+  HumanInputTimeoutPolicy,
 } from "../types.js";
 import { resolveConfigExpressions, resolveEmbeddedExpressions } from "../resolve.js";
 import { isStrictExpr } from "../expression-utils.js";
@@ -49,6 +62,13 @@ const SIGNAL_PREFIX = "human_input_";
 const DEFAULT_TIMEOUT_SECONDS = 0;
 const DEFAULT_ON_TIMEOUT = "fail" as const;
 
+/**
+ * Temporal patch id for logging approval_resolved before a fail-policy
+ * timeout fails the task. Wire bytes: a rename makes every history that
+ * carries the marker replay down the old path.
+ */
+export const HUMAN_INPUT_FAIL_TIMEOUT_RESOLVED_PATCH = "human-input-fail-timeout-resolved";
+
 /**
  * Executes a human_input task. Called from `runSingleTask` in do-executor
  * when the task kind is "human_input".
@@ -97,29 +117,22 @@ export async function executeHumanInputTask(
     ]);
   }
 
-  const result: HumanInputResult = applyTimeoutOutcomeContract(
-    await ctx.awaitHumanInput({
-      signalName,
-      timeoutSeconds,
-      onTimeout,
-    }),
-    config.outcomes,
-  );
+  const response = await ctx.awaitHumanInput({ signalName, timeoutSeconds });
+  const result = isTimeout(response)
+    ? resolveTimeout(onTimeout, config.outcomes)
+    : response;
 
-  if (ctx.emitEvents) {
-    await ctx.emitEvents([{
-      type: "approval_resolved",
-      taskName,
-      occurredAt: new Date().toISOString(),
-      outcome: result.outcome,
-      resolvedBy: result.reviewer ?? "",
-      resolvedByActor: result.reviewer_actor,
-      comment: "",
-      waitDurationMs: Date.now() - approvalRequestedAt,
-      autoResolved: result.auto_resolved ?? false,
-    }]);
+  if (result === undefined) {
+    if (ctx.isPatched?.(HUMAN_INPUT_FAIL_TIMEOUT_RESOLVED_PATCH) ?? true) {
+      await emitApprovalResolved(ctx, taskName, approvalRequestedAt, {
+        outcome: "", auto_resolved: true, reason: "timeout",
+      });
+    }
+    throw new Error(`human_input task timed out waiting for signal '${signalName}'`);
   }
 
+  await emitApprovalResolved(ctx, taskName, approvalRequestedAt, result);
+
   state.addData({ [taskName]: result });
 
   const selectedOutcome = config.outcomes?.find(o => o.name === result.outcome);
@@ -136,35 +149,72 @@ function validateConfig(config: HumanInputConfig, taskName: string): void {
   }
 }
 
+function isTimeout(response: HumanInputResponse): response is HumanInputTimeout {
+  return "timedOut" in response;
+}
+
 /**
- * Applies the proto contract for timeout auto-resolution with custom
- * outcomes (HumanInputTaskConfig.outcomes doc): auto-approve resolves to
- * the FIRST declared outcome and auto-deny to the LAST, so `then` routing
- * and downstream outcome switches see declared outcome names — never the
- * orchestrator's internal approve/deny words, which a reviewer of a
- * custom-outcome gate was never offered. Binary gates (no custom outcomes)
- * keep the plain approve/deny result.
+ * The decision a timeout policy makes, or `undefined` when the policy is
+ * fail and the gate ends without one.
+ *
+ * With custom outcomes the proto contract (HumanInputTaskConfig.outcomes doc)
+ * applies: auto-approve resolves to the FIRST declared outcome and auto-deny
+ * to the LAST, so `then` routing and downstream outcome switches see declared
+ * outcome names, never approve/deny words a reviewer of a custom-outcome gate
+ * was never offered. Binary gates (no custom outcomes) keep plain approve/deny.
  *
  * Escalate needs no remapping by construction (stigmer/stigmer#781): its
- * policy word IS the declared outcome's name — the loader (and the server
+ * policy word IS the declared outcome's name. The loader (and the server
  * validator) only accept the escalate policy when an outcome named
- * "escalate" with `then` exists, so the caller's ordinary name lookup
- * routes the escalation branch.
+ * "escalate" with `then` exists, so the caller's ordinary name lookup routes
+ * the escalation branch.
  */
-function applyTimeoutOutcomeContract(
-  result: HumanInputResult,
+function resolveTimeout(
+  policy: HumanInputTimeoutPolicy,
   outcomes: HumanInputConfig["outcomes"],
-): HumanInputResult {
-  if (!result.auto_resolved || result.reason !== "timeout" || !outcomes?.length) {
-    return result;
-  }
-  if (result.outcome === "approve") {
-    return { ...result, outcome: outcomes[0].name };
-  }
-  if (result.outcome === "deny") {
-    return { ...result, outcome: outcomes[outcomes.length - 1].name };
+): HumanInputResult | undefined {
+  const decided = (outcome: string): HumanInputResult => ({
+    outcome, auto_resolved: true, reason: "timeout",
+  });
+  switch (policy) {
+    case "approve":
+      return decided(outcomes?.length ? outcomes[0].name : "approve");
+    case "deny":
+      return decided(outcomes?.length ? outcomes[outcomes.length - 1].name : "deny");
+    case "escalate":
+      return decided("escalate");
+    case "fail":
+      return undefined;
+    default: {
+      const unreachable: never = policy;
+      throw new Error(`human_input: unknown timeout policy '${String(unreachable)}'`);
+    }
   }
-  return result;
+}
+
+/**
+ * Logs how the gate's approval ended. A timeout's decision carries no
+ * reviewer, no comment and `auto_resolved`; a fail timeout's carries no
+ * outcome either.
+ */
+async function emitApprovalResolved(
+  ctx: TaskExecutionContext,
+  taskName: string,
+  approvalRequestedAt: number,
+  result: HumanInputResult,
+): Promise<void> {
+  if (!ctx.emitEvents) return;
+  await ctx.emitEvents([{
+    type: "approval_resolved",
+    taskName,
+    occurredAt: new Date().toISOString(),
+    outcome: result.outcome,
+    resolvedBy: result.reviewer ?? "",
+    resolvedByActor: result.reviewer_actor,
+    comment: result.comment ?? "",
+    waitDurationMs: Date.now() - approvalRequestedAt,
+    autoResolved: result.auto_resolved ?? false,
+  }]);
 }
 
 interface ResolvedReviewPayload {

package/src/workflow-engine/types.ts

@@ -561,10 +561,20 @@ export interface RunWorkflowExecutionConfig {
 }
 
 /**
- * Blocks workflow execution until a human provides input via signal.
- * Supports configurable timeout with policies (fail, approve, deny, escalate).
+ * Blocks workflow execution until a human provides input via signal, or
+ * until the timeout elapses. Reports which happened and nothing more: the
+ * timeout policy (fail, approve, deny, escalate) is the kernel's to apply
+ * (`tasks/human-input.ts`), so one module owns every way a gate can end.
  */
-export type AwaitHumanInputFn = (config: HumanInputExecutionConfig) => Promise<HumanInputResult>;
+export type AwaitHumanInputFn = (config: HumanInputExecutionConfig) => Promise<HumanInputResponse>;
+
+/** What a wait at a human_input gate ended with: the reviewer's decision, or the timeout. */
+export type HumanInputResponse = HumanInputResult | HumanInputTimeout;
+
+/** The gate's timeout elapsed before any decision arrived. */
+export interface HumanInputTimeout {
+  readonly timedOut: true;
+}
 
 /**
  * Internal timeout-policy vocabulary — the loader-normalized form of the
@@ -577,8 +587,8 @@ export type HumanInputTimeoutPolicy = "fail" | "approve" | "deny" | "escalate";
 
 export interface HumanInputExecutionConfig {
   readonly signalName: string;
+  /** Seconds to wait before reporting a {@link HumanInputTimeout}; 0 waits indefinitely. */
   readonly timeoutSeconds: number;
-  readonly onTimeout: HumanInputTimeoutPolicy;
 }
 
 export interface HumanInputResult {
@@ -594,6 +604,8 @@ export interface HumanInputResult {
   readonly reviewer_actor?: HumanInputReviewerActor;
   readonly responded_at?: string;
   readonly form_data?: Record<string, unknown>;
+  /** Free-text comment the reviewer attached. Absent when none was written, and always on a timeout. */
+  readonly comment?: string;
   readonly auto_resolved?: boolean;
   readonly reason?: string;
 }

package/src/workflows/call-agent-orchestrator.ts

@@ -65,6 +65,13 @@ type AgentActivities = ReturnType<typeof createCallAgentActivities>;
 type StatusActivities = ReturnType<typeof createCallAgentStatusActivities>;
 type EventActivities = ReturnType<typeof createWorkflowEventActivities>;
 
+/**
+ * Every activity an agent call schedules. The engine's own activity type
+ * includes it, so a worker (or a test mock) that registers the engine's
+ * activities is checked against this list by the compiler.
+ */
+export type AgentCallActivities = AgentActivities & StatusActivities & EventActivities;
+
 // The 1h ceiling is a deliberate platform constant, not a user knob: the
 // old AgentCallTaskConfig declared a per-task `timeout` that nothing ever
 // read, and #358 deleted it rather than declaring what isn't honored. The

package/src/workflows/engine-core.ts

@@ -28,6 +28,7 @@ import type { createRunCommandActivities } from "../activities/run-command.js";
 import type { createWorkflowEventActivities } from "../activities/workflow-event-activities.js";
 import type { createPromoteTaskOutputActivities } from "../activities/promote-task-output.js";
 import { orchestrateAgentCall } from "./call-agent-orchestrator.js";
+import type { AgentCallActivities } from "./call-agent-orchestrator.js";
 import { orchestrateListenTask } from "./listen-orchestrator.js";
 import { orchestrateRunWorkflow } from "./run-orchestrator.js";
 import { orchestrateHumanInput } from "./human-input-orchestrator.js";
@@ -65,6 +66,23 @@ type RunActivities = ReturnType<typeof createRunCommandActivities>;
 type EventActivities = ReturnType<typeof createWorkflowEventActivities>;
 type PromoteActivities = ReturnType<typeof createPromoteTaskOutputActivities>;
 
+/**
+ * Every activity the engine can schedule, by name. A worker that runs the
+ * engine must register each one; the test mocks declare
+ * `satisfies Record<keyof EngineActivities, unknown>` so a new activity
+ * without a mock fails the typecheck instead of failing the smoke run at
+ * run time (stigmer#1300: four missing local activities made the golden
+ * suite report passes for months without running a golden).
+ */
+export type EngineActivities = EvalActivities &
+  HttpActivities &
+  GrpcActivities &
+  FunctionActivities &
+  RunActivities &
+  EventActivities &
+  PromoteActivities &
+  AgentCallActivities;
+
 const evalProxy = proxyLocalActivities<EvalActivities>({
   startToCloseTimeout: "10s",
 });

package/src/workflows/execute-from-execution.ts

@@ -31,7 +31,8 @@ import type { createHydrateWorkflowActivities } from "../activities/hydrate-work
 // Hydration Activity Proxy
 // ─────────────────────────────────────────────────────────────────────────────
 
-type HydrateActivities = ReturnType<typeof createHydrateWorkflowActivities>;
+/** The activity this entry point schedules before it hands the model to the engine. */
+export type HydrateActivities = ReturnType<typeof createHydrateWorkflowActivities>;
 
 const hydrateProxy = proxyActivities<HydrateActivities>({
   startToCloseTimeout: "2m",