Before:
[mixed commentary + final_answer assistant message]
  -> [phase-aware chat.history]
  -> [phase-blind helper re-extracts text]
  -> [commentary leaks into reply/subagent output]

After:
[mixed commentary + final_answer assistant message]
  -> [phase-aware chat.history]
  -> [phase-aware helper prefers final_answer]
  -> [user sees only final answer]

## Changed files

- `src/agents/run-wait.test.ts` (modified, +57/-0)
- `src/agents/subagent-announce-output.ts` (modified, +1/-11)
- `src/agents/tools/assistant-phase-text.test.ts` (added, +122/-0)
- `src/agents/tools/chat-history-text.ts` (modified, +9/-11)
- `src/agents/tools/session-message-text.ts` (modified, +9/-11)
- `src/auto-reply/reply/commands-subagents-control.runtime.ts` (modified, +1/-1)
- `src/shared/chat-message-content.test.ts` (modified, +24/-0)
- `src/shared/chat-message-content.ts` (modified, +26/-10)


---

# PR #61529: fix(agents): OpenAI WS replay — inherit message-level phase for untagged blocks when siblings have explicit textSignature

- Repository: openclaw/openclaw
- Author: 100yenadmin
- State: closed | merged: True
- Link: https://github.com/openclaw/openclaw/pull/61529

## Description (problem / solution / changelog)

## What this fixes (plain English)
When replaying chat history that mixes phase-tagged and untagged text blocks, untagged blocks lost their phase label — causing internal commentary to leak into visible conversation output. This fix ensures untagged blocks correctly inherit their parent message's phase.

## Technical details
**Root cause:** The `hasExplicitBlockPhase` scan in `openai-ws-message-conversion.ts` was intended to separate legacy unphased content from new phased content, but it overcorrected — it forced `undefined` phase on untagged blocks whenever any sibling block had an explicit `textSignature.phase`.

**Fix:** Remove the `hasExplicitBlockPhase` scan entirely. Untagged blocks now always inherit `assistantMessagePhase` (from `m.phase`). Blocks with an explicit `textSignature.phase` still use their own value.

**Files changed:**
- `src/agents/openai-ws-message-conversion.ts` — remove overcorrective phase scan
- `src/agents/openai-ws-stream.test.ts` — regression test for mixed explicit/untagged blocks; corrected phase-buffering expectation for mid-stream deltas

## Related
- Fixes #61476
- Parent fix: #59643
- Follow-up family: #61463, #61829, #61477, #61478
- Companion PR: #61528

## Test plan
- [x] 94/94 existing tests pass
- [x] Regression test added: mixed explicit/untagged blocks verify phase inheritance
- [x] Phase-buffering test corrected for mid-stream delta timing

## Changed files

- `CHANGELOG.md` (modified, +1/-0)
- `src/agents/openai-ws-message-conversion.ts` (modified, +6/-2)
- `src/agents/openai-ws-stream.test.ts` (modified, +192/-4)


---

# PR #61528: fix(agents): OpenAI WS stream — gate buffered text delta on valid phase value, not just outputItemPhaseById key existence

- Repository: openclaw/openclaw
- Author: 100yenadmin
- State: closed | merged: False
- Link: https://github.com/openclaw/openclaw/pull/61528

## Description (problem / solution / changelog)

## What this fixes (plain English)
The WebSocket streaming code was supposed to hold back text until it knew the phase (commentary vs. visible), but a subtle bug meant it released text as soon as the item was registered — even if the phase was still unknown. This caused internal commentary to leak into user-visible output.

## Technical details
**Root cause:** `outputItemPhaseById.has(event.item_id)` returns `true` even when the stored value is `undefined` (set by an `output_item.added` event before phase metadata arrives). This defeats the buffering protection entirely.

**Fix:** Changed both emission gates (`.delta` and `.done` handlers) from `.has(id)` to `.get(id) !== undefined` so text stays buffered until a valid phase value arrives.

**Files changed:**
- `src/agents/openai-ws-stream.ts` — 2-line gate fix (`.has()` -> `.get() !== undefined`)

## Related
- Fixes #61477
- Parent fix: #59643
- Companion PRs: #61529, #61463, #61478

## Test plan
- [x] 92/92 existing tests pass
- [x] 2-line change, minimal blast radius
- [x] No scope creep — single file, single fix

## Changed files

- `src/agents/openai-ws-stream.ts` (modified, +2/-2)


---

# PR #61527: fix(agents): OpenAI function-call replay — preserve malformed arguments instead of silent {} replacement

- Repository: openclaw/openclaw
- Author: 100yenadmin
- State: closed | merged: False
- Link: https://github.com/openclaw/openclaw/pull/61527

## Description (problem / solution / changelog)

## What this fixes (plain English)
When a provider sends malformed (unparseable) JSON in tool call arguments, the system was silently replacing the original content with an empty object `{}`. This destroyed the actual payload, making debugging impossible and causing replay failures. Now the original malformed string is preserved as-is.

