hook::emit_telemetry drops the envelope once data exceeds the Windows command-line limit

[kyle-sexton]

Summary

hook::emit_telemetry builds the envelope with jq -n … --argjson data "$data_json"
(lib/hook-utils.sh, and every vendored copy). Windows caps a process command line at 32767
characters, so once a producer's data payload serializes past that, jq never runs and the whole
envelope is dropped.

Reproduced on Windows / Git Bash with the same jq the hooks use:

n=100   serialized_bytes=6401    rc=0    findings preserved
n=300   serialized_bytes=19201   rc=0    findings preserved
n=600   serialized_bytes=38401   rc=126  <- argument list too long
n=1200  serialized_bytes=76801   rc=126

rc=126 is the shell reporting the exec failure; jq is never entered, so nothing in the pipeline
can distinguish it from a jq parse error.

Why it matters, and why it is not just "telemetry is lossy"

The contract does say telemetry is best-effort and lossy (docs/conventions/hook-telemetry/README.md).
A dropped envelope under load is inside that contract. The problem is the shape of the loss: it is
deterministic on payload size, so a consumer wiring a sink gets complete data for every ordinary file
and silently nothing for exactly the large or finding-dense files a sink is most likely to be
wired for. That is a systematic blind spot, not sampling.

Scope

Every producer that can emit a large data payload. Known:

• markdown-format — data.findings is one string per unfixable violation, deliberately uncapped.
  A real 324-finding file serializes well past 32 KB.
• typos-format — data.findings plus data.applied, both uncapped.

Other producers with bounded payloads are unaffected today but sit on the same helper.

The same defect class already bit the two plugins' own payload construction and was fixed there by
feeding jq on stdin instead of argv (see #1578, #1589). Those fixes are plugin-local; this one is not,
which is why it is filed separately.

Fix

Pass data_json to jq on stdin rather than as --argjson. The remaining --arg values
(schema_version, timestamp, hook, hook_event, status, duration_ms) are all short and
bounded, so only the one value needs to move.

This is a change to the SSOT lib/hook-utils.sh, so it requires scripts/sync-hook-utils.sh and the
usual version-bump wave across every carrying plugin — which is the reason it is not folded into
either plugin PR.

Not verified

Whether any non-Windows platform hits this. POSIX ARG_MAX is typically 2 MB or more, so the
practical exposure is Windows-only, but that has not been measured here.

[kyle-sexton]

This was generated by AI during triage.

Admission gate: work-class: structural → C4 → human-gated per the work-loop lane's autonomy matrix. Routed to human-gated; not dispatched.

[kyle-sexton]

Cross-reference: two plugin-local halves of this defect have landed, and both had to state the incomplete end-to-end behaviour in their own tests because of what remains here.

• markdown-format fix(markdown-format): stop the telemetry payload lying when it exceeds argv #1600 — build_data_json moved off --argjson.
• typos-format fix(typos-format): disclose every applied correction on both channels #1580 — same, for data.findings plus the new data.applied.

Both now build a correct payload and then hand it to hook::emit_telemetry, which passes it as --argjson data — so on Windows an oversized envelope is dropped rather than delivered. That is the right failure direction and it is what those PRs establish (the failure moved from a falsified payload to a lost one), but it means a consumer wiring a sink still gets nothing for the largest files until this lands.

Both suites assert the invariant rather than a count, specifically so they keep passing unchanged when this is fixed: lost, never falsified. Neither will need editing.

Also relevant: #1587 is already touching lib/hook-utils.sh for a different large-payload defect on the stdin side. Whoever takes this should check whether the two want to ride the same sync-and-bump wave rather than forcing two.

[kyle-sexton]

Drain: tracked by open PR #2465 fix(hook-utils): feed emit_telemetry data to jq on stdin (no duplicate opened).