Summary

Completion-announcement retries for subagent runs can re-inject the same synthetic internal runtime context into the parent session transcript more than once.

In practice this creates duplicate [Internal task completion event] user turns in the parent session, often followed by assistant NO_REPLY responses. On large active parent transcripts this causes repeated append/rewrite/lock churn and can starve the parent session lane.

Observed symptom

In a live agent:main:main session, the same child completion payloads appeared multiple times in the parent transcript. The assistant correctly answered NO_REPLY to stale duplicates, but the duplicates still expanded the parent transcript and correlated with repeated:

• lane wait exceeded: lane=session:agent:main:main ...
• context-engine maintenance / transcript rewrite activity
• lockfile churn on the parent transcript

Why this happens

The retry model currently operates at the whole parent-session agent invocation layer rather than only at downstream delivery.

Relevant source path

1. completeSubagentRun(...) triggers cleanup announce flow:

   • src/agents/subagent-registry-lifecycle.ts
   • startSubagentAnnounceCleanupFlow(runId, entry)

2. That calls:

   • runSubagentAnnounceFlow(...)

3. Which ultimately calls:

   • deliverSubagentAnnouncement(...)
   • callGateway({ method: "agent", ... internalEvents })

4. In the parent agent execution path, internal events are turned into a new synthetic user turn via:

   • src/agents/command/attempt-execution.ts
   • prependInternalEventContext(body, events)

export function prependInternalEventContext(body, events) {
  if (hasInternalRuntimeContext(body)) {
    return body;
  }
  const renderedEvents = formatAgentInternalEventsForPrompt(events);
  if (!renderedEvents) {
    return body;
  }
  return [renderedEvents, body].filter(Boolean).join("\n\n");
}

So every retry of the announce flow creates another parent-session input turn containing the same completion event.

The retry window

cleanupHandled is intentionally cleared on retry/defer paths, and resumeSubagentRun(runId) can re-enter startSubagentAnnounceCleanupFlow(...) as long as cleanupCompletedAt has not been set.

Relevant files / lines:

• src/agents/subagent-registry-lifecycle.ts
  • beginSubagentCleanup(...)
  • finalizeSubagentCleanup(...)
  • retryDeferredCompletedAnnounces(...)
  • startSubagentAnnounceCleanupFlow(...)
• src/agents/subagent-registry.ts
  • resumeSubagentRun(runId)

Notably, retries are intentionally supported, but there is no persistent guard ensuring that the same (childSessionKey, childRunId) completion context is injected into the parent session transcript only once.

Why current idempotency is not sufficient

The announce path does derive stable announce ids and idempotency keys:

• buildAnnounceIdFromChildRun(...)
• buildAnnounceIdempotencyKey(...)

But those are applied to the announce/delivery request. The retry still re-runs the parent agent invocation path that prepends internal runtime context into the parent input body. In other words, retries are happening at too high a layer.

Expected behavior

For a given child completion (childSessionKey, childRunId):

• the parent session should ingest the internal completion context at most once
• retries should only affect downstream delivery / unresolved follow-up behavior
• retrying should not create duplicate synthetic user turns in the parent transcript

Actual behavior

The same completion can be re-announced into the parent session transcript more than once before cleanupCompletedAt is finalized.

Impact

• duplicate internal completion context messages in parent transcript
• duplicate assistant work on stale completion events
• repeated NO_REPLY responses
• much larger active parent transcript than necessary
• repeated transcript rewrite / lock churn
• lane starvation on the parent session

Suggested fix direction

Split these concerns:

1. Completion ingestion into parent session — record once per (childSessionKey, childRunId)
2. Delivery / follow-up retry — may retry, but must not re-inject the same internal context into the parent transcript

A per-run persisted marker such as one of these would likely be enough:

• completionContextInjectedAt
• deliveredAnnounceId
• announcedChildRunIds[]

and gate runSubagentAnnounceFlow(...) / the agent reinvocation path accordingly.

Additional note

The existing subagent-registry.announce-loop-guard tests cover eventual give-up / retry bookkeeping, but they do not appear to assert the stronger invariant that the same child completion cannot produce duplicate internal-context parent turns.