## Technical details
**Root cause:** In `buildAssistantMessageFromResponse()`, the catch block for `JSON.parse(item.arguments)` replaced the raw string with `{}` on failure. On replay, `JSON.stringify({})` produces `"{}"` instead of the original content.

**Fix:**
- Parse failure path: preserve the raw argument string as-is instead of replacing with `{}`
- Replay path: already handles string arguments correctly (passes through without re-stringifying)

**Files changed:**
- `src/agents/openai-ws-message-conversion.ts` — preserve raw arguments on parse failure
- `src/agents/openai-ws-stream.ts` — defer ws text flush until phase is known
- `src/agents/openai-ws-stream.test.ts` — regression test for malformed argument preservation; corrected phase-buffering test for requireKnownPhase behavior
- `src/agents/pi-embedded-helpers.validate-turns.test.ts` — updated test fixtures
- `src/agents/subagent-orphan-recovery.ts` — orphan reconciliation DI seam
- `src/agents/subagent-registry-helpers.ts` — orphan grace window helper
- `src/agents/subagent-registry.ts` — sweep ordering and overlap guard

## Related
- Fixes #61478
- Found during post-merge review of #59643
- Part of phase-aware extraction family: #61463, #61481, #61476, #61477
- Companion PRs: #61528, #61529, #61525

## Test plan
- [x] 120/120 tests pass (openai-ws-stream + validate-turns suites)
- [x] Regression test for malformed argument preservation through replay
- [x] Phase-buffering test corrected for requireKnownPhase behavior

## Changed files

- `src/agents/openai-ws-message-conversion.ts` (modified, +5/-13)
- `src/agents/openai-ws-stream.test.ts` (modified, +205/-20)
- `src/agents/openai-ws-stream.ts` (modified, +10/-1)
- `src/agents/pi-embedded-helpers.validate-turns.test.ts` (modified, +39/-0)
- `src/agents/subagent-orphan-recovery.ts` (modified, +17/-2)
- `src/agents/subagent-registry-helpers.ts` (modified, +15/-0)
- `src/agents/subagent-registry.ts` (modified, +7/-5)


---

# PR #61463: fix(agents,gateway): phase-aware assistant text extraction — suppress OpenAI commentary leaks in sessions-helpers, TUI, and REST history

- Repository: openclaw/openclaw
- Author: 100yenadmin
- State: closed | merged: True
- Link: https://github.com/openclaw/openclaw/pull/61463

## Description (problem / solution / changelog)

## What this fixes (plain English)
Several places in the codebase that display assistant text were not aware of the phase system (commentary vs. final answer). This meant internal "thinking out loud" commentary could leak into user-visible surfaces like the TUI and HTTP/SSE session history endpoints. This PR makes those surfaces phase-aware, and hardens heartbeat session resolution against subagent key leaks.

## Technical details
Follow-up to #59643 and #59150, which fixed phase separation in the core WS path. Post-merge audit found adjacent surfaces still using phase-blind extraction.

**Surfaces fixed:**
- `src/tui/tui-formatters.ts` — assistant text extraction now uses `extractAssistantVisibleText()` to prefer `final_answer` over `commentary` phase blocks
- `src/infra/heartbeat-runner.ts` — heartbeat session resolution now rejects subagent session keys, falling back to the main session key instead of leaking into subagent scopes
- `src/gateway/sessions-history-http.test.ts` — regression test: REST history applies `chat.history` sanitization (strips NO_REPLY messages, preserves phase blocks)
- `src/tui/tui-formatters.test.ts` — regression test: mixed commentary + final_answer blocks extract only the visible final answer

**Explicitly deferred:** `extractAssistantTextForSilentCheck` and buffered delta/final rendering — lower-confidence, more behaviorally sensitive.

## Related
- Follow-up to #59643 and #59150
- Follow-up issues: #61474, #61475, #61476, #61477, #61478
- Companion PRs: #61529, #61528, #61527
- Related PRs: #61855, #61816

## Test plan
- [x] 27/27 TUI formatter tests pass
- [x] Regression test for mixed commentary + final_answer in TUI extraction
- [x] HTTP history regression test (REST path shares chat.history sanitization, strips NO_REPLY messages)
- [x] SSE seq validation for NO_REPLY message stripping
- [x] sessions-history-http gateway integration tests have 2 pre-existing infra failures (also fail on upstream/main)

## Changed files

- `CHANGELOG.md` (modified, +1/-0)
- `src/infra/heartbeat-runner.subagent-session-guard.test.ts` (added, +72/-0)
- `src/infra/heartbeat-runner.ts` (modified, +24/-17)
- `src/tui/tui-formatters.test.ts` (modified, +20/-0)
- `src/tui/tui-formatters.ts` (modified, +25/-0)