Summary

• Keep extension/custom-tool exec retained stdout and stderr UTF-16 safe when output is caller-capped.
• Reuse the shared sliceUtf16Safe helper for both tail-retention and default output-limit truncation.
• Add regression coverage for caller-supplied caps and the default output-limit path.

What Problem This Solves

Extension runtime commands can return stdout/stderr containing non-BMP characters such as emoji. execCommand retained output with String.prototype.slice, so a cap that landed between UTF-16 surrogate halves could return a dangling surrogate in the retained stream.

The anchor PR fixed the same class of truncation bug for exec auto-reviewer rationale text. This follow-up applies the same shared UTF-16-safe truncation invariant to extension/custom-tool command output retention.

User Impact

Users running extensions or custom tools that emit emoji or other non-BMP text could receive broken retained stdout/stderr after truncation. That broken text can be surfaced as command output, diagnostics, or model-visible tool output. After this patch, truncation may retain one fewer UTF-16 code unit at a split boundary, but it will not return an invalid surrogate half.

Origin / follow-up

Follows and completes #101513.

• Anchor: fix(agents): keep exec auto-reviewer rationale truncation UTF-16 safe #101513 fixed exec auto-reviewer rationale truncation by using UTF-16-safe truncation.
• Gap this fills: src/agents/sessions/exec.ts still used raw slice() for retained stdout/stderr in the extension/custom-tool command execution path.
• Consistency: This patch reuses the existing @openclaw/normalization-core/utf16-slice helper instead of introducing another truncation implementation.

Competition / linked PR analysis

I checked current open PRs and issues for the same execCommand / extension exec UTF-16 truncation gap.

• No open issue matched extension exec output UTF-16 surrogate or execCommand truncation surrogate.
• No open PR matched execCommand truncation UTF-16 safe.
• One open PR mentions surrogate-safe truncation in a different memory-core dreaming snippet path; it does not touch src/agents/sessions/exec.ts or the extension exec stdout/stderr retention path.
• Related open PR scan: no same-file or same-runtime duplicate was found for this patch.

Real behavior proof

• Behavior or issue addressed: extension/custom-tool exec retained stdout/stderr must not contain dangling UTF-16 surrogate halves after truncation.
• Why it matters / User impact: extension command output is user-triggered text that can be returned as stdout/stderr; a split surrogate can show replacement characters or invalid text to the next consumer.
• Canonical reachability path: user-triggered extension command output input → child-process pipe ingestion and Buffer-to-string type conversion in execCommand → ExecResult runtime object → retained stdout/stderr returned as the command effect.
• Boundary crossed: child-process stdout/stderr pipe payloads are captured through the same execCommand retention logic used by extension command execution.
• Shared helper / provider constraint check: existing repository helper sliceUtf16Safe is reused; provider-specific constraints are not applicable to this local command-output boundary.
• Architecture / source-of-truth check: appendCapturedOutput is the source-of-truth retention boundary for ExecResult stdout/stderr caps. The patch fixes the invariant there instead of adding a downstream cleanup step, so stored/returned command output share the same safe retained text.
• Real environment tested: local OpenClaw repo on Node/Vitest using the shipped child-process output capture boundary.
• Exact steps or command run after this patch:

node scripts/test-projects.mjs src/agents/sessions/exec.test.ts

node --import tsx --input-type=module
# Imported src/agents/sessions/exec.ts, executed a child process that wrote
# A😀B to stdout and C😀D to stderr, and called execCommand(..., { maxOutputChars: 2 }).

• Evidence after fix:

$ node scripts/test-projects.mjs src/agents/sessions/exec.test.ts
Test Files  1 passed (1)
Tests  7 passed (7)
[test] passed 1 Vitest shard in 11.57s

{
  "stdout": "B",
  "stderr": "D",
  "stdoutLength": 1,
  "stderrLength": 1,
  "stdoutCodes": ["42"],
  "stderrCodes": ["44"],
  "stdoutDangling": [],
  "stderrDangling": [],
  "stdoutTruncatedChars": 3,
  "stderrTruncatedChars": 3,
  "code": 0
}

• Observed result after fix: stdout and stderr retain valid text with no dangling surrogate halves; truncation counts reflect the actual removed UTF-16 code units.
• What was not tested: full dev gateway startup was not run because the changed boundary is the local execCommand child-process output capture path.
• What did NOT change: no extension loader API, process spawning, timeout, abort, process-tree cleanup, model routing, or network behavior changed.
• Target test file: src/agents/sessions/exec.test.ts.
• Scenario locked in: caller-capped stdout A😀B and stderr C😀D with maxOutputChars: 2 now retain B and D without dangling surrogate halves; the default output-limit path also avoids retaining a half emoji at the cap boundary.
• Why this is the smallest reliable guardrail: the regression hits execCommand at the retained-output source-of-truth boundary, covers both stdout and stderr, and also covers the default limit path where the same helper is now used.
• Fix classification: Root cause fix
• Maintainer-ready confidence: High. The diff is limited to two slicing call sites plus focused tests, and fresh verification is bound to the committed diff.
• Patch quality notes: Patch quality warning considered: this is not a fallback, default-value change, catch/ignore path, or downstream masking step; it replaces unsafe slicing at the retention source.

Review findings addressed

No maintainer review findings are attached to this follow-up yet. This patch addresses the sibling gap left by #101513 in the extension exec output retention path.

Regression Test Plan

node scripts/test-projects.mjs src/agents/sessions/exec.test.ts

The regression suite now covers:

• caller-capped retained stdout/stderr containing emoji at the truncation boundary;
• default output-limit truncation when the cap would otherwise split an emoji surrogate pair;
• existing independent stdout/stderr retention, process-tree cleanup, timeout, and stream-error behavior.

Merge risk

• Risk labels considered: no merge-risk label is expected for this XS scoped agents/runtime retention patch; changed files are src/agents/sessions/exec.ts and src/agents/sessions/exec.test.ts only.
• Risk explanation: retained output can become one UTF-16 code unit shorter at a surrogate boundary, but caps remain enforced and returned text becomes valid rather than partially split.
• Why acceptable: this preserves the existing API and truncation behavior while enforcing the text-validity invariant already used by the shared helper.

Risk / Compatibility

Risk is low and localized to retained output truncation in execCommand.

• API shape is unchanged.
• Output caps remain enforced.
• At a surrogate boundary, retained output may be one UTF-16 code unit shorter than the raw cap to avoid returning invalid text.
• stdoutTruncatedChars and stderrTruncatedChars now count the actual number of removed UTF-16 code units after safe slicing.

What was not changed

• No extension loader API changes.
• No process spawning, timeout, abort, or process-tree cleanup behavior changes.
• No model routing or network behavior changes.
• No new truncation helper was added.

Root Cause

• Root cause: execCommand used raw String.prototype.slice() to enforce retained output caps. JavaScript slicing is based on UTF-16 code units, so slicing at a cap boundary can return only one half of a surrogate pair.
• Why this is root-cause fix: The fix replaces both affected slicing sites in appendCapturedOutput with the shared UTF-16-safe helper, covering tail retention for caller-supplied caps and head retention for default output-limit enforcement at the source where retained stdout/stderr is produced.