Summary

• Fixes message_tool_only: withheld finals stay in the agent's context as normal turns, desynchronizing agent memory from what the user saw #100368 by recording when a substantive message_tool_only final entered the transcript but was not delivered to the source channel.
• Gives direct runs and queued follow-up runs the same durable behavior: append one hidden undelivered-final marker before enqueueing the existing one-shot recovery retry.
• Keeps retry runs from appending a duplicate marker and preserves the marker through transcript replay/rotation so later model context matches what the user actually saw.
• Adds a standard top-level messageId to the repository QA channel's successful send receipt. The real runtime proof exposed that its previous nested-only receipt made a successful recovery send look incomplete.

What Problem This Solves

A message_tool_only assistant final can be stored in session history even though the user never received it. Without a durable delivery marker, later model turns treat that private final as user-visible conversation state, desynchronizing agent memory from what the user actually saw.

The same failure also behaved differently across runners: direct runs recorded the undelivered state, while queued follow-up runs could enter recovery without doing so. This patch makes that session-state invariant runner-independent.

Root Cause

• Root cause: Direct and queued follow-up runners applied different durable transcript behavior after the same message_tool_only stranded final: direct runs appended the undelivered marker, while queued follow-ups could enqueue recovery without recording that the final remained private.
• Why this is root-cause fix: The patch restores the invariant at the shared runner/session boundary where normalized final text and committed source-delivery evidence become durable session state, before either runner starts recovery. It does not mask the later transcript symptom or infer transport success downstream.
• Architecture / source-of-truth check: The source of truth is the completed run's normalized assistant final plus committed granular source-route delivery evidence. persistSessionTranscriptTurn is the canonical durable write, and the existing one-shot stranded-reply follow-up remains the canonical retry. Current origin/main still needs this patch, and the existing-PR diagnosis found no canonical replacement PR to defer to.

Under messages.visibleReplies: "message_tool", the runtime normalizes source delivery to sourceReplyDeliveryMode: "message_tool_only". An assistant final can therefore be durably present in the session transcript while remaining private because the model did not call message(action=send).

The existing direct-run recovery path appended a hidden undelivered-final marker, but the queued follow-up recovery path did not. Both paths could enqueue the same one-shot stranded-reply recovery, yet the same user-visible failure produced different durable model context depending on which runner executed it. A restart or later model turn could consequently treat a queued private final as text the user had seen.

The source of truth is the completed run's normalized assistant final plus committed source-route delivery evidence. The marker is the durable projection of the negative delivery fact; it does not infer provider state or replace transport receipts.

The outside-Vitest proof also found an adjacent QA boundary defect. qa-channel successfully wrote the recovery message to its HTTP bus but returned only { message: { id } }. The shared delivery classifier intentionally requires a standard committed receipt such as top-level messageId, so the successful send was classified as incomplete and an incorrect second failure diagnostic was emitted. The narrow repair is at the QA action boundary: retain the full message and also return messageId: message.id.

Canonical reachability

messages.visibleReplies: "message_tool"
  -> config schema/type/ingestion/normalization
  -> sourceReplyDeliveryMode: "message_tool_only"
  -> real gateway session lane and follow-up queue
  -> runEmbeddedAgent() final + committed delivery evidence
  -> direct runner or followup-runner.ts delivery decision
  -> guarded persistSessionTranscriptTurn(..., updateMode: "file-only")
  -> hidden openclaw.message-tool-only-undelivered-final record
  -> existing queue-front stranded-reply recovery
  -> message(action=send)
  -> channel action receipt
  -> SessionManager/transcript replay consumes the durable marker

The append is guarded by the active session id and lifecycle revision when a store path is available. Marker persistence is awaited before recovery enqueue. A persistence failure remains contained so it cannot suppress the already-established recovery path.

What changed

• Extracted the direct runner's guarded marker append into a shared helper.
• Called the same helper from the queued follow-up runner before evaluating/enqueueing stranded-final recovery.
• Reused the run's successful source-delivery result for both marker suppression and stranded-final detection.
• Preserved the existing retry guard so strandedReplyRetry runs do not append the marker again.
• Added a regression assertion that reads the real temporary session JSONL from the enqueue callback and proves the marker already exists.
• Added top-level messageId to successful qa-channel send results and covered it at the channel action boundary.

Real behavior proof

