Summary

When deliverSubagentAnnouncement direct-dispatch returns a non-terminal status (accepted/started/in_flight) and the requester parent is not actively streaming (yielded, queued, compaction-prep, or tool-result truncated), today's behaviour returns

{ delivered: false, reason: "completion_handoff_pending", error: "completion agent handoff is still pending" }

— which surfaces as the dominant signature in openclaw tasks audit --json delivery_failed findings: the requester parent never receives a child-completion event that already arrived in the gateway. From inside the requester, the symptom is a subagent that appears active (waiting on N children) with pendingDescendants > 0 indefinitely after the envelope's endedAt already fired, because the completion event can't deliver back.

This PR routes those cases into the requester's existing in-process durable system-event inbox instead, keyed by the announce idempotency key. The inbox is the same primitive used today by jobs, hooks, restart sentinels, ACP child spawns, monitor events, and the group/channel completion path in task-registry. It is idempotent on (text, contextKey, deliveryContext), bounded at 20 events per session, and drained on the parent's next turn-start.

What changed

• SubagentDeliveryPath union in subagent-announce-dispatch.ts extended with a new "durable_queue" literal (with doc comment).
• subagent-announce-delivery.ts: the directAnnounceStillPending give-up branch (when expectsCompletionMessage && expectedMediaUrls.length === 0 && !requiresMessageToolDelivery) now calls enqueueSystemEvent with contextKey: "subagent-announce:${params.directIdempotencyKey}" and deliveryContext: requesterSessionOrigin ?? completionExternalFallbackOrigin ?? directOrigin, returning { delivered: true, path: "durable_queue" }. Existing directIdempotencyKey is reused — no new param threading.
• Safety net: if enqueueSystemEvent itself throws, the original give-up payload ({ delivered: false, path: "direct", reason: "completion_handoff_pending", error: ... }) is returned so today's retry/give-up bookkeeping remains the floor.
• isDurableAgentHarnessCompletionDelivery in plugin-sdk/agent-harness-task-runtime.ts now treats "durable_queue" as durable, preventing the Codex native-subagent monitor from looping retry against an inbox that already idempotently holds the event.

Tail-risk: SubagentDeliveryPath consumers

Three real consumers; all safe:

Tests

• 5 unit tests in subagent-announce-delivery.test.ts — covers the new branch firing, idempotency on duplicate fires, no-fallback-on-active-stream (steered path wins), no-fallback-with-media (existing direct/media path preserved), and the result-envelope shape downstream consumers see.
• 1 integration test in embedded-agent-runner/sessions-yield.orchestration.test.ts — reproduces the failure class end-to-end: yielded parent → runEmbeddedAgent returns stopReason:"end_turn" → isEmbeddedAgentRunActive(parentSessionId) returns false → deliverSubagentAnnouncement with stubbed callGateway returning accepted → asserts path:"durable_queue", inbox holds the trigger, drainSystemEvents returns it, post-drain inbox empty.
• 1 unit test in agent-harness-task-runtime.test.ts — asserts durable_queue is treated as durable and that delivered:false still fails fast.

Targeted suite (5 files): 150/150 pass.

src/agents/subagent-announce-delivery.test.ts          97/97  (92 baseline + 5 new)
src/agents/subagent-announce-dispatch.test.ts          11/11  (no regression)
src/agents/subagent-registry-lifecycle.test.ts         30/30  (no regression)
src/agents/embedded-agent-runner/sessions-yield.orchestration.test.ts
                                                         5/5  (4 baseline + 1 new integration)
src/plugin-sdk/agent-harness-task-runtime.test.ts        7/7  (6 baseline + 1 new)

Full unit lane (pnpm test:unit): 10071 passed across 1055 files. The 5 failures observed are in src/commands/status.summary.runtime.test.ts (3) and src/agents/tools/subagents-tool.test.ts (2) — both of which fail identically on a clean unpatched main HEAD (verified via stash + re-run). Cause appears to be a test-isolation issue where those tests load the host's ~/.openclaw/openclaw.json rather than a sandboxed config; not related to this patch.

pnpm tsgo:core, pnpm tsgo:test:src, pnpm exec oxfmt --check (6 files), pnpm exec oxlint (6 files): all clean.

Not run

• pnpm test:e2e, pnpm test:live, pnpm test:docker:* — require live provider credentials and/or docker daemon access. The not_streaming failure class is exercised deterministically by the integration repro; patch surface is one branch in one direct-dispatch function plus one downstream consumer. Happy to run any of these on request from a maintainer who has the live secrets.

Out of scope (deliberate)

• The "recovery pointer" enrichment for delivery_failed audit findings (so the Brad-side watchdog could attempt automated retry) is held for a follow-up PR after this core fix lands. Filed mentally; not in this diff.

Origin / context

I wrote and operated a Brad-side audit watchdog (alert-only, 3-minute cadence) that has been catching every fresh delivery_failed incident on this side over the past day. The watchdog will stay alert-only and be retired after this fix is deployed and proven stable across multiple subagent flows. This PR is the upstream-side root-cause fix corresponding to the watchdog's mitigation surface.