What Problem This Solves

Closes two distinct silent-drop paths inside subagent completion delivery that left a parent waiting via sessions_yield hung in state=processing until restart. Both paths were verified live by independent reporters on the issue thread (sunnydongbo for RC1; jrex-jooni for RC2 on 2026.6.9), and ClawSweeper's most recent review explicitly recommends pairing both fixes:

Land or replace the wait-layer timeout snapshot fix, then pair it with a maintainer-approved no-deliverable-payload terminal notification path so yielded parents receive exactly one bounded completion/failure event.

This PR is the minimal-surface implementation of that pairing.

Linked context

• Closes part of Sub-agent run timeout does not notify parent session (completion event silently dropped) #89095 (umbrella issue for the silent-drop cluster).
• Pairs with fix(agents): skip text-direct fallback for sessions_yield completions #91370 (openperf — FM-6 yield resume race; touches subagent-announce.ts, subagent-registry-lifecycle.ts, subagent-registry.types.ts, subagent-registry-run-manager.ts — no file overlap with this PR).
• Pairs with fix(tasks): wake parent on blocked subagent delivery #95080 (Yzx — RC3 blocked-completion task-registry wake; touches src/tasks/ — no file overlap).
• RC4 (isolated-cron completion notify) is split into a separate RFC issue (linked below) because it is product-decision territory ClawSweeper has explicitly held back on related issues.

Root cause and fix

RC1 — wait-timer fallback ignored pending timeout snapshots

src/gateway/server-methods/agent-job.ts

waitForAgentJob's inner setSafeTimeout fallback only consulted getPendingAgentRunError. When a subagent was force-killed by runTimeoutSeconds, a pending timeout snapshot (not a pending error) is recorded; the wait-timer fired near-simultaneously with the gateway-side kill and called finish(null), discarding the timeout snapshot. isTerminalWaitTimeout then resolved false downstream, the announce flow never fired, and the parent (sessions_yield) hung in state=processing until restart.

The eager-check path higher up at lines 411–418 already consulted both maps. The patched timer mirrors that ordering: pendingError → createPendingErrorTimeoutSnapshot, else pendingTimeout → snapshot, else null.

RC2 — no-deliverable-payload synth notice + reordered fallback

src/agents/subagent-announce-delivery.ts

resolveTextCompletionDirectFallback only returned content for completions with status:\"ok\" and non-empty payload. Any other terminal completion left deliverTextCompletionDirect returning undefined, the four guarded return-false sites at ~lines 1614/1629/1672/1686 fired `visible_reply_missing`, announce retried 3× and abandoned, and the yielded parent never saw a terminal message.

Per jrex-jooni's 2026-06-22 verified data point (OpenClaw 2026.6.9): the trigger is not timeout-specific — context-overflow-driven mid-turn compaction reliably produces a cleanly-stopped (`stopReason=stop`) child with an empty completion payload that hits the same drop. The fix has to key off "child produced no deliverable payload" rather than the timeout case specifically.

Two changes:

1. Second-pass loop in `resolveTextCompletionDirectFallback` synthesizes a bounded terminal notice when no ok-with-content completion exists but at least one `task_completion` event is present:

   Background task finished without producing a visible reply (status: X, reason: Y).

   No raw child output is leaked; `statusLabel` is used as a hint when result has content, otherwise the reason is "no visible reply". Length is well under any per-channel budget.

2. Reordered the message-tool-only delivery branch (~line 1646) so the text-direct fallback is attempted before the `hasFailedSubagentNoOutputCompletion` early-out. Without the reorder, the early-out short-circuits to `visible_reply_missing` for the exact `(no output)` case the synth path is meant to cover.

Tests

5 new tests across the two test files ClawSweeper named as acceptance criteria:

`src/agents/subagent-announce-delivery.test.ts` (4 new, 1 modified):