• Behavior or issue addressed: A queued substantive final that was saved but not delivered under message_tool_only must append one hidden marker before recovery so later model context does not treat private text as user-visible history.
• Canonical reachability path: User/config/input messages.visibleReplies: "message_tool" → schema/type/ingestion/normalization → runtime object sourceReplyDeliveryMode: "message_tool_only" on the embedded/follow-up run → request/effect: guarded transcript marker append, queue-front recovery request, message-tool send, and committed channel receipt.
• Boundary crossed: Actual OpenClaw CLI command, gateway socket, same-session lane, follow-up queue, followup-runner.ts, session JSONL, recovery message tool, qa-channel plugin, and loopback HTTP bus.
• Shared helper / provider constraint check: Both runners reuse persistMessageToolOnlyUndeliveredFinalNotice, which delegates to persistSessionTranscriptTurn; recovery and source-delivery classifiers remain shared. No provider-owned numeric/range contract is changed, and receipt classification is not widened globally.
• Real environment tested: Linux OpenClaw worktree with isolated home/state/config/workspace/session directories, real CLI/gateway runtime, repository loopback QA channel, and repository loopback mock provider. Authentication used only the local placeholder qa-mock-not-a-real-key.
• Exact steps or command run after this patch: Start private-QA mock provider, QA HTTP bus, and gateway; start a held CLI run on agent:qa:main; inject a normal QA-channel direct message into the same session; wait for queue/recovery/provider completion and a stable bus cursor; inspect gateway logs, session JSONL, provider requests, bus state, and final session state.
• Evidence after fix: The queue waited 58.238 seconds behind the active run; marker count was 1; the marker preceded recovery enqueue by 194 ms; the recovery called message(action=send); the stable bus had one outbound; failure diagnostic count was 0; session status was done with abortedLastRun: false.
• Observed result after fix: The queued private final was followed by the hidden durable marker before recovery, the recovery send produced a standard committed receipt, no duplicate marker or fallback diagnostic was emitted, and later transcript replay retained the delivery fact.
• What was not tested: The proof did not leave the isolated loopback QA environment. That is the intended boundary because this PR changes session-state handling and the repository QA action receipt; network transport implementations and accounts are not modified.
• Why it matters / User impact: Without the marker, later agent turns can reason from a reply the user never saw. Restoring runner parity keeps agent memory synchronized with the user's actual conversation and survives process exits between the original run and recovery drain.
• Fix classification: Root-cause fix at the runner/session-state source-of-truth boundary, plus a narrow repository-QA receipt contract repair discovered by the runtime proof.
• Maintainer-ready confidence: High for the local OpenClaw runtime/session/channel-plugin boundary: code order, TDD regressions, replay coverage, fresh suites, and outside-Vitest runtime evidence agree. Maintainer acceptance remains explicit for the persistent model-consumed marker representation.
• Patch quality notes: The 11-file/734-line cumulative PR includes the original marker, replay, direct-run coverage, and this repair; the new repair commit itself is limited to six files. Retry-related scanner hits are assertions for the existing one-shot recovery, not retry-policy changes. Test return true preserves the queue mock's success contract; production return false rejects missing source-route evidence. Broad catches intentionally keep established recovery available if marker persistence fails. Replay preserves marker adjacency across rotation rather than rewriting user content. The QA receipt adds an already-supported standard field at a private test-channel boundary. No casts, skipped tests, dependency changes, lockfile churn, or unrelated formatting are included.

Verdict: PASS for the local real OpenClaw CLI/gateway/session/channel-plugin boundary.

The proof launched the actual OpenClaw CLI and gateway with isolated home, state, config, workspace, and session directories. It used the repository's loopback qa-channel HTTP bus and loopback mock OpenAI server. The model output was deterministic, but the CLI command, gateway socket, session lane, queue, followup-runner.ts, transcript persistence, message tool dispatch, channel plugin, and HTTP bus were real runtime paths.

OpenClaw 2026.6.11 (version string HEAD 974adc9, with the pending PR diff built)
gateway:       http://127.0.0.1:18829
qa-channel:    http://127.0.0.1:43163
mock provider: http://127.0.0.1:44083
session key:   agent:qa:main
queue mode:    followup
visibleReplies: message_tool

No network channel credentials were configured. The only auth value was the local placeholder qa-mock-not-a-real-key.

Driven scenario

