Summary

This PR fixes the edit-tool mismatch diagnostic truncation path so the Current file contents: hint cannot split an emoji or other astral Unicode character at the 800-character cutoff.

• Why it matters / User impact: When an edit replacement cannot find its exact oldText, the diagnostic should show trustworthy current-file context. A broken replacement character at the truncation boundary makes the hint harder to use when the file contains non-BMP Unicode near the cutoff.
• Maintainer-ready confidence: High for this focused diagnostic fix. The patch touches only the edit-tool mismatch hint path and is covered by a live edit-tool invocation, a targeted regression test, and changed-file core checks.
• What did NOT change: Edit matching, replacement semantics, file writes, newline normalization, post-write recovery, preview rendering, approval flows, gateway protocol, UI approval surfaces, generated Swift models, and plugin/native channel behavior are unchanged.

Real behavior proof

• Behavior or issue addressed: Edit-tool exact-match failures append Current file contents: to the thrown mismatch error. Before this change, long current-file snippets were truncated with raw String.prototype.slice(0, 800), which can split a UTF-16 surrogate pair when the cutoff lands inside an emoji or other astral Unicode character.
• Real environment tested: Windows 10 Enterprise LTSC 2019 via Git Bash, Node v22.17.0, pnpm 11.2.2.
• Exact steps or command run after this patch: From the repository root, I ran a non-test live edit-tool invocation with node --import tsx. The script imported src/agents/sessions/tools/edit.ts, created a temporary file containing 799 ASCII characters, one 🙂 emoji, and trailing text, then called createEditTool(...).execute(...) with a missing oldText to trigger the real mismatch diagnostic path. I also ran the focused regression test and changed-file checks:

node --import tsx <live edit-tool invocation script>
node scripts/run-vitest.mjs src/agents/sessions/tools/edit.test.ts
git diff --check
OPENCLAW_CHECK_CHANGED_REMOTE_CHILD=1 OPENCLAW_CHANGED_LANES_RAW_SYNC=1 CI=1 PNPM_CONFIG_VERIFY_DEPS_BEFORE_RUN=false pnpm check:changed

• Evidence after fix: The live edit-tool invocation produced this copied terminal output, with the temp path redacted:

temp file: <temp-dir>\unicode-boundary.txt
message includes exact mismatch header: true
message includes intact emoji at boundary: true
message includes replacement character: false
snippet tail:
aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa🙂
... (truncated)

LIVE_PROOF_EXIT:0

The focused edit-tool test suite exited 0. git diff --check exited 0. The local changed-file check exited 0 and selected the core/core-test lanes for src/agents/sessions/tools/edit.ts and src/agents/sessions/tools/edit.test.ts.

• Observed result after fix: The live mismatch diagnostic includes the exact mismatch header, keeps the full boundary emoji before ... (truncated), and does not contain the Unicode replacement character. The regression test verifies the same boundary case through createEditTool(...).execute(...), so the hint no longer relies on raw .slice() truncation at the UTF-16 boundary.
• What was not tested: No live external channel, Telegram, Matrix, iMessage, Control UI, gateway, Mantis, or Desktop proof was run because the current patch does not touch those paths. A plain pnpm check:changed invocation attempted to delegate to Blacksmith Testbox through crabbox, but this host's crabbox binary failed its basic sanity check before running repo checks. The local child-mode command above was used for the actual changed-file verification.
• Fix classification: Root cause fix.

What Problem This Solves

When an edit replacement cannot find its exact oldText, the edit tool appends Current file contents: to help the model/user see what actually exists in the file. For long files this diagnostic is capped at EDIT_MISMATCH_HINT_LIMIT characters.

Before this change, the cap used raw JavaScript string slicing. JavaScript slice() counts UTF-16 code units, not displayed Unicode characters/code points. If an emoji or other astral character straddled the 800-code-unit boundary, the hint could include only half of the surrogate pair. That produces a malformed diagnostic snippet at the exact point where the tool is trying to provide useful mismatch context.

Root Cause