• Updated existing `does not directly deliver failed subagent placeholder output` test → asserts the new behavior (synth notice is delivered) instead of the old silent drop.
• New: synth notice for clean completion with empty payload (jrex-jooni's verified case).
• New: synth notice for timeout-killed subagent with `(no output)` (sunnydongbo's verified case).
• New: synth notice does not leak raw child output (bounded length + no sensitive-fragment echo).

`src/gateway/server-methods/server-methods.test.ts` (1 new):

• Symmetric `pendingTimeout-before-wait-timer` test mirroring the existing pending-error case at line 553. Without the patch, this test resolves to `null`; with the patch, it resolves to the timeout snapshot with `endedAt` preserved.

568 tests pass across the four files ClawSweeper named (subagent-announce-delivery.test.ts: 216 across its two project configs, server-methods.test.ts: 162, subagent-registry-lifecycle.test.ts + subagent-registry.test.ts: 190), including the review-response regression tests below. Broader sweep of 7 adjacent subagent-* test files (`subagent-announce*`, `run-wait`, `subagent-run-timeout`, `subagent-delivery-state`) also passes — no regressions. `oxlint:core` and `tsgo` type-check clean.

Evidence

Vitest output for the new behavior (run on this branch)

```
✓ |agents| src/agents/subagent-announce-delivery.test.ts > deliverSubagentAnnouncement completion delivery > delivers a synthesized terminal notice when a direct-message subagent fails with no output (#89095) 3ms
✓ |agents| src/agents/subagent-announce-delivery.test.ts > deliverSubagentAnnouncement completion delivery > delivers a synthesized terminal notice for a clean completion with empty payload (#89095) 2ms
✓ |agents| src/agents/subagent-announce-delivery.test.ts > deliverSubagentAnnouncement completion delivery > delivers a synthesized terminal notice for a timeout-killed subagent with no output (#89095) 1ms
✓ |agents| src/agents/subagent-announce-delivery.test.ts > deliverSubagentAnnouncement completion delivery > synthesized terminal notice does not leak raw child output (#89095) 1ms
✓ |gateway-methods| src/gateway/server-methods/server-methods.test.ts > waitForAgentJob > resolves with the pending timeout snapshot when the wait timer expires before the grace fires (#89095) 0ms
```

Live-environment validation (this workspace, OpenClaw 2026.6.8)

Both fixes have been applied as byte-equivalent runtime patches to the installed `dist/` on this workspace's gateway for ~24 hours of real use (multi-agent workflows, sessions_yield-based ACP/Codex orchestration, Workflow tool harness runs). The local-patch sandbox suites are:

• `subagent-wait-timer-timeout-fallback` — 10/10 functional assertions PASS on 2026.6.8.
• `subagent-no-output-synth` — 14/14 functional assertions PASS on 2026.6.8.

No silent-drop incidents observed in 24h of normal use. The vitest tests in this PR are the source-level translation of those sandbox assertions.

Issue-thread live reproductions (independent verification)

• sunnydongbo (Sub-agent run timeout does not notify parent session (completion event silently dropped) #89095 comment, 2026-06-01): Live repro on `sleep 600` + `runTimeoutSeconds: 30` → confirmed the wait-timer fix alone resolves the wait/resolve-layer drop but leaves the no-output delivery drop intact (i.e. requires both fixes to be useful).
• jrex-jooni (Sub-agent run timeout does not notify parent session (completion event silently dropped) #89095 comments, 2026-06-22): Live repro on OpenClaw 2026.6.9 confirming the no-output drop fires for clean `stopReason=stop` completions, not only timeouts. Context-overflow-driven mid-turn compaction is a reliable trigger; a zero-overflow child fails identically.

Hard maintainer requirements satisfied

• ✅ Live/sandboxed repro on the underlying behavior (issue thread + workspace 24h soak).
• ✅ Tests in the four files ClawSweeper named (`subagent-announce-delivery.test.ts`, `subagent-registry-lifecycle.test.ts`, `subagent-registry.test.ts`, `server-methods.test.ts`). Registry test files are not modified because RC1/RC2 do not touch registry state; coverage was added where the behavior actually changes.
• ✅ Zero new persisted fields (keeps `merge-risk: session-state` low).
• ✅ Bounded notice template; no raw child output leaked (explicitly asserted by test 4).
• ✅ No overlap with fix(agents): skip text-direct fallback for sessions_yield completions #91370 (different source files) or fix(tasks): wake parent on blocked subagent delivery #95080 (different package: `src/tasks/`).

Out of scope / follow-up

• RC4 (isolated-cron completion notify — parent yielded for an isolated cron is never resumed even when the cron completes successfully): split into a separate RFC issue because it is a product-decision opt-in API (`cron.jobs[].notifyOnCompletion: true`-shaped surface), not a bug fix. ClawSweeper has held back this scope on Subagent announce give-up (retry-limit/expiry) does not wake parent waiting on sessions_yield → permanent deadlock #90178 for the same reason.

Review Response (2026-07-08)

All three rank-up moves addressed in commit 215f73f1d:

• [P2 → done] Classifier-gated timeout forwarding. The wait-timer fallback
  now reuses the shared terminal-outcome classifier and forwards a pending
  timeout snapshot only when terminalOutcomeFromSnapshot(...).reason === "hard_timeout". Soft queue/draining timeouts and restart-cancelled snapshots
  stay inside grace instead of being published as a false terminal cause.
  Regression tests: soft timeoutPhase: "queue" and stopReason: "restart"
  pending snapshots both resolve the waiter to null when the wait timer fires.
• [P1 → done] Closed-vocabulary synth notice. The synthesized terminal
  notice no longer reads event.statusLabel at all — it is outcome.error-
  derived and could echo provider error text (paths, secrets) to an external
  DM when the completion carried non-empty content. The reason is now strictly
  one of no visible reply / timed out / failed (details withheld) /
  incomplete, and the status is normalized to the closed event-status set.
  Regression tests: an error completion with a secret-bearing statusLabel and
  partial output, and a timeout completion with partial output, both produce
  the exact closed-vocabulary notice and never contain the label text.

Real behavior proof (redacted)

Live run on a real gateway (v2026.6.11, macOS, dist patched with this PR's
delivery-path change), performed 2026-07-08:

1. A parent session spawned a run-mode subagent whose task forces a
   no-deliverable-payload completion:

[Subagent Task] This is a delivery-path test. Do not run any tools. End your
turn with exactly this text and nothing else: (no output)

2. Child session transcript (full — two messages):

user      :: [Subagent Context] You are running as a subagent (depth 1/1). …
             [Subagent Task] … End your turn with exactly this text and nothing else: (no output)
assistant :: (no output)

3. Task ledger after completion — exactly one announce task for the child,
   terminal, delivered (ids truncated):

b5f3b063-… cli       succeeded  not_applicable  83e27d84-…  agent:main:subagent:4230f8a4-…  completed
cac895ca-… subagent  succeeded  delivered       83e27d84-…  agent:main:subagent:4230f8a4-…  (no output)

Before this fix, this exact shape ((no output) placeholder result) abandoned
delivery after the retry limit with visible_reply_missing and the waiting
parent never received a terminal message. With the fix, the completion is
announced once (delivery: delivered) and the parent wakes with the bounded
terminal notice. No sensitive values in the artifacts above; session ids are
machine-local UUIDs.

Rebase note (2026-07-09)

Rebased onto current main per review. RC1 is superseded: #89367 landed the
wait-timer pending-timeout forwarding on main, already gated through the shared
terminal-outcome classifier with fresh-wait isolation — so this branch drops its
agent-job.ts changes entirely and now carries only the delivery-layer
slice (the no-deliverable-payload synth notice with closed vocabulary, plus
the delivery-branch reorder). One commit, conflict-free against main.

Tests rerun on the exact rebased head (63c8981d7c):

pnpm vitest run src/agents/subagent-announce-delivery.test.ts        → 234 passed
pnpm vitest run src/gateway/server-methods/server-methods.test.ts   → 172 passed
pnpm vitest run src/agents/subagent-registry*.test.ts               → 344 passed
pnpm tsgo && pnpm tsgo:test                                          → clean
oxlint / oxfmt (touched files)                                       → clean

Semantics notes for the rebase review ask:

• Main's fresh-wait isolation and canonical hard-timeout classifier behavior in
  waitForAgentJob are untouched; the retained wait-timer tests (hard forwarded,
  soft queue-timeout not forwarded) lock main's fix: forward pending timeout snapshot in waitForAgentJob fallback timer #89367 behavior in place.
• Restart-cancelled completions resolve through main's direct terminal path
  (centralized precedence, fix(agents): centralize terminal run outcome precedence #88136) rather than timeout grace; that behavior is
  main's by design and this PR does not alter it.
• The live parent-wake proof above exercises the delivery slice, which is
  byte-identical before/after the rebase apart from context lines.

Sibling sequencing: with RC1 gone this PR no longer touches the wait layer at
all, so the only remaining composition surface with the yielded-completion and
blocked-completion PRs is the single synth-notice fallback in
resolveTextCompletionDirectFallback — additive, and inert whenever an
ok-with-content completion exists.