1. A real CLI agent run started on agent:qa:main; the local provider held it for 60 seconds.
2. While that run was active, a normal direct inbound message was posted to the real qa-channel HTTP bus.
3. The gateway routed the second message to the same session lane under messages.queue.mode=followup.
4. The queued run produced a substantive final without calling the message tool.
5. The follow-up runner persisted the hidden marker, enqueued recovery, and the recovery run called message(action=send).
6. Evidence was frozen only after provider work completed and the QA bus cursor remained stable.

Same-session queue evidence

11:25:52.419 lane enqueue: lane=session:agent:qa:main queueSize=2
11:26:50.656 lane wait exceeded: waitedMs=58238 activeAhead=1
11:26:50.659 lane dequeue: waitMs=58238 queueSize=0

The second normal user message waited 58.238 seconds behind the active CLI run, proving it entered the same real session queue before followup-runner.ts handled it.

Durable transcript evidence

line 8   user       queued qa-channel inbound
line 9   assistant  substantive private final, length 240
line 11  custom     openclaw.message-tool-only-undelivered-final
line 12  assistant  message(action=send, message=QA-STRANDED-85714)
line 13  assistant  delivery mirror
line 15  toolResult successful qa-channel outbound receipt
line 16  assistant  empty post-tool completion

The redacted marker was:

{
  "role": "custom",
  "customType": "openclaw.message-tool-only-undelivered-final",
  "display": false,
  "details": {
    "sourceReplyDeliveryMode": "message_tool_only",
    "delivered": false,
    "finalTextLength": 240
  }
}

marker count:             1
failure diagnostic count: 0

Marker-before-recovery ordering

11:26:51.844 transcript marker appended
11:26:52.038 recovery lane enqueue
11:26:52.820 recovery message tool call appended

The durable marker existed 194 ms before recovery enqueue and 976 ms before the recovery tool call.

Recovery receipt and stable channel state

{
  "messageId": "5318c425-c8f1-4cd4-872b-3cc396551bf2",
  "message": {
    "direction": "outbound",
    "conversation": {
      "id": "qa-pr-101618-queued-fixed",
      "kind": "direct"
    },
    "text": "QA-STRANDED-85714"
  }
}

After all provider requests completed and the bus cursor stabilized:

{
  "outboundCount": 1,
  "outboundTexts": ["QA-STRANDED-85714"]
}

The final session state was:

{
  "key": "agent:qa:main",
  "status": "done",
  "abortedLastRun": false
}

The provider observed four gateway requests: the slow CLI run, the queued substantive-final run, the recovery tool-planning run, and the post-tool completion. Only the recovery request planned the message tool.

Adjacent runtime probe

The first full runtime attempt produced one successful QA bus delivery followed by an incorrect failure diagnostic and left the session killed with abortedLastRun: true. Tracing the tool result showed that qa-channel returned only nested message.id, so committed source-delivery evidence never became true.

A TDD regression first observed:

expected undefined to be '<qa message id>'

After returning messageId: message.id, the focused test passed, all 14 qa-channel tests passed, and the repeated real runtime produced exactly one outbound, no failure diagnostic, and a completed session.

Proof boundary

This is a redacted artifact from a local real OpenClaw CLI/gateway/session/channel-plugin run outside Vitest. The run intentionally remained on isolated loopback QA infrastructure; no network transport implementation or account was involved.

Evidence

TDD and fresh verification

The queued-run regression was written first and failed because the JSONL captured at enqueue did not contain openclaw.message-tool-only-undelivered-final. After the shared helper was wired into the follow-up runner, the same assertion passed.

The QA receipt regression was also observed RED before the one-line production repair, then GREEN after the top-level receipt was added.

Commands run against the final pending diff:

node scripts/run-vitest.mjs \
  --config test/vitest/vitest.auto-reply-reply.config.ts \
  reply/agent-runner.misc.runreplyagent.test.ts \
  reply/followup-runner.test.ts \
  reply/session-transcript-replay.test.ts \
  reply/stranded-reply-recovery.test.ts \
  reply/agent-runner-payloads.test.ts

Test Files  5 passed (5)
Tests       293 passed (293)

node scripts/run-vitest.mjs \
  --config test/vitest/vitest.e2e.config.ts \
  src/auto-reply/reply/agent-runner.runreplyagent.e2e.test.ts

Test Files  1 passed (1)
Tests       92 passed (92)

qa-channel focused receipt regression: 1 passed
qa-channel complete test file:          14 passed
git diff --check:                       passed with no output

