zeitlich 0.2.37 → 0.2.39

package/src/lib/subagent/subagent.integration.test.ts

@@ -36,7 +36,7 @@ vi.mock("@temporalio/workflow", () => {
     condition: vi.fn(async (fn: () => boolean) => {
       if (!fn()) throw new Error("condition predicate was not satisfied");
     }),
-    startChild: vi.fn(
+    executeChild: vi.fn(
       async (
         _workflow: unknown,
         opts: { workflowId: string; args: unknown[] }
@@ -51,11 +51,7 @@ vi.mock("@temporalio/workflow", () => {
               usage: { inputTokens: 100, outputTokens: 50 },
             };
 
-        return {
-          signal: vi.fn(),
-          result: () => Promise.resolve(result),
-          workflowId: opts.workflowId,
-        };
+        return result;
       }
     ),
     getExternalWorkflowHandle: vi.fn((_id: string) => ({
@@ -378,8 +374,8 @@ describe("createSubagentHandler", () => {
   });
 
   it("passes sandbox inherit to child when sandbox is inherit", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
 
     const inheritSubagent: SubagentConfig = {
       agentName: "inherit-agent",
@@ -404,8 +400,8 @@ describe("createSubagentHandler", () => {
       }
     );
 
-    const lastCall = startMock.mock.calls[startMock.mock.calls.length - 1];
-    if (!lastCall) throw new Error("expected startChild call");
+    const lastCall = execMock.mock.calls[execMock.mock.calls.length - 1];
+    if (!lastCall) throw new Error("expected executeChild call");
     const workflowInput = lastCall[1].args[1] as SubagentWorkflowInput;
     expect(workflowInput.sandbox).toEqual({
       mode: "inherit",
@@ -436,8 +432,8 @@ describe("createSubagentHandler", () => {
   });
 
   it("does not pass sandboxId to child when sandbox is own (first call)", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
 
     const ownSubagent: SubagentConfig = {
       agentName: "own-agent",
@@ -458,15 +454,15 @@ describe("createSubagentHandler", () => {
       }
     );
 
-    const lastCall = startMock.mock.calls[startMock.mock.calls.length - 1];
-    if (!lastCall) throw new Error("expected startChild call");
+    const lastCall = execMock.mock.calls[execMock.mock.calls.length - 1];
+    if (!lastCall) throw new Error("expected executeChild call");
     const workflowInput = lastCall[1].args[1] as SubagentWorkflowInput;
     expect(workflowInput.sandbox).toBeUndefined();
   });
 
   it("resolves context function at invocation time", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
 
     let counter = 0;
     const dynamicSubagent: SubagentConfig = {
@@ -486,15 +482,15 @@ describe("createSubagentHandler", () => {
       { threadId: "t", toolCallId: "tc", toolName: "Subagent" }
     );
 
-    const lastCall = startMock.mock.calls[startMock.mock.calls.length - 1];
-    if (!lastCall) throw new Error("expected startChild call");
+    const lastCall = execMock.mock.calls[execMock.mock.calls.length - 1];
+    if (!lastCall) throw new Error("expected executeChild call");
     const context = lastCall[1].args[2] as Record<string, unknown>;
     expect(context).toEqual({ invocation: 1 });
   });
 
   it("passes static context unchanged", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
 
     const staticSubagent: SubagentConfig = {
       agentName: "static-ctx",
@@ -510,15 +506,15 @@ describe("createSubagentHandler", () => {
       { threadId: "t", toolCallId: "tc", toolName: "Subagent" }
     );
 
-    const lastCall = startMock.mock.calls[startMock.mock.calls.length - 1];
-    if (!lastCall) throw new Error("expected startChild call");
+    const lastCall = execMock.mock.calls[execMock.mock.calls.length - 1];
+    if (!lastCall) throw new Error("expected executeChild call");
     const context = lastCall[1].args[2] as Record<string, unknown>;
     expect(context).toEqual({ key: "value" });
   });
 
   it("does not pass sandbox init when sandbox is own without prior sandbox", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
 
     const ownSubagent: SubagentConfig = {
       agentName: "own-agent",
@@ -539,8 +535,8 @@ describe("createSubagentHandler", () => {
       }
     );
 
-    const lastCall = startMock.mock.calls[startMock.mock.calls.length - 1];
-    if (!lastCall) throw new Error("expected startChild call");
+    const lastCall = execMock.mock.calls[execMock.mock.calls.length - 1];
+    if (!lastCall) throw new Error("expected executeChild call");
     const workflowInput = lastCall[1].args[1] as SubagentWorkflowInput;
     expect(workflowInput.sandbox).toBeUndefined();
   });
@@ -548,8 +544,8 @@ describe("createSubagentHandler", () => {
   // --- Thread mode ---
 
   it("passes thread fork when thread is fork and threadId provided", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
 
     const contSubagent: SubagentConfig = {
       agentName: "cont",
@@ -570,8 +566,8 @@ describe("createSubagentHandler", () => {
       { threadId: "t", toolCallId: "tc", toolName: "Subagent" }
     );
 
-    const lastCall = startMock.mock.calls[startMock.mock.calls.length - 1];
-    if (!lastCall) throw new Error("expected startChild call");
+    const lastCall = execMock.mock.calls[execMock.mock.calls.length - 1];
+    if (!lastCall) throw new Error("expected executeChild call");
     const workflowInput = lastCall[1].args[1] as SubagentWorkflowInput;
     expect(workflowInput.thread).toEqual({
       mode: "fork",
@@ -580,8 +576,8 @@ describe("createSubagentHandler", () => {
   });
 
   it("passes thread continue when thread is continue", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
 
     const contSubagent: SubagentConfig = {
       agentName: "cont-mode",
@@ -602,8 +598,8 @@ describe("createSubagentHandler", () => {
       { threadId: "t", toolCallId: "tc", toolName: "Subagent" }
     );
 
-    const lastCall = startMock.mock.calls[startMock.mock.calls.length - 1];
-    if (!lastCall) throw new Error("expected startChild call");
+    const lastCall = execMock.mock.calls[execMock.mock.calls.length - 1];
+    if (!lastCall) throw new Error("expected executeChild call");
     const workflowInput = lastCall[1].args[1] as SubagentWorkflowInput;
     expect(workflowInput.thread).toEqual({
       mode: "continue",
@@ -612,8 +608,8 @@ describe("createSubagentHandler", () => {
   });
 
   it("does not pass thread when thread is new", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
 
     const noContSubagent: SubagentConfig = {
       agentName: "no-cont",
@@ -633,8 +629,8 @@ describe("createSubagentHandler", () => {
       { threadId: "t", toolCallId: "tc", toolName: "Subagent" }
     );
 
-    const lastCall = startMock.mock.calls[startMock.mock.calls.length - 1];
-    if (!lastCall) throw new Error("expected startChild call");
+    const lastCall = execMock.mock.calls[execMock.mock.calls.length - 1];
+    if (!lastCall) throw new Error("expected executeChild call");
     const workflowInput = lastCall[1].args[1] as SubagentWorkflowInput;
     expect(workflowInput.thread).toBeUndefined();
   });
@@ -642,8 +638,8 @@ describe("createSubagentHandler", () => {
   // --- Sandbox continuation ---
 
   it("does not pass sandbox when thread is fork (own sandbox)", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
 
     const contSandboxSubagent: SubagentConfig = {
       agentName: "sb-cont",
@@ -664,15 +660,15 @@ describe("createSubagentHandler", () => {
       }
     );
 
-    const lastCall = startMock.mock.calls[startMock.mock.calls.length - 1];
-    if (!lastCall) throw new Error("expected startChild call");
+    const lastCall = execMock.mock.calls[execMock.mock.calls.length - 1];
+    if (!lastCall) throw new Error("expected executeChild call");
     const workflowInput = lastCall[1].args[1] as SubagentWorkflowInput;
     expect(workflowInput.sandbox).toBeUndefined();
   });
 
   it("tracks sandbox ID and passes sandbox fork on continuation", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
 
     nextStartChildResult = () => ({
       toolResponse: "first run done",
@@ -713,8 +709,8 @@ describe("createSubagentHandler", () => {
       { threadId: "t", toolCallId: "tc-2", toolName: "Subagent" }
     );
 
-    const secondCall = startMock.mock.calls[startMock.mock.calls.length - 1];
-    if (!secondCall) throw new Error("expected second startChild call");
+    const secondCall = execMock.mock.calls[execMock.mock.calls.length - 1];
+    if (!secondCall) throw new Error("expected second executeChild call");
     const workflowInput = secondCall[1].args[1] as SubagentWorkflowInput;
     expect(workflowInput.thread).toEqual({
       mode: "fork",
@@ -727,8 +723,8 @@ describe("createSubagentHandler", () => {
   });
 
   it("does not pass sandbox fork without thread continuation", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
 
     nextStartChildResult = () => ({
       toolResponse: "done",
@@ -764,8 +760,8 @@ describe("createSubagentHandler", () => {
       { threadId: "t", toolCallId: "tc-2", toolName: "Subagent" }
     );
 
-    const secondCall = startMock.mock.calls[startMock.mock.calls.length - 1];
-    if (!secondCall) throw new Error("expected startChild call");
+    const secondCall = execMock.mock.calls[execMock.mock.calls.length - 1];
+    if (!secondCall) throw new Error("expected executeChild call");
     const workflowInput = secondCall[1].args[1] as SubagentWorkflowInput;
     expect(workflowInput.sandbox).toBeUndefined();
     expect(workflowInput.thread).toBeUndefined();
@@ -882,8 +878,8 @@ describe("createSubagentHandler", () => {
   });
 
   it("does not pass sandboxId when sandbox is none (default)", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
 
     const noneSubagent: SubagentConfig = {
       agentName: "none-agent",
@@ -903,15 +899,15 @@ describe("createSubagentHandler", () => {
       }
     );
 
-    const lastCall = startMock.mock.calls[startMock.mock.calls.length - 1];
-    if (!lastCall) throw new Error("expected startChild call");
+    const lastCall = execMock.mock.calls[execMock.mock.calls.length - 1];
+    if (!lastCall) throw new Error("expected executeChild call");
     const workflowInput = lastCall[1].args[1] as SubagentWorkflowInput;
     expect(workflowInput.sandbox).toBeUndefined();
   });
 
   it("does not pass sandboxId when sandbox is explicitly none", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
 
     const noneSubagent: SubagentConfig = {
       agentName: "none-agent",
@@ -932,8 +928,8 @@ describe("createSubagentHandler", () => {
       }
     );
 
-    const lastCall = startMock.mock.calls[startMock.mock.calls.length - 1];
-    if (!lastCall) throw new Error("expected startChild call");
+    const lastCall = execMock.mock.calls[execMock.mock.calls.length - 1];
+    if (!lastCall) throw new Error("expected executeChild call");
     const workflowInput = lastCall[1].args[1] as SubagentWorkflowInput;
     expect(workflowInput.sandbox).toBeUndefined();
   });
@@ -961,8 +957,8 @@ describe("createSubagentHandler", () => {
   // --- inherit + continuation: fork ---
 
   it("forks from parent sandbox when inherit + continuation=fork", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
 
     const config: SubagentConfig = {
       agentName: "inherit-fork",
@@ -987,8 +983,8 @@ describe("createSubagentHandler", () => {
       }
     );
 
-    const lastCall = startMock.mock.calls.at(-1);
-    if (!lastCall) throw new Error("expected startChild call");
+    const lastCall = execMock.mock.calls.at(-1);
+    if (!lastCall) throw new Error("expected executeChild call");
     const workflowInput = lastCall[1].args[1] as SubagentWorkflowInput;
     expect(workflowInput.sandbox).toEqual({
       mode: "fork",
@@ -999,8 +995,8 @@ describe("createSubagentHandler", () => {
   // --- own + continuation: continue ---
 
   it("passes sandbox continue on thread continuation with continuation=continue", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
 
     nextStartChildResult = () => ({
       toolResponse: "first",
@@ -1045,8 +1041,8 @@ describe("createSubagentHandler", () => {
       { threadId: "t", toolCallId: "tc-2", toolName: "Subagent" }
     );
 
-    const secondCall = startMock.mock.calls.at(-1);
-    if (!secondCall) throw new Error("expected startChild call");
+    const secondCall = execMock.mock.calls.at(-1);
+    if (!secondCall) throw new Error("expected executeChild call");
     const workflowInput = secondCall[1].args[1] as SubagentWorkflowInput;
     expect(workflowInput.sandbox).toEqual({
       mode: "continue",
@@ -1058,8 +1054,8 @@ describe("createSubagentHandler", () => {
   // --- own + init: once + continuation: fork ---
 
   it("stores sandbox on first call and forks from it on second call (init=once, continuation=fork)", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
 
     nextStartChildResult = () => ({
       toolResponse: "first",
@@ -1088,8 +1084,8 @@ describe("createSubagentHandler", () => {
     );
 
     // First call: no sandbox init (child creates fresh), forced pause-until-parent-close
-    const firstCall = startMock.mock.calls.at(-1);
-    if (!firstCall) throw new Error("expected startChild call");
+    const firstCall = execMock.mock.calls.at(-1);
+    if (!firstCall) throw new Error("expected executeChild call");
     const firstInput = firstCall[1].args[1] as SubagentWorkflowInput;
     expect(firstInput.sandbox).toBeUndefined();
     expect(firstInput.sandboxShutdown).toBe("pause-until-parent-close");
@@ -1107,8 +1103,8 @@ describe("createSubagentHandler", () => {
       { threadId: "t", toolCallId: "tc-2", toolName: "Subagent" }
     );
 
-    const secondCall = startMock.mock.calls.at(-1);
-    if (!secondCall) throw new Error("expected startChild call");
+    const secondCall = execMock.mock.calls.at(-1);
+    if (!secondCall) throw new Error("expected executeChild call");
     const secondInput = secondCall[1].args[1] as SubagentWorkflowInput;
     expect(secondInput.sandbox).toEqual({
       mode: "fork",
@@ -1119,8 +1115,8 @@ describe("createSubagentHandler", () => {
   // --- own + init: once + continuation: continue ---
 
   it("stores sandbox on first call and continues it on second call (init=once, continuation=continue)", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
 
     nextStartChildResult = () => ({
       toolResponse: "first",
@@ -1160,8 +1156,8 @@ describe("createSubagentHandler", () => {
       { threadId: "t", toolCallId: "tc-2", toolName: "Subagent" }
     );
 
-    const secondCall = startMock.mock.calls.at(-1);
-    if (!secondCall) throw new Error("expected startChild call");
+    const secondCall = execMock.mock.calls.at(-1);
+    if (!secondCall) throw new Error("expected executeChild call");
     const secondInput = secondCall[1].args[1] as SubagentWorkflowInput;
     expect(secondInput.sandbox).toEqual({
       mode: "continue",
@@ -1398,8 +1394,8 @@ describe("createSubagentHandler", () => {
   // --- mustSurvive does not override user shutdown ---
 
   it("does not override keep-until-parent-close with pause-until-parent-close for init=once", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
 
     nextStartChildResult = () => ({
       toolResponse: "first",
@@ -1428,15 +1424,15 @@ describe("createSubagentHandler", () => {
       { threadId: "t", toolCallId: "tc-1", toolName: "Subagent" }
     );
 
-    const firstCall = startMock.mock.calls.at(-1);
-    if (!firstCall) throw new Error("expected startChild call");
+    const firstCall = execMock.mock.calls.at(-1);
+    if (!firstCall) throw new Error("expected executeChild call");
     const firstInput = firstCall[1].args[1] as SubagentWorkflowInput;
     expect(firstInput.sandboxShutdown).toBe("keep-until-parent-close");
   });
 
   it("does not override pause with pause-until-parent-close for init=once", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
 
     nextStartChildResult = () => ({
       toolResponse: "first",
@@ -1465,15 +1461,15 @@ describe("createSubagentHandler", () => {
       { threadId: "t", toolCallId: "tc-1", toolName: "Subagent" }
     );
 
-    const firstCall = startMock.mock.calls.at(-1);
-    if (!firstCall) throw new Error("expected startChild call");
+    const firstCall = execMock.mock.calls.at(-1);
+    if (!firstCall) throw new Error("expected executeChild call");
     const firstInput = firstCall[1].args[1] as SubagentWorkflowInput;
     expect(firstInput.sandboxShutdown).toBe("pause");
   });
 
   it("does not override keep with pause for continuation=continue", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
 
     nextStartChildResult = () => ({
       toolResponse: "first",
@@ -1502,15 +1498,15 @@ describe("createSubagentHandler", () => {
       { threadId: "t", toolCallId: "tc-1", toolName: "Subagent" }
     );
 
-    const firstCall = startMock.mock.calls.at(-1);
-    if (!firstCall) throw new Error("expected startChild call");
+    const firstCall = execMock.mock.calls.at(-1);
+    if (!firstCall) throw new Error("expected executeChild call");
     const firstInput = firstCall[1].args[1] as SubagentWorkflowInput;
     expect(firstInput.sandboxShutdown).toBe("keep");
   });
 
   it("still overrides destroy with pause for continuation=continue", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
 
     nextStartChildResult = () => ({
       toolResponse: "first",
@@ -1539,8 +1535,8 @@ describe("createSubagentHandler", () => {
       { threadId: "t", toolCallId: "tc-1", toolName: "Subagent" }
     );
 
-    const firstCall = startMock.mock.calls.at(-1);
-    if (!firstCall) throw new Error("expected startChild call");
+    const firstCall = execMock.mock.calls.at(-1);
+    if (!firstCall) throw new Error("expected executeChild call");
     const firstInput = firstCall[1].args[1] as SubagentWorkflowInput;
     expect(firstInput.sandboxShutdown).toBe("pause");
   });
@@ -1548,8 +1544,8 @@ describe("createSubagentHandler", () => {
   // --- snapshot continuation ---
 
   it("forces sandboxShutdown=snapshot and passes no sandbox on first call (continuation=snapshot)", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
 
     nextStartChildResult = () => ({
       toolResponse: "first",
@@ -1589,16 +1585,16 @@ describe("createSubagentHandler", () => {
       { threadId: "t", toolCallId: "tc-1", toolName: "Subagent" }
     );
 
-    const firstCall = startMock.mock.calls.at(-1);
-    if (!firstCall) throw new Error("expected startChild call");
+    const firstCall = execMock.mock.calls.at(-1);
+    if (!firstCall) throw new Error("expected executeChild call");
     const firstInput = firstCall[1].args[1] as SubagentWorkflowInput;
     expect(firstInput.sandbox).toBeUndefined();
     expect(firstInput.sandboxShutdown).toBe("snapshot");
   });
 
   it("boots follow-up from stored thread snapshot on continuation=snapshot", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
 
     nextStartChildResult = () => ({
       toolResponse: "first",
@@ -1660,8 +1656,8 @@ describe("createSubagentHandler", () => {
       { threadId: "t", toolCallId: "tc-2", toolName: "Subagent" }
     );
 
-    const secondCall = startMock.mock.calls.at(-1);
-    if (!secondCall) throw new Error("expected startChild call");
+    const secondCall = execMock.mock.calls.at(-1);
+    if (!secondCall) throw new Error("expected executeChild call");
     const secondInput = secondCall[1].args[1] as SubagentWorkflowInput;
     expect(secondInput.sandbox).toEqual({
       mode: "from-snapshot",
@@ -1671,8 +1667,8 @@ describe("createSubagentHandler", () => {
   });
 
   it("uses per-agent base snapshot for a new thread when init=once + continuation=snapshot", async () => {
-    const { startChild } = await import("@temporalio/workflow");
-    const startMock = startChild as ReturnType<typeof vi.fn>;
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
 
     // First call — establishes base snapshot.
     nextStartChildResult = () => ({
@@ -1731,8 +1727,8 @@ describe("createSubagentHandler", () => {
       { threadId: "t", toolCallId: "tc-2", toolName: "Subagent" }
     );
 
-    const secondCall = startMock.mock.calls.at(-1);
-    if (!secondCall) throw new Error("expected startChild call");
+    const secondCall = execMock.mock.calls.at(-1);
+    if (!secondCall) throw new Error("expected executeChild call");
     const secondInput = secondCall[1].args[1] as SubagentWorkflowInput;
     expect(secondInput.sandbox).toEqual({
       mode: "from-snapshot",
@@ -1814,6 +1810,173 @@ describe("createSubagentHandler", () => {
     expect(deletedTags.sort()).toEqual(["base", "exit-2"]);
   });
 
+  it("publishes persistentBaseSnapshot from childSandboxReadySignal before child completes", async () => {
+    const { setHandler, executeChild } = await import("@temporalio/workflow");
+    const setHandlerMock = setHandler as ReturnType<typeof vi.fn>;
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
+
+    const signalBase = {
+      sandboxId: "sb-signal",
+      providerId: "test",
+      data: { tag: "signal-base" },
+      createdAt: new Date().toISOString(),
+    };
+
+    const config: SubagentConfig = {
+      agentName: "snap-agent",
+      description: "Snapshot-driven",
+      workflow: mockWorkflow(),
+      thread: "continue",
+      sandbox: {
+        source: "own",
+        init: "once",
+        continuation: "snapshot",
+        proxy: noopSandboxProxy,
+      },
+    };
+
+    const { handler } = createSubagentHandler([config]);
+
+    // Fire the signal from inside executeChild so persistentBaseSnapshot is
+    // set before the child's own result is returned. The child result itself
+    // intentionally omits baseSnapshot — only the signal path can populate
+    // the map for this call.
+    execMock.mockImplementationOnce(
+      async (_wf: unknown, opts: { workflowId: string; args: unknown[] }) => {
+        const reg = setHandlerMock.mock.calls
+          .filter(
+            ([sig]) => (sig as { name?: string })?.name === "childSandboxReady"
+          )
+          .at(-1);
+        const signalHandler = reg?.[1] as
+          | ((p: {
+              childWorkflowId: string;
+              sandboxId: string;
+              baseSnapshot?: unknown;
+            }) => void)
+          | undefined;
+        signalHandler?.({
+          childWorkflowId: opts.workflowId,
+          sandboxId: "sb-signal",
+          baseSnapshot: signalBase,
+        });
+        return {
+          toolResponse: "first",
+          data: null,
+          threadId: "child-sig-1",
+        };
+      }
+    );
+
+    await handler(
+      { subagent: "snap-agent", description: "test", prompt: "first" },
+      { threadId: "t", toolCallId: "tc-1", toolName: "Subagent" }
+    );
+
+    // Second call on a new thread must boot from the signal-published base.
+    nextStartChildResult = () => ({
+      toolResponse: "second",
+      data: null,
+      threadId: "child-sig-2",
+    });
+
+    await handler(
+      { subagent: "snap-agent", description: "test", prompt: "second" },
+      { threadId: "t", toolCallId: "tc-2", toolName: "Subagent" }
+    );
+
+    const secondCall = execMock.mock.calls.at(-1);
+    if (!secondCall) throw new Error("expected executeChild call");
+    const secondInput = secondCall[1].args[1] as SubagentWorkflowInput;
+    expect(secondInput.sandbox).toEqual({
+      mode: "from-snapshot",
+      snapshot: expect.objectContaining({ data: { tag: "signal-base" } }),
+    });
+  });
+
+  it("ignores signal baseSnapshot for non-snapshot-base creators", async () => {
+    const { setHandler, executeChild } = await import("@temporalio/workflow");
+    const setHandlerMock = setHandler as ReturnType<typeof vi.fn>;
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
+
+    const config: SubagentConfig = {
+      agentName: "lazy-fork-agent",
+      description: "Lazy fork (not snapshot)",
+      workflow: mockWorkflow(),
+      sandbox: {
+        source: "own",
+        init: "once",
+        continuation: "fork",
+        proxy: noopSandboxProxy,
+      },
+    };
+
+    const { handler } = createSubagentHandler([config]);
+
+    execMock.mockImplementationOnce(
+      async (_wf: unknown, opts: { workflowId: string; args: unknown[] }) => {
+        const reg = setHandlerMock.mock.calls
+          .filter(
+            ([sig]) => (sig as { name?: string })?.name === "childSandboxReady"
+          )
+          .at(-1);
+        const signalHandler = reg?.[1] as
+          | ((p: {
+              childWorkflowId: string;
+              sandboxId: string;
+              baseSnapshot?: unknown;
+            }) => void)
+          | undefined;
+        // Stray baseSnapshot on a non-snapshot path must not land in
+        // persistentBaseSnapshot, or it would corrupt a different agent's
+        // snapshot flow.
+        signalHandler?.({
+          childWorkflowId: opts.workflowId,
+          sandboxId: "sb-lazy",
+          baseSnapshot: {
+            sandboxId: "sb-lazy",
+            providerId: "test",
+            data: { tag: "should-be-ignored" },
+            createdAt: new Date().toISOString(),
+          },
+        });
+        return {
+          toolResponse: "first",
+          data: null,
+          threadId: "child-lazy-1",
+          sandboxId: "sb-lazy",
+        };
+      }
+    );
+
+    await handler(
+      { subagent: "lazy-fork-agent", description: "test", prompt: "first" },
+      { threadId: "t", toolCallId: "tc-1", toolName: "Subagent" }
+    );
+
+    // Second call should fork from the lazy-published sandbox, not restore
+    // from any snapshot.
+    nextStartChildResult = () => ({
+      toolResponse: "second",
+      data: null,
+      threadId: "child-lazy-2",
+      sandboxId: "sb-lazy",
+    });
+
+    await handler(
+      { subagent: "lazy-fork-agent", description: "test", prompt: "second" },
+      { threadId: "t", toolCallId: "tc-2", toolName: "Subagent" }
+    );
+
+    const secondCall = execMock.mock.calls.at(-1);
+    if (!secondCall) throw new Error("expected executeChild call");
+    const secondInput = secondCall[1].args[1] as SubagentWorkflowInput;
+    expect(secondInput.sandbox).toEqual({
+      mode: "fork",
+      sandboxId: "sb-lazy",
+    });
+  });
+
   it("does not call deleteSandboxSnapshot for children that produced no snapshots", async () => {
     const opsMock = makeMockSandboxOps();
     const config: SubagentConfig = {
@@ -1847,6 +2010,195 @@ describe("createSubagentHandler", () => {
 
     expect(opsMock.deleteSandboxSnapshot).not.toHaveBeenCalled();
   });
+
+  // -------------------------------------------------------------------------
+  // Child workflow failure propagation
+  // -------------------------------------------------------------------------
+
+  it("propagates executeChild failure to the caller instead of hanging", async () => {
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
+    execMock.mockImplementationOnce(async () => {
+      throw new Error("Child Workflow execution failed: timeout");
+    });
+
+    const { handler } = createSubagentHandler([
+      {
+        agentName: "researcher",
+        description: "Researches topics",
+        workflow: mockWorkflow("researcherWorkflow"),
+      },
+    ]);
+
+    await expect(
+      handler(
+        { subagent: "researcher", description: "test", prompt: "hi" },
+        { threadId: "t", toolCallId: "tc", toolName: "Subagent" }
+      )
+    ).rejects.toThrow("Child Workflow execution failed: timeout");
+  });
+
+  it("applies a default workflowRunTimeout when workflowOptions is omitted", async () => {
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
+
+    const { DEFAULT_SUBAGENT_WORKFLOW_RUN_TIMEOUT } = await import("./handler");
+
+    const { handler } = createSubagentHandler([
+      {
+        agentName: "researcher",
+        description: "Researches topics",
+        workflow: mockWorkflow("researcherWorkflow"),
+      },
+    ]);
+
+    await handler(
+      { subagent: "researcher", description: "test", prompt: "hi" },
+      { threadId: "t", toolCallId: "tc", toolName: "Subagent" }
+    );
+
+    const lastCall = execMock.mock.calls[execMock.mock.calls.length - 1];
+    if (!lastCall) throw new Error("expected executeChild call");
+    expect(lastCall[1].workflowRunTimeout).toBe(
+      DEFAULT_SUBAGENT_WORKFLOW_RUN_TIMEOUT
+    );
+  });
+
+  it("lets workflowOptions.workflowRunTimeout override the default", async () => {
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
+
+    const { handler } = createSubagentHandler([
+      {
+        agentName: "researcher",
+        description: "Researches topics",
+        workflow: mockWorkflow("researcherWorkflow"),
+        workflowOptions: { workflowRunTimeout: "30s" },
+      },
+    ]);
+
+    await handler(
+      { subagent: "researcher", description: "test", prompt: "hi" },
+      { threadId: "t", toolCallId: "tc", toolName: "Subagent" }
+    );
+
+    const lastCall = execMock.mock.calls[execMock.mock.calls.length - 1];
+    if (!lastCall) throw new Error("expected executeChild call");
+    expect(lastCall[1].workflowRunTimeout).toBe("30s");
+  });
+
+  it("forwards workflowOptions to executeChild", async () => {
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
+
+    const { handler } = createSubagentHandler([
+      {
+        agentName: "researcher",
+        description: "Researches topics",
+        workflow: mockWorkflow("researcherWorkflow"),
+        workflowOptions: {
+          workflowRunTimeout: "5m",
+          workflowTaskTimeout: "30s",
+          retry: { maximumAttempts: 1 },
+        },
+      },
+    ]);
+
+    await handler(
+      { subagent: "researcher", description: "test", prompt: "hi" },
+      { threadId: "t", toolCallId: "tc", toolName: "Subagent" }
+    );
+
+    const lastCall = execMock.mock.calls[execMock.mock.calls.length - 1];
+    if (!lastCall) throw new Error("expected executeChild call");
+    expect(lastCall[1]).toMatchObject({
+      workflowRunTimeout: "5m",
+      workflowTaskTimeout: "30s",
+      retry: { maximumAttempts: 1 },
+    });
+  });
+
+  it("does not let workflowOptions override workflowId, taskQueue, or args", async () => {
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
+
+    const { handler } = createSubagentHandler([
+      {
+        agentName: "researcher",
+        description: "Researches topics",
+        workflow: mockWorkflow("researcherWorkflow"),
+        taskQueue: "my-queue",
+        workflowOptions: {
+          // Intentionally violates the public Omit<> type to prove the
+          // handler still wins at runtime. Cast removes the type error.
+          ...({
+            workflowId: "forbidden-id",
+            taskQueue: "forbidden-queue",
+            args: ["forbidden"],
+          } as Record<string, unknown>),
+        },
+      },
+    ]);
+
+    await handler(
+      { subagent: "researcher", description: "test", prompt: "hello" },
+      { threadId: "t", toolCallId: "tc", toolName: "Subagent" }
+    );
+
+    const lastCall = execMock.mock.calls[execMock.mock.calls.length - 1];
+    if (!lastCall) throw new Error("expected executeChild call");
+    expect(lastCall[1].workflowId).not.toBe("forbidden-id");
+    expect(lastCall[1].workflowId).toMatch(/^researcher-/);
+    expect(lastCall[1].taskQueue).toBe("my-queue");
+    expect(lastCall[1].args[0]).toBe("hello");
+  });
+
+  it("clears lazy-creator bookkeeping on failure so the next call can re-try", async () => {
+    const opsMock = makeMockSandboxOps();
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
+
+    const lazySubagent: SubagentConfig = {
+      agentName: "lazy",
+      description: "Lazy sandbox init",
+      workflow: mockWorkflow(),
+      sandbox: {
+        source: "own",
+        init: "once",
+        continuation: "fork",
+        proxy: () => opsMock,
+      },
+    };
+
+    const { handler } = createSubagentHandler([lazySubagent]);
+
+    execMock.mockImplementationOnce(async () => {
+      throw new Error("init failed");
+    });
+
+    await expect(
+      handler(
+        { subagent: "lazy", description: "test", prompt: "first" },
+        { threadId: "t", toolCallId: "tc-1", toolName: "Subagent" }
+      )
+    ).rejects.toThrow("init failed");
+
+    // A second call must be able to take the creator role again (no stranded
+    // "creating" flag) and succeed.
+    nextStartChildResult = () => ({
+      toolResponse: "ok",
+      data: null,
+      threadId: "child-t-2",
+      sandboxId: "child-sb-2",
+    });
+
+    const result = await handler(
+      { subagent: "lazy", description: "test", prompt: "second" },
+      { threadId: "t", toolCallId: "tc-2", toolName: "Subagent" }
+    );
+
+    expect(result.toolResponse).toBe("ok");
+  });
 });
 
 // ---------------------------------------------------------------------------
@@ -2054,6 +2406,7 @@ describe("defineSubagentWorkflow", () => {
       sandboxShutdown: "destroy",
       thread: { mode: "fork", threadId: "prev-42" },
       onSandboxReady: expect.any(Function),
+      onSessionExit: expect.any(Function),
     });
   });
 
@@ -2073,6 +2426,7 @@ describe("defineSubagentWorkflow", () => {
       sandboxShutdown: "destroy",
       sandbox: { mode: "inherit", sandboxId: "sb-123" },
       onSandboxReady: expect.any(Function),
+      onSessionExit: expect.any(Function),
     });
   });
 
@@ -2092,6 +2446,7 @@ describe("defineSubagentWorkflow", () => {
       sandboxShutdown: "destroy",
       sandbox: { mode: "fork", sandboxId: "prev-sb-1" },
       onSandboxReady: expect.any(Function),
+      onSessionExit: expect.any(Function),
     });
   });
 
@@ -2115,6 +2470,7 @@ describe("defineSubagentWorkflow", () => {
       thread: { mode: "fork", threadId: "prev-t" },
       sandbox: { mode: "fork", sandboxId: "prev-sb" },
       onSandboxReady: expect.any(Function),
+      onSessionExit: expect.any(Function),
     });
   });
 
@@ -2185,6 +2541,7 @@ describe("defineSubagentWorkflow", () => {
       agentName: "test",
       sandboxShutdown: "destroy",
       onSandboxReady: expect.any(Function),
+      onSessionExit: expect.any(Function),
     });
   });
 
@@ -2207,4 +2564,171 @@ describe("defineSubagentWorkflow", () => {
 
     expect(capturedSession?.sandboxShutdown).toBe("keep-until-parent-close");
   });
+
+  // -------------------------------------------------------------------------
+  // Auto-forwarding of session outputs + signal payload
+  // -------------------------------------------------------------------------
+
+  it("auto-forwards baseSnapshot captured via onSandboxReady", async () => {
+    const baseSnapshot = {
+      sandboxId: "sb-1",
+      providerId: "test",
+      data: { tag: "base" },
+      createdAt: new Date().toISOString(),
+    };
+    const workflow = defineSubagentWorkflow(
+      { name: "test", description: "test agent" },
+      async (_prompt, sessionInput) => {
+        sessionInput.onSandboxReady?.({ sandboxId: "sb-1", baseSnapshot });
+        return { toolResponse: "ok", data: null, threadId: "t" };
+      }
+    );
+
+    const result = await workflow("go", {});
+    expect(result.baseSnapshot).toEqual(baseSnapshot);
+  });
+
+  it("auto-forwards sandboxId and snapshot captured via onSessionExit", async () => {
+    const snapshot = {
+      sandboxId: "sb-1",
+      providerId: "test",
+      data: { tag: "exit" },
+      createdAt: new Date().toISOString(),
+    };
+    const workflow = defineSubagentWorkflow(
+      { name: "test", description: "test agent" },
+      async (_prompt, sessionInput) => {
+        sessionInput.onSessionExit?.({
+          sandboxId: "sb-1",
+          snapshot,
+          threadId: "t",
+        });
+        return { toolResponse: "ok", data: null, threadId: "t" };
+      }
+    );
+
+    const result = await workflow("go", {});
+    expect(result.sandboxId).toBe("sb-1");
+    expect(result.snapshot).toEqual(snapshot);
+  });
+
+  it("fn-explicit sandbox outputs win over captured session outputs", async () => {
+    const workflow = defineSubagentWorkflow(
+      { name: "test", description: "test agent" },
+      async (_prompt, sessionInput) => {
+        sessionInput.onSessionExit?.({
+          sandboxId: "session-sb",
+          snapshot: {
+            sandboxId: "session-sb",
+            providerId: "test",
+            data: { tag: "session" },
+            createdAt: new Date().toISOString(),
+          },
+          threadId: "t",
+        });
+        return {
+          toolResponse: "ok",
+          data: null,
+          threadId: "t",
+          sandboxId: "explicit-sb",
+          snapshot: {
+            sandboxId: "explicit-sb",
+            providerId: "test",
+            data: { tag: "explicit" },
+            createdAt: new Date().toISOString(),
+          },
+        };
+      }
+    );
+
+    const result = await workflow("go", {});
+    expect(result.sandboxId).toBe("explicit-sb");
+    expect(
+      (result.snapshot as { data: { tag: string } } | undefined)?.data
+    ).toEqual({ tag: "explicit" });
+  });
+
+  it("signals parent with baseSnapshot via childSandboxReadySignal", async () => {
+    const { getExternalWorkflowHandle } = await import("@temporalio/workflow");
+    const ghMock = getExternalWorkflowHandle as ReturnType<typeof vi.fn>;
+    const baseSnapshot = {
+      sandboxId: "sb-1",
+      providerId: "test",
+      data: { tag: "base" },
+      createdAt: new Date().toISOString(),
+    };
+
+    const workflow = defineSubagentWorkflow(
+      { name: "test", description: "test agent" },
+      async (_prompt, sessionInput) => {
+        sessionInput.onSandboxReady?.({ sandboxId: "sb-1", baseSnapshot });
+        return { toolResponse: "ok", data: null, threadId: "t" };
+      }
+    );
+
+    await workflow("go", {});
+
+    const handle = ghMock.mock.results.at(-1)?.value as {
+      signal: ReturnType<typeof vi.fn>;
+    };
+    expect(handle.signal).toHaveBeenCalledWith(
+      expect.objectContaining({ name: "childSandboxReady" }),
+      expect.objectContaining({
+        childWorkflowId: "child-wf-1",
+        sandboxId: "sb-1",
+        baseSnapshot,
+      })
+    );
+  });
+
+  it("omits baseSnapshot from signal when session did not capture one", async () => {
+    const { getExternalWorkflowHandle } = await import("@temporalio/workflow");
+    const ghMock = getExternalWorkflowHandle as ReturnType<typeof vi.fn>;
+
+    const workflow = defineSubagentWorkflow(
+      { name: "test", description: "test agent" },
+      async (_prompt, sessionInput) => {
+        sessionInput.onSandboxReady?.({ sandboxId: "sb-1" });
+        return { toolResponse: "ok", data: null, threadId: "t" };
+      }
+    );
+
+    await workflow("go", {});
+
+    const handle = ghMock.mock.results.at(-1)?.value as {
+      signal: ReturnType<typeof vi.fn>;
+    };
+    const payload = handle.signal.mock.calls.at(-1)?.[1] as {
+      childWorkflowId: string;
+      sandboxId: string;
+      baseSnapshot?: unknown;
+    };
+    expect(payload).toEqual({
+      childWorkflowId: "child-wf-1",
+      sandboxId: "sb-1",
+    });
+    expect(payload.baseSnapshot).toBeUndefined();
+  });
+
+  it("skips the signal when the sandbox is reused (continue mode)", async () => {
+    const { getExternalWorkflowHandle } = await import("@temporalio/workflow");
+    const ghMock = getExternalWorkflowHandle as ReturnType<typeof vi.fn>;
+
+    const workflow = defineSubagentWorkflow(
+      { name: "test", description: "test agent" },
+      async (_prompt, sessionInput) => {
+        sessionInput.onSandboxReady?.({ sandboxId: "sb-1" });
+        return { toolResponse: "ok", data: null, threadId: "t" };
+      }
+    );
+
+    await workflow("go", {
+      sandbox: { mode: "continue", sandboxId: "sb-1" },
+    });
+
+    const handle = ghMock.mock.results.at(-1)?.value as {
+      signal: ReturnType<typeof vi.fn>;
+    };
+    expect(handle.signal).not.toHaveBeenCalled();
+  });
 });