PR #75786: fix(subagents): reconcile timed-out waits against child session state

• Repository: openclaw/openclaw
• Author: carlos-443-diaz
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/75786

Description (problem / solution / changelog)

Fixes #75785.

Summary

Reconcile timed-out agent.wait results against the persisted child session state before announcing subagent completion.

This fixes a false-timeout path where the child run can finish successfully, but the parent-side completion handoff still reports timed out and falls back to a partial-progress stub.

Problem / Motivation

The announce flow currently trusts the immediate agent.wait timeout result. In the observed failure mode, that timeout can be stale relative to the child session store state. When that happens, the parent announces a timeout even though the child session has already completed successfully.

What Changed

• src/agents/subagent-announce-output.ts
  • waitForSubagentRunOutcome(runId, timeoutMs, sessionKey?) now optionally re-checks session-store state after a timeout
  • added helpers to load and interpret the child session entry
• src/agents/subagent-announce.ts
  • pass childSessionKey into waitForSubagentRunOutcome(...)
  • do the same for the immediate recheck path
• src/agents/subagent-announce.timeout.test.ts
  • adds a regression test covering a timed-out wait that should reconcile to persisted child success before announcing

Why this is the smallest reliable guardrail

The reconciliation only runs:

• when agent.wait returns timeout
• when the child session key is available
• for a short bounded retry loop

Normal successful and failed paths are unchanged.

User-visible / Behavior Changes

Parent sessions stop receiving false timed out completion events for already-finished child runs in this path.

Diagram

Before:
child finishes successfully -> agent.wait returns timeout -> parent announces timeout -> actual child result is replaced by partial progress

After:
child finishes successfully -> agent.wait returns timeout -> announce flow rechecks child session state -> parent announces success -> child result is delivered

Security Impact

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No

Repro + Verification

Environment

• OS: Linux 6.8
• Runtime/container: npm global install
• Model/provider: openai-codex/gpt-5.4
• Integration/channel: subagent completion announce path
• Relevant config: default subagent announce flow with completion handoff enabled

Steps

1. Spawn a subagent that performs many tool calls and completes successfully.
2. Let the child session reach a terminal successful state.
3. Have the parent-side announce flow observe agent.wait return timeout.
4. Compare the child session state with the parent completion event.

Expected

• Parent completion announce resolves to child success and includes the child result.

Actual

• Parent completion announce can resolve to timeout and replace the child result with a partial-progress stub.

Evidence

• Trace/log snippets
• Failing test/log before + passing after
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification

• Verified scenarios:
  • observed a child run with successful terminal state while the parent announce path still emitted a timeout result
  • applied equivalent reconciliation logic locally in the installed build and confirmed it corrected the announce outcome for that bug path
• Edge cases checked:
  • no reconciliation path is used unless agent.wait returns timeout
  • still falls back to original timeout result if the child session store is not terminal
• What I did not verify:
  • full upstream CI suite
  • multi-provider or multi-channel coverage beyond the local reproduction path

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No

Risks and Mitigations

• Risk: session-store terminal state could be briefly stale in the opposite direction
  • Mitigation: reconciliation runs only after a timeout and only upgrades the announce outcome when the child session entry is already terminal
• Risk: additional small read on timeout path
  • Mitigation: only occurs on timeout, with a short bounded retry loop

Changed files

• src/agents/subagent-announce-output.ts (modified, +92/-1)
• src/agents/subagent-announce.timeout.test.ts (modified, +42/-0)
• src/agents/subagent-announce.ts (modified, +10/-2)