The final auto-reply and E2E logs contain no module-resolution errors. Each run prints the repository's existing Vitest envFile deprecation notice before the passing summary; this patch does not change the test configuration.

Regression Test Plan

• Target test file: src/auto-reply/reply/followup-runner.test.ts, the specified five-file auto-reply suite, src/auto-reply/reply/agent-runner.runreplyagent.e2e.test.ts, and extensions/qa-channel/src/channel.test.ts.
• Scenario locked in: A queued message_tool_only substantive final with no successful source delivery writes the hidden JSONL marker before enqueueing one protected recovery; retry runs do not duplicate it; a successful QA send exposes top-level messageId and completes without a fallback diagnostic.
• Why this is the smallest reliable guardrail: The focused follow-up test observes the real temporary JSONL at the enqueue callback, the existing E2E/replay suites protect durable ordering and model consumption, and the QA action test checks the receipt at the exact plugin boundary. The outside-Vitest run separately proves those seams operate together in the actual CLI/gateway/session flow.

Review findings addressed

• RF-001: Added the redacted outside-Vitest OpenClaw runtime/session artifact above.
• RF-002: Drove the actual CLI, gateway socket, same-session lane, follow-up queue, transcript JSONL, message tool, repository channel plugin, and loopback HTTP bus. This matches the changed runtime/session boundary.
• RF-003: Direct and queued follow-up runners now call the same guarded persistence helper and produce the same durable model context for equivalent undelivered finals.
• RF-004: The marker is intentionally persistent, model-consumed session state rather than an internal diagnostic. Replay/rotation preserves it because later runs must know the preceding assistant final was private. This compatibility/session-state representation remains an explicit maintainer acceptance decision.
• RF-005: The narrow shared-runner repair is complete. Contributor-supplied real-runtime proof is supplied separately above; durable-marker product acceptance remains a separate maintainer judgment rather than being hidden inside the code fix.
• RF-006: followup-runner.ts now awaits marker persistence before queue-front recovery enqueue, with both RED-to-GREEN JSONL ordering coverage and real runtime ordering evidence.
• RF-007: Fresh specified auto-reply suite passed: 5 files, 293 tests.
• RF-008: Fresh specified E2E file passed: 1 file, 92 tests.
• RF-009: git diff --check passed with no output.

Merge risk

• Risk labels considered: compatibility, message-delivery, security-boundary, and session-state.

• Risk explanation: The marker is persistent model-consumed state preserved across rotation; the runtime decision controls whether private text is treated as user-visible; and the QA receipt affects committed delivery classification. Incorrect scope, ordering, or ownership could create false conversation history or duplicate recovery.

• Why acceptable: The marker is restricted to nonempty, non-silent, allowed message_tool_only finals without successful source delivery; writes are session/lifecycle guarded and occur before enqueue; retry runs cannot duplicate it; the QA change adds a standard receipt already recognized by the shared classifier; the real runtime ended with exactly one marker, one outbound, no failure diagnostic, and a completed session.

• What did NOT change: Public config schema/defaults, model service contracts, network channel implementations, message-tool API, retry count/prompt/priority, room-event handling, send-policy denial, intentional silence, dependencies, and lockfiles are unchanged. The related-main scan confirmed this existing PR remains necessary.

• Compatibility/session-state: The hidden custom record survives replay/rotation and is consumed by later model context. That is deliberate: removing it would restore the user/model history mismatch. The record is limited to nonempty, non-silent, allowed message_tool_only finals without successful source delivery.

• Ordering: Persistence is awaited before recovery enqueue, so an exit between the original run and queue drain cannot lose the negative delivery fact.

• Duplication: Recovery retries are marked and do not append another undelivered-final marker; the real transcript contained exactly one marker.

• Stale ownership: Store-backed writes use expected session id and lifecycle revision guards.

• Delivery: Successful committed source delivery suppresses the marker and recovery. The QA-only receipt change exposes the standard evidence already recognized by the shared classifier rather than weakening receipt classification globally.

• Failure containment: A marker append failure is logged but does not block the existing one-shot recovery path.

Out of scope

• No public config schema/default, model service contract, network channel implementation, retry count, retry priority, recovery prompt, room-event behavior, send-policy denial, or intentional-silence behavior changes.
• No dependency or lockfile changes.
• Runtime evidence is scoped to the isolated loopback QA boundary exercised above.