Hmbown/CodeWhale · error · RuntimeError

Codewhale terminal receipt exceeded its total bound

Error message

Codewhale terminal receipt exceeded its total bound

What it means

The harness re-encodes the terminal metadata receipt it extracted from Codewhale's stream-json output and enforces a hard 8 KiB ceiling (MAX_TERMINAL_RECEIPT_BYTES = 8_192 in harness.py). After each field passes per-value bounds (strings <= 512 chars, ints in [0, 2^63-1]), the whole dict is JSON-dumped and its byte length is checked. This error means the receipt was structurally valid but its combined fields serialized to more than 8192 bytes, so the harness refuses to retain it in trace metadata.

Source

Thrown at integrations/verifiers-codewhale/codewhale_harness/harness.py:272

def _bounded_terminal(meta: dict[str, Any]) -> dict[str, Any]:
    terminal: dict[str, Any] = {}
    for key in _TERMINAL_FIELDS:
        if key not in meta or meta[key] is None:
            continue
        value = meta[key]
        if isinstance(value, str):
            if len(value) > MAX_TERMINAL_STRING_CHARS:
                raise RuntimeError("Codewhale terminal receipt exceeded its string bound")
        elif isinstance(value, int) and not isinstance(value, bool):
            if value < 0 or value > 2**63 - 1:
                raise RuntimeError("Codewhale terminal receipt contained an invalid count")
        else:
            raise RuntimeError("Codewhale terminal receipt contained a non-scalar field")
        terminal[key] = value
    encoded = json.dumps(terminal, sort_keys=True, separators=(",", ":")).encode()
    if len(encoded) > MAX_TERMINAL_RECEIPT_BYTES:
        raise RuntimeError("Codewhale terminal receipt exceeded its total bound")
    return terminal


def _install_script(version: str) -> str:
    version_q = shlex.quote(version)
    install_q = shlex.quote(INSTALL_DIR)
    release_q = shlex.quote(RELEASE_ROOT)
    return f"""
set -eu
version={version_q}
install_dir={install_q}
release_root={release_q}
if [ "$(uname -s)" != Linux ]; then
    echo "automatic Codewhale installation supports Linux runtimes; set binary_path" >&2
    exit 1
fi
case "$(uname -m)" in
    x86_64|amd64) platform=linux-x64 ;;

View on GitHub (pinned to 8880682c63)

Solutions

1. Pin CodewhaleHarnessConfig.version to the supported release (default '0.9.1') so the terminal receipt field set and sizes match what the harness validates.
2. If using binary_path with a candidate build, shorten the oversized string fields (model, provider, status, termination_reason, error_category) in the facade's terminal metadata so the encoded receipt stays under 8192 bytes.
3. Reproduce locally: json.dumps(terminal, sort_keys=True, separators=(',', ':')) on the facade's metadata event and inspect which fields dominate the 8192-byte budget.
4. If a legitimately larger receipt is required, raise MAX_TERMINAL_RECEIPT_BYTES and MAX_TERMINAL_STRING_CHARS in harness.py deliberately, with a matching change on the producer side.

Example fix

# before: facade writes unbounded diagnostic into the receipt
meta['error_category'] = f'{exc!r}'  # can be thousands of chars

# after: bounded field, receipt stays under the total bound
meta['error_category'] = exc.__class__.__name__[:512]

def receipt_fits_bound(terminal: dict) -> bool:
    encoded = json.dumps(terminal, sort_keys=True, separators=(",", ":")).encode()
    return len(encoded) <= 8192 and all(
        len(v) <= 512 for v in terminal.values() if isinstance(v, str)
    )

def is_bounded_terminal(meta: dict) -> bool:
    allowed = {"receipt_kind", "provider", "model", "status"}  # subset check
    return isinstance(meta, dict) and receipt_fits_bound(meta) and all(
        isinstance(v, (str, int)) and not isinstance(v, bool) for v in meta.values()
    )

When it happens

Trigger: A Codewhale binary emits a terminal metadata event whose _TERMINAL_FIELDS (provider, model, status, error_category, the four sha256 fields, token counts, etc.) collectively exceed 8192 bytes when JSON-encoded with sort_keys and compact separators. Typical cause: several string fields each near the 512-char limit (e.g. a very long model name plus long status/termination_reason/error_category strings), or a binary version that adds fields beyond the pinned 0.9.1 set.

Common situations: Version skew: a newer or locally patched Codewhale facade (binary_path override) emits richer metadata than release 0.9.1; debug builds that embed long diagnostic strings into status/error_category; provider identifiers that include long suffixes. The harness pins version 0.9.1 for reproducible rollouts precisely to avoid this drift.

Related errors

• Codewhale stream-json line {line_number} was not an object
• Codewhale emitted more than one terminal metadata receipt
• Codewhale metadata event was not a terminal receipt
• Codewhale terminal receipt omitted a valid {field}
• Codewhale stream-json line {line_number} was not valid JSON

AI-assisted analysis of Hmbown/CodeWhale@8880682c63 (2026-08-16). Data as JSON: /api/errors/0ddb1776e80eb736. Report an issue: GitHub.