• Root cause: The edit mismatch diagnostic source of truth is appendMismatchHint(), and that formatter truncated currentContent with currentContent.slice(0, EDIT_MISMATCH_HINT_LIMIT). That operation counts UTF-16 code units instead of whole Unicode code points, so the diagnostic owner could create an invalid snippet by cutting between the high and low surrogate of a non-BMP character.
• Why this is root-cause fix: The fix changes the truncation primitive at the diagnostic source of truth, before the mismatch hint string is assembled. Iterating with for...of makes the formatter count whole Unicode code points, so the invariant becomes: the edit mismatch hint may be shortened, but it never creates a malformed half-character at the truncation boundary. This fixes the source formatter rather than masking replacement characters after the fact.
• Architecture / source-of-truth check: The source-of-truth boundary is the private edit-tool mismatch hint formatter in src/agents/sessions/tools/edit.ts. No public contract, schema, protocol, config, generated model, or API surface is changed; compatibility and default behavior for edit execution are unchanged. A related open PR / same-contract scan is not relevant because this patch does not define or expand a public contract surface. Out of scope: changing edit matching, replacement, persistence, preview rendering, gateway behavior, approval UI, or any protocol field.

Changes

• Added a small edit-tool-local mismatch snippet helper that iterates currentContent with for...of, so the cutoff is counted by Unicode code point instead of raw UTF-16 code unit.
• Preserved the existing mismatch hint limit and ... (truncated) suffix behavior.
• Added a regression test where the 800th displayed character is an emoji, proving the hint keeps the emoji intact before appending the truncation marker.

Review findings addressed from the previous PR content

This PR previously carried a different approval-prompt/protocol/UI change. That old diff has been removed from the branch and replaced with the focused edit-tool fix above.

• RF-001 / RF-002 / RF-004 / RF-006: old requests for real Telegram, Control UI, gateway, or approval prompt proof no longer apply to the current diff because the approval-flow changes were removed.
• RF-003: old public-ish approval contract compatibility concern no longer applies; the current diff does not touch gateway protocol, generated Swift models, plugin SDK reply parameters, or approval metadata.
• RF-005: the previous draft/readiness gate was for the old approval PR content. Current readiness should be judged from the new edit-tool diff and verification below.
• RF-007: old UI i18n concern no longer applies; the current diff does not add or change approval UI warnings.

Evidence

The live proof and regression test both covered the real edit-tool mismatch error path through createEditTool(...).execute(...), not only a standalone helper. The boundary file contains 799 ASCII characters followed by an emoji and trailing text, then triggers an exact-match miss. The observed diagnostic includes the intact emoji and the existing truncation marker.

Changed-file verification also covered:

conflict markers
changelog attributions
guarded extension wildcard re-exports
plugin-sdk wildcard re-exports
duplicate scan target coverage
dependency pin guard
package patch guard
test temp creation report
typecheck core
typecheck core tests
lint core changed files
database-first legacy-store guard
media download helper guard
runtime sidecar loader guard
runtime import cycles
webhook body guard
pairing store guard
pairing account guard

All selected local changed-file lanes exited 0.

Regression Test Plan

• Target test file: src/agents/sessions/tools/edit.test.ts.
• Scenario locked in: A mismatch hint whose truncation boundary lands after 799 ASCII characters and one emoji.
• Why this is the smallest reliable guardrail: The test exercises the public edit-tool execution path, so it verifies the actual error message users/models see without exporting a formatting helper or adding broader fixtures.
• Expected behavior: the thrown mismatch error contains the full emoji followed by ... (truncated), not a sliced surrogate half or replacement character.
• Existing mismatch behavior remains covered by the existing exact-match diagnostic test.

Merge risk

• Risk labels considered: No merge-risk:* label should be required for the current diff. The old approval-protocol/UI compatibility risk no longer applies because that diff was removed.
• Risk explanation: The change is isolated to diagnostic formatting for edit-tool mismatch errors and keeps the same limit/suffix contract. It does not change edit application, matching, persistence, protocol, UI, or approval behavior.
• Why acceptable: Counting the truncation limit by Unicode code point prevents malformed diagnostics while preserving bounded output and the existing truncation marker. The only behavior difference is that astral Unicode characters are kept whole at the boundary.
• Patch quality notes: This is not a fallback or downstream string special-case. It fixes the truncation primitive at the mismatch hint source, keeps the helper private to the edit tool, and adds a regression test for the exact boundary failure mode.