Summary

Fixes a set of subagent completion lifecycle races that can leave completed child runs stuck behind cleanup/announce sequencing or overwrite a terminal error with a later success signal.

The patch makes three related changes:

• Do not block completion announce delivery on browser-session cleanup. The cleanup is now started after the announce/cleanup flow is leased and runs best-effort in the background, with warnings captured instead of blocking the lifecycle path.
• Skip waiting for an active embedded child session when a frozen final reply is already available. If we already captured the reply text, the requester can be notified immediately instead of waiting on a stale/active child run check.
• Preserve a terminal error outcome if a later completion signal reports success for the same run, unless the run was actually restarted after the error. This prevents cleanup/finalization races from turning a failed run into a successful task after the fact.

Why this matters

The lifecycle path has a few asynchronous pieces that can finish in different orders:

1. child session/browser cleanup
2. completion announce delivery back to the requester
3. task finalization bookkeeping
4. embedded child-run settle checks
5. terminal lifecycle hooks

Before this patch, a slow or stuck browser cleanup could delay the announce/cleanup flow. Separately, if a child run had already produced frozen reply text but still appeared active, the announce flow could wait unnecessarily. And in a failure path, a later complete event could overwrite the already-recorded terminal error.

That combination makes subagent completion feel flaky from the user's side: the work is done, but the parent session may not receive the completion promptly, or the persisted final task state can become misleading.

Implementation notes

Lifecycle cleanup lease

completeSubagentRun now preclaims cleanup when triggerCleanup is true and cleanup has not already completed/been handled. That lease is passed into startSubagentAnnounceCleanupFlow as skipBeginCleanup, avoiding a second beginSubagentCleanup race while still protecting duplicate cleanup attempts.

If cleanup is not actually triggered, or announce is suppressed for steer-restart, the preclaim is released so the record does not stay permanently handled.

Browser cleanup no longer blocks announce cleanup

Previously browser cleanup was awaited before starting the subagent announce cleanup flow. This patch starts the announce cleanup flow first, retires run-mode bundle MCP runtime as before, and then launches browser cleanup as a best-effort async task:

• uses injected cleanupBrowserSessionsForLifecycleEnd when provided
• lazy-loads the browser cleanup helper otherwise
• logs warning context on failure
• does not reject or delay completion delivery

Frozen reply short-circuit

runSubagentAnnounceFlow now checks whether roundOneReply already contains non-empty frozen reply text. If it does, the flow does not wait for waitForEmbeddedPiRunEnd even if isEmbeddedPiRunActive reports true. The frozen reply is already the durable completion payload; waiting only increases the chance of a stale active-state race.

Terminal error preservation

When a run already has a terminal error outcome/reason, a later successful completion signal no longer overwrites it unless the entry's startedAt proves the run restarted after the error's endedAt. The ended hook and persisted outcome use the preserved effective reason/outcome.

Tests

Added/updated coverage for:

• announcing without waiting for browser cleanup
• skipping announce delivery when completion messages are disabled
• delete-mode cleanup when completion messages are disabled
• preserving terminal errors against later success completion
• allowing success to replace error only after a restart
• using frozen reply text without waiting on an active embedded child session

Verification run locally:

pnpm test src/agents/subagent-registry-lifecycle.test.ts src/agents/subagent-announce.test.ts

Result: 2 files passed, 29 tests passed.