Summary

• Problem: overflow-recovery transcript rewrites replay the active suffix, so already-polluted branches can keep re-appending the same logical transcript payloads.
• Why it matters: cloned user prompts, compaction records, and bootstrap context records amplify session JSONL growth and can worsen later context overflows.
• What changed: transcript rewrite replay now suppresses exact replay identities for message, compaction, custom, and custom-message entries while preserving the id remap chain for later suffix entries.
• What did NOT change (scope boundary): this does not close the whole Umbrella: duplicate transcript, replay, and context assembly across channels #69208 umbrella or add channel-local ingress dedupe; it targets the concrete Track A overflow/rewrite path from Overflow recovery duplicates role=user messages in session JSONL, amplifying transcript growth #66443.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes Overflow recovery duplicates role=user messages in session JSONL, amplifying transcript growth #66443
• Related Umbrella: duplicate transcript, replay, and context assembly across channels #69208
• This PR fixes a bug or regression

Real behavior proof (required for external PRs)

External contributors must show after-fix evidence from a real OpenClaw setup. Unit tests, mocks, lint, typechecks, snapshots, and CI are supplemental only. Screenshots are encouraged even for CLI, console, text, or log changes; terminal screenshots and copied live output count. Be mindful of private information like IP addresses, API keys, phone numbers, non-public endpoints, or other private details when providing evidence.

• Behavior or issue addressed: transcript rewrite replay no longer persists exact duplicate user payloads or repeated bootstrap context entries when rewriting a polluted active branch.
• Real environment tested: local OpenClaw checkout on Linux, Node 24.15.0 via repo pnpm exec tsx, branch based on upstream/main at a1ac559ed7.
• Exact steps or command run after this patch: ran a local OpenClaw runtime script that creates a real persisted SessionManager JSONL file, appends three identical user payloads plus two duplicate openclaw:bootstrap-context:full custom entries, calls the production rewriteTranscriptEntriesInSessionFile(...) function, reopens the session file, and prints the active branch counts.
• Evidence after fix (copied terminal output from the local OpenClaw runtime script):

before branch roles=user,user,user,assistant
before user_count=3
before bootstrap_count=2
[agent/embedded] [transcript-rewrite] rewrote 1 entry bytesFreed=0 sessionKey=agent:main:main:heartbeat
rewrite changed=true rewrittenEntries=1
after branch roles=user,assistant
after user_count=1
after bootstrap_count=1
raw_jsonl_lines=10

• Observed result after fix: after reopening the persisted session file, the active branch contains only one user payload and one bootstrap context entry instead of the three user payloads and two bootstrap entries that existed before rewrite.
• What was not tested: a full end-to-end forced provider context-overflow run was not triggered locally; the runtime script exercises the same transcript rewrite/file-state path called by tool-result truncation recovery.
• Before evidence (optional but encouraged): the same script prints before user_count=3 and before bootstrap_count=2 immediately before invoking the rewrite path.

Root Cause (if applicable)

For bug fixes or regressions, explain why this happened, not just what changed. Otherwise write N/A. If the cause is unclear, write Unknown.

• Root cause: rewriteTranscriptEntriesInSessionManager and rewriteTranscriptEntriesInState branched from the first replaced message and then appended every suffix entry without an idempotency invariant.
• Missing detection / guardrail: there was no regression coverage for rewriting a branch already polluted with exact replayed user messages, repeated bootstrap custom entries, or cloned compactions.
• Contributing context (if known): overflow recovery uses this rewrite path after building tool-result replacement plans, so a polluted suffix could be faithfully replayed into the new active branch.

Regression Test Plan (if applicable)

For bug fixes or regressions, name the smallest reliable test coverage that should catch this. Otherwise write N/A.

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/agents/pi-embedded-runner/transcript-rewrite.test.ts
• Scenario the test should lock in: exact replayed user payloads collapse during in-memory and persisted file rewrites, repeated same text with distinct message timestamps remains intact, and replayed bootstrap/compaction clones collapse.
• Why this is the smallest reliable guardrail: it exercises the shared transcript rewrite seam directly, including the file-state path used for persisted sessions, without requiring a slow provider overflow setup.
• Existing test that already covers this (if any): existing tests covered suffix replay and remapping, but not polluted suffix dedupe.
• If no new test is added, why not: N/A

User-visible / Behavior Changes

Overflow-recovery transcript rewrites should stop amplifying exact replayed transcript records in session JSONL. Normal repeated user text with distinct message timestamps remains preserved.

Diagram (if applicable)

Before:
[polluted branch] -> [rewrite first replacement] -> [append every suffix entry] -> [duplicates stay active]

After:
[polluted branch] -> [rewrite first replacement] -> [append first replay identity only] -> [active branch is compacted]

Security Impact (required)

• New permissions/capabilities? (Yes/No) No
• Secrets/tokens handling changed? (Yes/No) No
• New/changed network calls? (Yes/No) No
• Command/tool execution surface changed? (Yes/No) No
• Data access scope changed? (Yes/No) No
• If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

• OS: Linux
• Runtime/container: Node 22/24 through repo pnpm wrappers
• Model/provider: N/A for targeted transcript rewrite regression
• Integration/channel (if any): Agent transcript persistence / overflow recovery seam
• Relevant config (redacted): default local test config

Steps

1. Build an active transcript branch with three exact copies of the same user AgentMessage payload.
2. Rewrite the first message through rewriteTranscriptEntriesInSessionManager and rewriteTranscriptEntriesInSessionFile.
3. Re-open/read the active branch and count visible message roles.

Expected

• The active branch contains one user message followed by the assistant tail.
• Same user text with a different message timestamp is preserved as a distinct turn.
• Duplicate bootstrap custom entries and cloned compactions collapse during replay.

Actual

• Matches expected after this patch.

Evidence

Attach at least one:

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios: local persisted-session runtime script, targeted transcript rewrite regression tests, persisted file-state rewrite path, production core typecheck, test typecheck, formatter, and whitespace check.
• Edge cases checked: repeated user text with distinct message timestamps is not collapsed.
• What you did not verify: full live provider overflow recovery with a real model context overflow.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

If a bot review conversation is addressed by this PR, resolve that conversation yourself. Do not leave bot review conversation cleanup for maintainers.

Compatibility / Migration

• Backward compatible? (Yes/No) Yes
• Config/env changes? (Yes/No) No
• Migration needed? (Yes/No) No
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: overly broad dedupe could remove legitimate repeated turns.
  • Mitigation: message replay identity hashes the full AgentMessage payload, so repeated same text with different timestamps remains a distinct turn; a regression test locks this in.
• Risk: skipped duplicate entries might break later remaps.
  • Mitigation: skipped entry ids map to the first emitted equivalent id, preserving downstream label/compaction remapping.