Best possible solution:

Use #77415 as the canonical branch and land it only after the remaining review and real behavior proof are resolved there.

Do we have a high-confidence way to reproduce the issue?

Yes, at source level. Current main accepts only start/end/error in the affected consumers and maps aborted end events to timeout, while this PR's added startup-failed path can still be followed by a later end event.

Is this the best way to solve the issue?

No for this branch. The additive lifecycle direction is right, but the newer successor PR is the narrower review target because it includes this change plus fixes for the late end and gateway wait gaps.

Security review:

Security review cleared: No concrete security or supply-chain issue found; the diff changes in-repo lifecycle logic, tests, docs, and changelog only.

What I checked:

• Current main still lacks the requested lifecycle phases: A source search on current main finds no first-progress implementation and only an unrelated provider-local-service startup-failed stop reason, so this PR is not already implemented on main. (src/agents/provider-local-service.ts:127, 983064f5f819)
• Current embedded lifecycle remains start/end/error only: Current main emits terminal error/end lifecycle events from handleAgentEnd and has no startup-failed branch in the embedded lifecycle handler. (src/agents/pi-embedded-subscribe.handlers.lifecycle.ts:119, 983064f5f819)
• Current subagent and wait consumers still ignore the new phases: Current main's subagent registry returns unless the lifecycle phase is end or error, and agent-job snapshots only accept end/error, matching the remaining bug surface. (src/agents/subagent-registry.ts:923, 983064f5f819)
• This PR is open but conflicted and already had blocking review feedback: Live PR metadata shows this branch remains open, mergeable=CONFLICTING, has only the original lifecycle commit, and has a prior Codex needs-changes comment for lifecycle ordering and server-chat/session finalization. (2969df18ac72)
• Newer PR supersedes this branch: Live PR metadata for fix(subagents): report startup and completion lifecycle edges #77415 shows the same author, an open successor branch, the same file surface, commit headline 'fix subagent startup lifecycle signals', plus follow-up commits including 'fix(gateway): preserve startup-failed agent waits'. (83aefea57419)

Likely related people:

• Peter Steinberger: Split the subagent registry lifecycle module, which is adjacent to the completion and terminal-state behavior touched by this PR. (role: recent refactor contributor; confidence: medium; commits: f862685ed8e4; files: src/agents/subagent-registry-lifecycle.ts, src/agents/subagent-registry.ts)
• Dario Zhang: Authored prior merged work changing subagent timeout reporting across the registry and gateway agent-job paths involved in this lifecycle ambiguity. (role: timeout behavior contributor; confidence: high; commits: e85bbe01f266; files: src/agents/subagent-registry.ts, src/gateway/server-methods/agent-job.ts)
• Bob: Authored gateway agent.wait and startup hardening work on the same server-methods agent-job surface. (role: adjacent gateway lifecycle contributor; confidence: medium; commits: 61f7cea48bd7; files: src/gateway/server-methods/agent-job.ts, src/gateway/server-methods/server-methods.test.ts, src/gateway/server-methods/agent.ts)
• Shakker: Current-main blame for the central lifecycle, registry, and agent-job lines in this checkout points to a recent commit touching these files. (role: recent area contributor; confidence: low; commits: af6f75f78cf6; files: src/agents/pi-embedded-subscribe.handlers.lifecycle.ts, src/agents/subagent-registry.ts, src/gateway/server-methods/agent-job.ts)

Codex review notes: model gpt-5.5, reasoning high; reviewed against 983064f5f819.