fix(harness): truncation marker could push output past its char budget

[teyrebaz33]

Primary change type

• Bug fix
• Documentation
• Feature
• Tests
• Dependency update
• Maintenance or refactor

Problem and motivation

Three truncation helpers in packages/harness write similar truncation-marker formats and had the same bug: they sliced content to exactly the configured budget, then appended the marker AFTER the slice, so the actual output was budget + marker.length characters, not budget.

• truncateForPayload (core/collector/normalizer.ts) — used for toolInput/toolResponseSummary.
• clip (core/record-archive.ts) — used by compactSessionRecord. Also documents an idempotency guarantee ("a second pass finds a body already at the cap and returns it untouched"); that guarantee itself held (0 idempotency violations in a 56-case sweep of the pre-fix code) but converged on a value that was already over budget — the bug was in the first pass's arithmetic, not the unwrap/fold logic.
• clamp (core/resume-brief.ts) — found in a final repo-wide sweep before opening this PR. Same bug, but its marker (CLAMP_MARKER) is a fixed string with no embedded count, so the fix is a single subtraction rather than a converging loop. Of its 7 call sites, 6 had no compensation; the 7th had manually pre-subtracted CLAMP_MARKER.length from its own budget to work around this exact bug.

None of the three is a practical incident today: the aggregate RECORD_MAX_BYTES cap in compactSessionRecord is enforced separately via a real Buffer.byteLength() measurement after clipping and drops whole turns oldest-first until it fits, and resume-brief's overrun is ~12 chars against a token-based ceiling with its own headroom. But all three directly contradicted their own documented guarantees.

Summary and scope

• truncateForPayload/clip: a small converging loop that shrinks the slice point until slice + marker fits within budget (the marker's own length depends on the dropped-char count, which depends on where we slice, which depends on the marker's length), with a final .slice(0, budget) backstop for degenerate tiny budgets.
• clamp: a single subtraction, since CLAMP_MARKER's length is fixed. Also removed the now-unnecessary manual - CLAMP_MARKER.length workaround at clamp's one self-compensating call site, and corrected a stale doc comment that inaccurately described CLAMP_MARKER as "the marker truncateForPayload leaves" (the two are different formats and unrelated at runtime).

Out of scope: packages/harness/web/src/lib/extract-step-context.ts's formatValue, a fourth instance of the same pattern found in the same sweep, has its own separate PR (different subsystem — web frontend, not this collector/archive backend code).

Related work

Related issue or discussion: #655

Validation

# packages/harness: vitest run <file> / tsc --noEmit / eslint <files>
normalizer.test.ts: 15/15 passing
record-archive.test.ts: 19/19 passing
resume-brief.test.ts: 26/26 passing
tsc --noEmit: clean
eslint: 0 errors, 0 warnings on every changed file
record-archive-wiring.test.ts: 2 pre-existing failures (native node-pty module /
  /tmp dir issue in this environment) -- confirmed identical on unmodified main
  via git stash, unrelated to this change

Tests and documentation

Updated three existing tests whose exact-match assertions had encoded the old (over-budget) output as the expected value, with new expected values computed independently and cross-checked. Added two new tests: one for truncateForPayload's degenerate maxLength-smaller-than-marker case, one for clamp's bound via describeToolTarget's public API — confirmed via git stash to fail (92 > 80) against the pre-fix code. Added a 56-case brute-force sweep (clip, bound + idempotency together) and a 54-case sweep (clamp, bound) as one-off verification, referenced in commit messages. No user-facing documentation changes needed.

Compatibility and release impact

• Breaking or externally visible changes: None. All three functions' signatures and return types are unchanged; only truncated outputs near a budget boundary get slightly shorter (by the marker's length) to actually respect the documented bound.
• Changeset: Added (.changeset/fix-harness-truncation-marker-budget.md), patch bump for @sapiom/harness.

Security

• I have not included secrets, credentials, private data, or unsanitized logs.
• This pull request does not publicly disclose a suspected vulnerability. I
  will follow the
  Security Policy for
  private reporting.

AI assistance

• I did not use AI assistance for this change.
• I used AI assistance and have described it below.

I used Claude (Anthropic) as a coding assistant throughout: it helped find the bug pattern (including the third instance in resume-brief.ts, found via a repo-wide grep sweep), draft the fixes and tests, and run the verification commands (tests/typecheck/lint, brute-force sweeps, git stash comparisons) quoted above. I reviewed and ran every command myself, read and understood the resulting diff line by line, and can explain and maintain every change in this PR.

Checklist

• I read CONTRIBUTING.md, and this contribution follows the direct-PR or issue-first policy.
• This pull request addresses one focused problem and contains no unrelated cleanup.
• I added or updated tests, or explained above why tests are not applicable.
• I ran the relevant build, typecheck, lint, and test commands, or explained
  any N/A checks above.
• I updated documentation for user-facing changes, or marked it N/A above.
• I added a Changeset for a published-package change, or explained why it is not applicable.
• I can explain and maintain every submitted change, including any AI-assisted work.