fix(collector): make trace failures self-explanatory in the JSON envelope

[burrows99]

Why

Minted from a real debugging session: the trace itself worked, but every failure after it was lossy in exactly the channel an agent consumes (--json + exit code). The model spent ~7 minutes chasing a wrong cause. The root pattern: the CLI knew the answer but put it where the agent doesn't look (human-render lines, info logs, or one undifferentiated 400). Each fix moves the signal into the envelope.

The session's smoking gun: a real --emit failed with password authentication failed for user "trace" — a Postgres failure — returned as 400, the same code as a malformed envelope. The model probed with a junk payload, got a different 400 ("invalid envelope"), fused the two, and concluded --concise was trimming required fields (it isn't — see #3).

Changes

1. Collector route — separate fault domains, add machine codes, stop leaking internals (ui/app/v1/traces/route.ts)

• Parse/validate failures → 4xx (caller's fault). Store/DB failure → 503 STORE_UNAVAILABLE, real cause logged server-side, not returned.
• Every response carries a code from the shared vocabulary (INGEST / INGEST_INVALID / INGEST_NO_SESSION / STORE). No more string-matching; infra outage ≠ bad envelope.
• Re-exports Code from trace-cli/server so the route reuses the one vocabulary instead of drifting literals.

2. Emit failures surface instead of vanishing (src/collector/Collector.ts, src/cli/Cli.ts)

• Collector.emit returns a rich EmitResult {ok,status,body,error} and logs rejections at error with the reason — previously a 400 logged at info and the bare false was swallowed by .catch(() => false).
• The run flushes pending emits before rendering and folds any rejection into the printed/--json envelope as an EMIT diagnostic. A run whose every emit 400'd no longer prints "success."

3. --concise no longer reads like it shapes the wire (src/cli/Cli.ts)

• Help now states it trims the printed envelope only and does NOT affect --emit (the collector always receives the full trace.toJSON()). Closes the false lead the session chased.

4. 0-hit runs explain themselves in JSON (src/shared/codes.ts, src/cli/commands/DynamicCommand.ts)

• New BP_BOUND_UNHIT diagnostic when a breakpoint binds but never fires — the JSON counterpart of the renderer's "no breakpoints hit" line. A --json reader can now tell "trigger didn't run" from "wrong line" without grepping server logs.

5. Port clarity (src/cli/commands/ServeCommand.ts, docker-compose.yml)

• trace serve prints the exact --emit URL to copy (auto-discovery only probes the well-known ports). Fixed the stale :4747 compose comment (host port is 14747).

Tests

• Extends test/output.test.js: asserts Code.BP_BOUND_UNHIT, and that Collector.emit resolves to a structured result (never throws, never a bare bool) on a refused POST.
• CLI tsc --noEmit clean · UI tsc --noEmit clean · npm test → 41/41 pass (1 DB round-trip skipped).

Base

Branched off master (which already carries the 14747 host-port mappings — fix #5 corrects the lone stale :4747 compose comment they left behind).

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR improves end-to-end debuggability of --emit/collector failures and “0-hit” dynamic runs for --json consumers by introducing shared machine-readable codes and surfacing emit/ingest failure reasons in structured outputs instead of losing them in human logs.

Changes:

• Adds collector ingest fault-domain separation (4xx envelope issues vs 503 store issues) and returns shared Code values in ingest responses.
• Makes Collector.emit return a structured result and updates CLI flow to flush emits before rendering and emit an EMIT diagnostic on failures.
• Introduces BP_BOUND_UNHIT to explain “breakpoints bound but never hit” in JSON diagnostics; updates serve output and compose comment for port clarity.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
ui/app/v1/traces/route.ts	Adds structured ingest error codes and distinguishes client envelope errors from store outages (503).
src/collector/Collector.ts	Changes emit() to return a rich result and logs HTTP rejections as errors with collector-provided details.
src/cli/Cli.ts	Flushes pending emits before printing output and surfaces emit failures as diagnostics; clarifies --concise help text.
src/cli/commands/DynamicCommand.ts	Adds BP_BOUND_UNHIT warning when breakpoints bind but no events fire.
src/shared/codes.ts	Adds BP_BOUND_UNHIT and collector/emit-related codes to the shared code vocabulary.
src/server.ts	Re-exports Code so the Next.js collector route can reuse the shared vocabulary.
test/output.test.js	Extends tests to cover new code and Collector.emit structured failure behavior.
docker-compose.yml	Fixes a stale compose comment to reference the correct exposed host port.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.