@librechat/agents 3.4.0 → 3.4.2

package/src/tools/__tests__/SubagentExecutor.test.ts

@@ -1,9 +1,12 @@
 import { describe, it, expect, beforeEach } from '@jest/globals';
+import { GraphInterrupt, MemorySaver } from '@langchain/langgraph';
 import { AIMessage, HumanMessage, ToolMessage } from '@langchain/core/messages';
 import type { BaseMessage } from '@langchain/core/messages';
 import type {
   AgentInputs,
+  GraphSubagentConfig,
   ResolvedSubagentConfig,
+  ResolvedSingleAgentSubagentConfig,
   StandardGraphInput,
   SubagentUpdateEvent,
   SubagentUsageEvent,
@@ -13,12 +16,14 @@ import type {
 import type { StandardGraph } from '@/graphs/Graph';
 import {
   SubagentExecutor,
+  filterGraphSubagentResult,
   filterSubagentResult,
   resolveSubagentConfigs,
   buildChildInputs,
   summarizeEvent,
 } from '../subagent';
 import { sanitizeForwardedSubagentUpdateData } from '../subagent/SubagentExecutor';
+import { SUBAGENT_PARENT_BATCH_CONFIG_KEY } from '../subagent/SubagentReplay';
 import { Constants, Providers, GraphEvents, StepTypes } from '@/common';
 import { StreamLimitExceededError } from '@/llm/streamLimits';
 import { AgentContext } from '@/agents/AgentContext';
@@ -37,8 +42,8 @@ const makeChildInputs = (agentId = 'child-agent'): AgentInputs => ({
 
 const makeConfig = (
   type = 'researcher',
-  overrides: Partial<ResolvedSubagentConfig> = {}
-): ResolvedSubagentConfig => ({
+  overrides: Partial<ResolvedSingleAgentSubagentConfig> = {}
+): ResolvedSingleAgentSubagentConfig => ({
   type,
   name: 'Test Researcher',
   description: 'Researches things',
@@ -47,6 +52,18 @@ const makeConfig = (
 });
 
 describe('filterSubagentResult', () => {
+  it('treats a result member with no new AI message as textless completion', () => {
+    expect(
+      filterGraphSubagentResult(
+        {
+          messages: [new AIMessage('worker output')],
+          subagentResult: { agentId: 'result' },
+        },
+        'result'
+      )
+    ).toBe('Task completed');
+  });
+
   it('extracts text from last AIMessage string content', () => {
     const messages: BaseMessage[] = [
       new HumanMessage('task'),
@@ -218,7 +235,8 @@ describe('resolveSubagentConfigs', () => {
     const parentContext = AgentContext.fromConfig(parentInputs);
     const resolved = resolveSubagentConfigs([config], parentContext);
     expect(resolved).toHaveLength(1);
-    expect(resolved[0].agentInputs.agentId).toBe('child-agent');
+    const resolvedConfig = resolved[0];
+    expect(resolvedConfig.agentInputs.agentId).toBe('child-agent');
   });
 
   it('resolves self-spawn from parent _sourceInputs', () => {
@@ -231,8 +249,9 @@ describe('resolveSubagentConfigs', () => {
     const parentContext = AgentContext.fromConfig(parentInputs);
     const resolved = resolveSubagentConfigs([selfConfig], parentContext);
     expect(resolved).toHaveLength(1);
-    expect(resolved[0].agentInputs.provider).toBe(Providers.OPENAI);
-    expect(resolved[0].agentInputs.instructions).toBe(
+    const resolvedConfig = resolved[0];
+    expect(resolvedConfig.agentInputs.provider).toBe(Providers.OPENAI);
+    expect(resolvedConfig.agentInputs.instructions).toBe(
       'You are a parent agent.'
     );
   });
@@ -349,8 +368,7 @@ describe('buildChildInputs', () => {
     /**
      * Self-spawn: `resolveSubagentConfigs` fills `agentInputs` as a shallow
      * spread of the parent's `_sourceInputs`, so the parent-scoped direct
-     * tool would leak into a checkpointer-less child graph and fail with
-     * `No checkpointer set` — must be scrubbed.
+     * tool would leak into the child implicitly — it must be scrubbed.
      */
     const selfConfig: ResolvedSubagentConfig = {
       type: 'self',
@@ -365,9 +383,8 @@ describe('buildChildInputs', () => {
 
     /**
      * Explicit child config: a host that deliberately attaches its own
-     * in-process direct tools to a child keeps them (Codex #289 P2 —
-     * interrupt-capable tools still fail in children, but non-interrupting
-     * direct tools are legitimate there).
+     * in-process direct tools to a child keeps them (Codex #289 P2). With
+     * HITL enabled, interrupt-capable child tools use the shared checkpointer.
      */
     const explicitConfig: ResolvedSubagentConfig = {
       type: 'researcher',
@@ -496,6 +513,281 @@ describe('SubagentExecutor', () => {
     expect(result.messages).toEqual([]);
   });
 
+  it('fails graph HITL before factories, hooks, events, or usage can run', async () => {
+    const graphConfig: GraphSubagentConfig = {
+      kind: 'graph',
+      type: 'graph-team',
+      name: 'Graph Team',
+      description: 'Runs a graph.',
+      agents: [makeChildInputs('graph-member')],
+      edges: [],
+      entryAgentId: 'graph-member',
+      resultAgentId: 'graph-member',
+    };
+    const createChildGraph = jest.fn(makeNoopGraphFactory());
+    const createChildGraphByKind = jest.fn(
+      (): StandardGraph => makeNoopGraphFactory()()
+    );
+    const hook = jest.fn(async (): Promise<Record<string, never>> => ({}));
+    const hookRegistry = new HookRegistry();
+    hookRegistry.register('SubagentStart', { hooks: [hook] });
+    const update = jest.fn();
+    const handlerRegistry = new HandlerRegistry();
+    handlerRegistry.register(GraphEvents.ON_SUBAGENT_UPDATE, {
+      handle: update,
+    });
+    const usageSink = jest.fn();
+    const executor = createExecutor({
+      configs: new Map([[graphConfig.type, graphConfig]]),
+      humanInTheLoop: { enabled: true },
+      createChildGraph,
+      createChildGraphByKind,
+      hookRegistry,
+      parentHandlerRegistry: handlerRegistry,
+      usageSink,
+    });
+
+    const result = await executor.execute({
+      description: 'Do not run.',
+      subagentType: graphConfig.type,
+    });
+
+    expect(result.content).toBe(
+      'Error: Human-in-the-loop execution is not yet supported for graph subagents.'
+    );
+    expect(createChildGraph).not.toHaveBeenCalled();
+    expect(createChildGraphByKind).not.toHaveBeenCalled();
+    expect(hook).not.toHaveBeenCalled();
+    expect(update).not.toHaveBeenCalled();
+    expect(usageSink).not.toHaveBeenCalled();
+  });
+
+  it('fails closed when resumable execution has no parent tool call ID', async () => {
+    const createChildGraph = jest.fn(makeNoopGraphFactory());
+    const executor = createExecutor({
+      humanInTheLoop: { enabled: true },
+      createChildGraph,
+    });
+
+    const result = await executor.execute({
+      description: 'Do something',
+      subagentType: 'researcher',
+      threadId: 'durable-thread',
+    });
+
+    expect(result.content).toContain('requires a parent tool call ID');
+    expect(result.messages).toEqual([]);
+    expect(createChildGraph).not.toHaveBeenCalled();
+  });
+
+  it('persists terminal replay outcomes without an active child workflow', async () => {
+    const checkpointer = new MemorySaver();
+    const hookRegistry = new HookRegistry();
+    hookRegistry.registerSession('original-run', 'PreToolUse', {
+      hooks: [async (): Promise<Record<string, never>> => ({})],
+    });
+    const initialExecutor = createExecutor({
+      checkpointer,
+      hookRegistry,
+      humanInTheLoop: { enabled: true },
+      parentRunId: 'original-run',
+    });
+    const call = {
+      id: 'call_terminal',
+      name: Constants.SUBAGENT,
+      args: {
+        description: 'blocked before execution',
+        subagent_type: 'researcher',
+      },
+      type: 'tool_call' as const,
+    };
+    const originalConfig = {
+      configurable: {
+        thread_id: 'durable-parent',
+        checkpoint_id: 'parent-fork',
+        run_id: 'original-run',
+      },
+    };
+    const settled = {
+      output: new ToolMessage({
+        content: 'Blocked: policy',
+        status: 'error' as const,
+        name: Constants.SUBAGENT,
+        tool_call_id: call.id,
+      }),
+      additionalContexts: ['persisted context'],
+      resolvedArgs: { description: 'rewritten' },
+    };
+
+    await initialExecutor.persistSettledToolOutput(
+      call,
+      originalConfig,
+      settled
+    );
+
+    const rebuiltExecutor = createExecutor({
+      checkpointer,
+      hookRegistry,
+      humanInTheLoop: { enabled: true },
+      parentRunId: 'rebuilt-run',
+    });
+    const restored = await rebuiltExecutor.getSettledToolOutput(call, {
+      configurable: {
+        ...originalConfig.configurable,
+        run_id: 'rebuilt-run',
+      },
+    });
+
+    expect(restored?.output.content).toBe('Blocked: policy');
+    expect(restored?.additionalContexts).toEqual(['persisted context']);
+    expect(restored?.resolvedArgs).toEqual({ description: 'rewritten' });
+    expect(hookRegistry.hasHookFor('PreToolUse', 'original-run')).toBe(true);
+    expect(hookRegistry.hasHookFor('PreToolUse', 'rebuilt-run')).toBe(true);
+  });
+
+  it('persists an ordinary child error after the active workflow is released', async () => {
+    const checkpointer = new MemorySaver();
+    const invoke = jest.fn().mockRejectedValue(new Error('child failed'));
+    const executor = createExecutor({
+      checkpointer,
+      humanInTheLoop: { enabled: true },
+      createChildGraph: (): StandardGraph =>
+        ({
+          createWorkflow: () => ({
+            getState: jest.fn().mockResolvedValue({
+              values: {},
+              next: ['child-agent'],
+              tasks: [],
+            }),
+            invoke,
+          }),
+          clearHeavyState: jest.fn(),
+        }) as unknown as StandardGraph,
+    });
+    const call = {
+      id: 'call_error',
+      name: Constants.SUBAGENT,
+      args: { description: 'fail', subagent_type: 'researcher' },
+      type: 'tool_call' as const,
+    };
+    const runnableConfig = {
+      configurable: {
+        thread_id: 'durable-parent',
+        checkpoint_id: 'parent-fork',
+        run_id: 'original-run',
+      },
+    };
+    const result = await executor.execute({
+      description: 'fail',
+      subagentType: 'researcher',
+      threadId: 'durable-parent',
+      parentToolCallId: call.id,
+      parentConfigurable: runnableConfig.configurable,
+    });
+    expect(result.content).toBe('Subagent error: child failed');
+
+    await executor.persistSettledToolOutput(call, runnableConfig, {
+      output: new ToolMessage({
+        content: result.content,
+        name: Constants.SUBAGENT,
+        tool_call_id: call.id,
+      }),
+      additionalContexts: [],
+    });
+
+    const restored = await createExecutor({
+      checkpointer,
+      humanInTheLoop: { enabled: true },
+    }).getSettledToolOutput(call, runnableConfig);
+    expect(invoke).toHaveBeenCalledTimes(1);
+    expect(restored?.output.content).toBe('Subagent error: child failed');
+  });
+
+  it('continues a recovered in-progress child without reseeding its task', async () => {
+    const invoke = jest.fn().mockResolvedValue({
+      messages: [new AIMessage('continued')],
+    });
+    const executor = createExecutor({
+      checkpointer: new MemorySaver(),
+      humanInTheLoop: { enabled: true },
+      createChildGraph: (): StandardGraph =>
+        ({
+          createWorkflow: () => ({
+            getState: jest.fn().mockResolvedValue({
+              values: {},
+              next: ['child-agent'],
+              tasks: [],
+            }),
+            invoke,
+          }),
+          clearHeavyState: jest.fn(),
+        }) as unknown as StandardGraph,
+    });
+
+    const result = await executor.execute({
+      description: 'Do not duplicate this task',
+      subagentType: 'researcher',
+      threadId: 'durable-parent',
+      parentToolCallId: 'call_in_progress',
+    });
+
+    expect(result.content).toBe('continued');
+    expect(invoke).toHaveBeenCalledWith(null, expect.any(Object));
+  });
+
+  it('preserves an existing nested approval scope', async () => {
+    const nestedScope = {
+      run_id: 'grandchild-run',
+      agent_id: 'grandchild-agent',
+      subagent_type: 'grandchild',
+      parent_tool_call_id: 'call_grandchild',
+    };
+    const nestedInterrupt = new GraphInterrupt([
+      {
+        id: 'nested-interrupt',
+        value: {
+          type: 'tool_approval',
+          action_requests: [],
+          review_configs: [],
+          subagent: nestedScope,
+        },
+      },
+    ]);
+    const executor = createExecutor({
+      humanInTheLoop: { enabled: true },
+      createChildGraph: (): StandardGraph =>
+        ({
+          createWorkflow: () => ({
+            getState: jest.fn().mockResolvedValue({
+              values: {},
+              next: ['agent'],
+              tasks: [],
+            }),
+            invoke: jest.fn().mockRejectedValue(nestedInterrupt),
+          }),
+          clearHeavyState: jest.fn(),
+        }) as unknown as StandardGraph,
+    });
+
+    let received: GraphInterrupt | undefined;
+    try {
+      await executor.execute({
+        description: 'Delegate again',
+        subagentType: 'researcher',
+        threadId: 'durable-thread',
+        parentToolCallId: 'call_child',
+      });
+    } catch (error) {
+      if (error instanceof GraphInterrupt) {
+        received = error;
+      }
+    }
+
+    expect(received?.interrupts[0].value).toMatchObject({
+      subagent: nestedScope,
+    });
+  });
+
   it('rethrows a child stream-limit trip instead of converting it to a tool result', async () => {
     const executor = createExecutor({
       createChildGraph: (): StandardGraph =>
@@ -1393,6 +1685,7 @@ describe('SubagentExecutor', () => {
           checkpoint_id: 'parent-checkpoint-id',
           checkpoint_map: { parent: 'checkpoint' },
           checkpoint_ns: 'parent-checkpoint-ns',
+          [SUBAGENT_PARENT_BATCH_CONFIG_KEY]: 'assistant-batch',
           requestBody: { messageId: 'msg-1' },
           thread_id: 'parent-thread',
           user: { id: 'user_abc' },
@@ -1409,11 +1702,260 @@ describe('SubagentExecutor', () => {
       expect(configurable.checkpoint_id).toBeUndefined();
       expect(configurable.checkpoint_map).toBeUndefined();
       expect(configurable.checkpoint_ns).toBeUndefined();
+      expect(configurable[SUBAGENT_PARENT_BATCH_CONFIG_KEY]).toBeUndefined();
       expect(configurable.requestBody).toEqual({ messageId: 'msg-1' });
       expect(configurable.thread_id).toBe('parent-thread');
       expect(configurable.user).toEqual({ id: 'user_abc' });
     });
 
+    it('isolates child checkpoints created from different parent forks', async () => {
+      const invokedConfigs: Record<string, unknown>[] = [];
+      const invoke = jest
+        .fn()
+        .mockImplementation(
+          async (
+            _input: unknown,
+            config: Record<string, unknown>
+          ): Promise<{ messages: BaseMessage[] }> => {
+            invokedConfigs.push(config);
+            return { messages: [new AIMessage('done')] };
+          }
+        );
+      const executor = createExecutor({
+        humanInTheLoop: { enabled: true },
+        createChildGraph: (): StandardGraph =>
+          ({
+            createWorkflow: () => ({
+              getState: jest.fn().mockResolvedValue({
+                values: {},
+                next: [],
+                tasks: [],
+              }),
+              invoke,
+            }),
+            clearHeavyState: jest.fn(),
+          }) as unknown as StandardGraph,
+      });
+      const common = {
+        description: 'task',
+        subagentType: 'researcher',
+        threadId: 'parent-thread',
+        parentToolCallId: 'call_shared',
+      };
+
+      await executor.execute({
+        ...common,
+        parentConfigurable: {
+          thread_id: 'parent-thread',
+          checkpoint_id: 'fork-a',
+        },
+      });
+      await executor.execute({
+        ...common,
+        parentConfigurable: {
+          thread_id: 'parent-thread',
+          checkpoint_id: 'fork-b',
+        },
+      });
+
+      expect(invoke).toHaveBeenCalledTimes(2);
+      const childThreadIds = invokedConfigs.map(
+        (config) =>
+          (config.configurable as Record<string, unknown>).thread_id as string
+      );
+      expect(childThreadIds[0]).toMatch(/^subagent:/);
+      expect(childThreadIds[1]).toMatch(/^subagent:/);
+      expect(childThreadIds[0]).not.toBe(childThreadIds[1]);
+    });
+
+    it('isolates reused tool-call IDs across assistant batches', async () => {
+      const invokedThreadIds: string[] = [];
+      const executor = createExecutor({
+        humanInTheLoop: { enabled: true },
+        createChildGraph: (): StandardGraph =>
+          ({
+            createWorkflow: () => ({
+              getState: jest.fn().mockResolvedValue({
+                values: {},
+                next: [],
+                tasks: [],
+              }),
+              invoke: jest
+                .fn()
+                .mockImplementation(
+                  async (
+                    _input: unknown,
+                    invokeConfig: Record<string, unknown>
+                  ): Promise<{ messages: BaseMessage[] }> => {
+                    invokedThreadIds.push(
+                      (invokeConfig.configurable as Record<string, unknown>)
+                        .thread_id as string
+                    );
+                    return { messages: [new AIMessage('done')] };
+                  }
+                ),
+            }),
+            clearHeavyState: jest.fn(),
+          }) as unknown as StandardGraph,
+      });
+      const common = {
+        description: 'task',
+        subagentType: 'researcher',
+        threadId: 'parent-thread',
+        parentToolCallId: 'call_reused',
+      };
+
+      await executor.execute({
+        ...common,
+        parentConfigurable: {
+          thread_id: 'parent-thread',
+          [SUBAGENT_PARENT_BATCH_CONFIG_KEY]: 'assistant-batch-1',
+        },
+      });
+      await executor.execute({
+        ...common,
+        parentConfigurable: {
+          thread_id: 'parent-thread',
+          [SUBAGENT_PARENT_BATCH_CONFIG_KEY]: 'assistant-batch-2',
+        },
+      });
+
+      expect(invokedThreadIds).toHaveLength(2);
+      expect(invokedThreadIds[0]).not.toBe(invokedThreadIds[1]);
+    });
+
+    it('keeps ambiguous parent agent and tool-call components collision-free', async () => {
+      const invokedThreadIds: string[] = [];
+      const createChildGraph = (): StandardGraph =>
+        ({
+          createWorkflow: () => ({
+            getState: jest.fn().mockResolvedValue({
+              values: {},
+              next: [],
+              tasks: [],
+            }),
+            invoke: jest
+              .fn()
+              .mockImplementation(
+                async (
+                  _input: unknown,
+                  invokeConfig: Record<string, unknown>
+                ): Promise<{ messages: BaseMessage[] }> => {
+                  invokedThreadIds.push(
+                    (invokeConfig.configurable as Record<string, unknown>)
+                      .thread_id as string
+                  );
+                  return { messages: [new AIMessage('done')] };
+                }
+              ),
+          }),
+          clearHeavyState: jest.fn(),
+        }) as unknown as StandardGraph;
+      const common = {
+        description: 'task',
+        subagentType: 'researcher',
+        threadId: 'parent',
+        parentConfigurable: { thread_id: 'parent' },
+      };
+
+      await createExecutor({
+        checkpointer: new MemorySaver(),
+        humanInTheLoop: { enabled: true },
+        parentAgentId: 'a_b',
+        createChildGraph,
+      }).execute({ ...common, parentToolCallId: 'c' });
+      await createExecutor({
+        checkpointer: new MemorySaver(),
+        humanInTheLoop: { enabled: true },
+        parentAgentId: 'a',
+        createChildGraph,
+      }).execute({ ...common, parentToolCallId: 'b_c' });
+
+      expect(invokedThreadIds).toHaveLength(2);
+      expect(invokedThreadIds[0]).not.toBe(invokedThreadIds[1]);
+    });
+
+    it('retains owned child checkpoint threads after heavy-state cleanup', async () => {
+      const executor = createExecutor({
+        checkpointer: new MemorySaver(),
+        humanInTheLoop: { enabled: true },
+        createChildGraph: (): StandardGraph =>
+          ({
+            createWorkflow: () => ({
+              getState: jest.fn().mockResolvedValue({
+                values: {},
+                next: [],
+                tasks: [],
+              }),
+              invoke: jest.fn().mockResolvedValue({
+                messages: [new AIMessage('done')],
+              }),
+            }),
+            clearHeavyState: jest.fn(),
+          }) as unknown as StandardGraph,
+      });
+
+      await executor.execute({
+        description: 'task',
+        subagentType: 'researcher',
+        threadId: 'parent',
+        parentToolCallId: 'call_owned',
+      });
+      const beforeCleanup = executor.getChildCheckpointThreadIds();
+      executor.clearHeavyState();
+
+      expect(beforeCleanup).toHaveLength(1);
+      expect(executor.getChildCheckpointThreadIds()).toEqual(beforeCleanup);
+
+      executor.resetCheckpointThreadIds();
+      expect(executor.getChildCheckpointThreadIds()).toEqual([]);
+    });
+
+    it('includes checkpoint threads from active descendant graphs', async () => {
+      const grandchildThreadId = 'subagent:grandchild';
+      const executor = createExecutor({
+        checkpointer: new MemorySaver(),
+        humanInTheLoop: { enabled: true },
+        createChildGraph: (): StandardGraph =>
+          ({
+            createWorkflow: () => ({
+              getState: jest.fn().mockResolvedValue({
+                values: {},
+                next: ['child-agent'],
+                tasks: [],
+              }),
+              invoke: jest.fn().mockRejectedValue(
+                new GraphInterrupt([
+                  {
+                    id: 'grandchild-interrupt',
+                    value: {
+                      type: 'tool_approval',
+                      action_requests: [],
+                      review_configs: [],
+                    },
+                  },
+                ])
+              ),
+            }),
+            getChildCheckpointThreadIds: jest.fn(() => [grandchildThreadId]),
+            clearHeavyState: jest.fn(),
+          }) as unknown as StandardGraph,
+      });
+
+      await expect(
+        executor.execute({
+          description: 'nested task',
+          subagentType: 'researcher',
+          threadId: 'parent',
+          parentToolCallId: 'call_child',
+        })
+      ).rejects.toBeInstanceOf(GraphInterrupt);
+
+      expect(executor.getChildCheckpointThreadIds()).toEqual(
+        expect.arrayContaining([grandchildThreadId])
+      );
+    });
+
     it('does not require parentConfigurable (back-compat with hosts that omit it)', async () => {
       const { factory, getInvokeConfig } = makeCapturingGraphFactory();
       const executor = createExecutor({ createChildGraph: factory });
@@ -1427,7 +1969,6 @@ describe('SubagentExecutor', () => {
         string,
         unknown
       >;
-      // Only thread_id (childRunId fallback) is set when no parent context is supplied.
       expect(Object.keys(configurable)).toEqual(['thread_id']);
     });
   });
@@ -1502,6 +2043,67 @@ describe('SubagentExecutor', () => {
       expect(input.agentType).toBe('researcher');
     });
 
+    it('finishes missing child lifecycle after recovering a completed checkpoint', async () => {
+      const stopHook = jest.fn().mockResolvedValue({});
+      const hookRegistry = new HookRegistry();
+      hookRegistry.register('SubagentStop', { hooks: [stopHook] });
+      const updates: SubagentUpdateEvent[] = [];
+      const handlerRegistry = new HandlerRegistry();
+      handlerRegistry.register(GraphEvents.ON_SUBAGENT_UPDATE, {
+        handle: (_event, data): void => {
+          updates.push(data as SubagentUpdateEvent);
+        },
+      });
+      const invoke = jest.fn();
+      const updateState = jest.fn().mockResolvedValue({});
+      const executor = createExecutor({
+        humanInTheLoop: { enabled: true },
+        hookRegistry,
+        parentHandlerRegistry: handlerRegistry,
+        createChildGraph: (): StandardGraph =>
+          ({
+            createWorkflow: () => ({
+              getState: jest.fn().mockResolvedValue({
+                values: { messages: [new AIMessage('persisted result')] },
+                next: [],
+                tasks: [],
+              }),
+              invoke,
+              updateState,
+            }),
+            clearHeavyState: jest.fn(),
+          }) as unknown as StandardGraph,
+      });
+
+      const result = await executor.execute({
+        description: 'recover me',
+        subagentType: 'researcher',
+        threadId: 'durable-thread',
+        parentToolCallId: 'call_recovered',
+      });
+
+      expect(result.content).toBe('persisted result');
+      expect(invoke).not.toHaveBeenCalled();
+      expect(stopHook).toHaveBeenCalledTimes(1);
+      expect(updates.filter((update) => update.phase === 'stop')).toHaveLength(
+        1
+      );
+      expect(updateState).toHaveBeenCalledTimes(1);
+      expect(updateState.mock.calls[0][1]).toMatchObject({
+        messages: [
+          {
+            additional_kwargs: {
+              __librechat_subagent_checkpoint: {
+                version: 1,
+                parentToolCallId: 'call_recovered',
+                lifecycleComplete: true,
+              },
+            },
+          },
+        ],
+      });
+    });
+
     it('SubagentStart deny blocks execution', async () => {
       const registry = new HookRegistry();
       registry.register('SubagentStart', {
@@ -2022,6 +2624,107 @@ describe('SubagentExecutor', () => {
       expect(phases[phases.length - 1]).toBe('stop');
     });
 
+    it('does not let a stalled observational update handler block child completion', async () => {
+      jest.useFakeTimers();
+      try {
+        const registry = new HandlerRegistry();
+        const updateHandler = jest.fn(
+          (): Promise<void> => new Promise<void>(() => {})
+        );
+        registry.register(GraphEvents.ON_SUBAGENT_UPDATE, {
+          handle: updateHandler,
+        });
+        const { factory } = makeStubGraphFactory({
+          messages: [new AIMessage('ok')],
+        });
+        const executor = createExecutor({
+          createChildGraph: factory,
+          parentHandlerRegistry: registry,
+        });
+
+        const execution = executor.execute({
+          description: 'Task',
+          subagentType: 'researcher',
+        });
+        const outcome = Promise.race([
+          execution.then(({ content }) => content),
+          new Promise<string>((resolve) =>
+            setTimeout(() => resolve('stalled'), 20_000)
+          ),
+        ]);
+
+        await jest.advanceTimersByTimeAsync(20_000);
+
+        await expect(outcome).resolves.toBe('ok');
+        expect(updateHandler).toHaveBeenCalledTimes(2);
+      } finally {
+        jest.useRealTimers();
+      }
+    });
+
+    it('does not let a stalled queued update block the terminal stop envelope', async () => {
+      jest.useFakeTimers();
+      try {
+        const phases: SubagentUpdateEvent['phase'][] = [];
+        const registry = new HandlerRegistry();
+        registry.register(GraphEvents.ON_SUBAGENT_UPDATE, {
+          handle: (_event, rawData): void | Promise<void> => {
+            const update = rawData as SubagentUpdateEvent;
+            phases.push(update.phase);
+            if (update.phase === 'run_step') {
+              return new Promise<void>(() => {});
+            }
+          },
+        });
+        const factory: () => StandardGraph = (): StandardGraph =>
+          ({
+            createWorkflow: (): { invoke: jest.Mock } => ({
+              invoke: jest.fn().mockImplementation(async (_state, options) => {
+                const opts = options as { callbacks?: unknown[] };
+                const forwarder = (opts.callbacks ?? [])[0] as {
+                  handleCustomEvent?: (
+                    eventName: string,
+                    data: unknown
+                  ) => Promise<void> | void;
+                };
+                for (let index = 0; index < 80; index++) {
+                  await forwarder.handleCustomEvent?.(GraphEvents.ON_RUN_STEP, {
+                    id: `step_${index}`,
+                    type: StepTypes.MESSAGE_CREATION,
+                    agentId: 'researcher',
+                    index,
+                  });
+                }
+                return { messages: [new AIMessage('ok')] };
+              }),
+            }),
+            clearHeavyState: jest.fn(),
+          }) as unknown as StandardGraph;
+        const executor = createExecutor({
+          createChildGraph: factory,
+          parentHandlerRegistry: registry,
+        });
+
+        const execution = executor.execute({
+          description: 'Task',
+          subagentType: 'researcher',
+        });
+        const outcome = Promise.race([
+          execution.then(({ content }) => content),
+          new Promise<string>((resolve) =>
+            setTimeout(() => resolve('stalled'), 20_000)
+          ),
+        ]);
+
+        await jest.advanceTimersByTimeAsync(20_000);
+
+        await expect(outcome).resolves.toBe('ok');
+        expect(phases).toEqual(['start', 'run_step', 'stop']);
+      } finally {
+        jest.useRealTimers();
+      }
+    });
+
     it('allowlists forwarded run step payloads before wrapping them in ON_SUBAGENT_UPDATE', async () => {
       const subagentUpdates: SubagentUpdateEvent[] = [];
       const registry = new HandlerRegistry();
@@ -2149,18 +2852,32 @@ describe('SubagentExecutor', () => {
       expect(serialized).not.toContain('nested-completed-secret');
     });
 
-    it('does not drop non-droppable updates when the forwarding queue overflows', async () => {
+    it('bounds queued updates under overload while preserving lifecycle envelopes', async () => {
+      const phases: SubagentUpdateEvent['phase'][] = [];
       const completedIds: string[] = [];
+      let releaseFirstCompleted!: () => void;
+      const firstCompletedBlocked = new Promise<void>((resolve) => {
+        releaseFirstCompleted = resolve;
+      });
+      let markAllEmitted!: () => void;
+      const allEmitted = new Promise<void>((resolve) => {
+        markAllEmitted = resolve;
+      });
+      let blockedFirstCompleted = false;
       const registry = new HandlerRegistry();
       registry.register(GraphEvents.ON_SUBAGENT_UPDATE, {
         handle: async (_event, rawData): Promise<void> => {
           const update = rawData as SubagentUpdateEvent;
+          phases.push(update.phase);
           if (update.phase === 'run_step_completed') {
             const data = update.data as { result?: { id?: string } };
             if (data.result?.id != null) {
               completedIds.push(data.result.id);
             }
-            await new Promise((resolve) => setTimeout(resolve, 1));
+            if (!blockedFirstCompleted) {
+              blockedFirstCompleted = true;
+              await firstCompletedBlocked;
+            }
           }
         },
       });
@@ -2195,6 +2912,7 @@ describe('SubagentExecutor', () => {
                   }
                 );
               }
+              markAllEmitted();
               return { messages: [new AIMessage('ok')] };
             }),
           }),
@@ -2206,14 +2924,21 @@ describe('SubagentExecutor', () => {
         parentHandlerRegistry: registry,
       });
 
-      await executor.execute({
+      const execution = executor.execute({
         description: 'Task',
         subagentType: 'researcher',
       });
+      await allEmitted;
+      releaseFirstCompleted();
+      await execution;
 
-      expect(completedIds).toHaveLength(80);
+      expect(completedIds).toHaveLength(65);
       expect(completedIds[0]).toBe('step_0');
+      expect(completedIds).not.toContain('step_1');
+      expect(completedIds).toContain('step_16');
       expect(completedIds[completedIds.length - 1]).toBe('step_79');
+      expect(phases[0]).toBe('start');
+      expect(phases[phases.length - 1]).toBe('stop');
     });
 
     it('does NOT forward ON_TOOL_EXECUTE when the parent registry has no handler (safe fallback)', async () => {