docs(design)!: agent OTLP rides the agent socket to a host collector (RIG-4611)

[rigel-mintaka]

Summary

Amendment record for agent OTLP routing (docs/designs/observability/compass-agent-collector-routing/design.md). It is rewritten around Matt's RIG-5237 rulings, which are recorded as DL-515.

• C-a: a collector runs on each runner host and exports upstream to the operator's endpoint (bundled, or --otel-external).
• C-b: agents export OTLP/HTTP over their existing agent socket. The Runner gateway mounts /v1/traces, /v1/metrics and /v1/logs. It stamps the bound compass.session.id, compass.telemetry.origin=agent and service.name=compass-agent, then relays to the host collector. There is no OTLP egress, and the socket stays the agent's only channel.
• C-c: devenv runs the collector.
• Relay limits:
  • 8 slots per Gateway and a Runner-wide byte budget;
  • a protowire pre-scan bounds decoded memory, counting messages and repeated scalars, packed or not;
  • one 8 s deadline;
  • status mapping matches OTel JS retry semantics.
• Amended frozen texts: the effect-otel "never the socket/vsock gateway" ruling for agent telemetry, both agent deployer contracts (no env-file endpoint), loop-otel Decision 3a, and parent D3's route clause.
• Removed from the previous draft: pasta, LoopbackForward, the canary, and the old OQ3/OQ4.

Tasks: CA1, CB1, CB2, CB3, CC1, CD1. All open questions are resolved in the record; none needs Matt.

Verification

• rumdl check is clean on the record and DL-515.
• design-ledger-gate:check is OK.
• Code claims were checked against source.
• A throwaway probe measured 4 MiB of OTLP decoding to about 244 MiB, which motivates the decode bound.

Review: a design-critic pass (14 findings) and review rounds R4 (16 findings) and R5 (1 high) are folded. See the review comment.

Risks

• Host-tier agents share the Runner's uid. Host-tier telemetry is one trust domain, not per-session evidence (stated in Global Constraints and DL-515).
• Apple-container inherits the DL-338 slow-roll gap for the whole agent channel.

Compatibility

Breaking for operators:

• --otel-external takes a URL;
• env-file agent OTLP endpoints are ignored;
• combining any two OTel flags is a usage error.

Implementation tasks carry the migrations.

Documentation

CD1 updates the operator docs.

Ledger-impact: DL-515 (docs/designs/decisions/observability/DL-515.md).

Spec-impact: none

[trunk-io]

Merging to main in this repository is managed by Trunk.

• To merge this pull request, check the box to the left or comment /trunk merge below.

After your PR is submitted to the merge queue, this comment will be automatically updated with its status. If the PR fails, failure details will also be posted here

[linear-code]

RIG-4611

RIG-5237

[github-actions]

Compass engineering docs preview: https://compass-obs-rig-4611-agent-c.compass-eng-docs.pages.dev

Deployed from compass-obs/rig-4611-agent-collector-amendment at c0753ea.

Changed pages:

• docs/designs/decisions/observability/DL-515.md
• docs/designs/observability/compass-agent-collector-routing/design.md

[rigel-mintaka]

Review result (head b7566c4)

The review followed skill://review: a review-lead fan-out (correctness, security, design and style) over 3 rounds, after a design-critic pass on the draft.

Round	Head	Findings	Disposition
Critic	draft	2 forks, 14 improvements	Improvements folded. Forks went to RIG-5237 (OQ1 co-location, OQ2 pasta vs. relay).
R1	e9ac5fd	1 high, 8 medium, 8 low	All accepted and fixed in 5ab669c. The high was endpoint precedence against the agent env file; others included the pasta_options widening and a canary, the preflight seam, query and fragment secrets, and header rotation. OQ3 (forged ids) was added. The pre-existing pasta_options exposure was spun out as RIG-5249.
R2	5ab669c	4 medium + lows (12)	All fixed in 6c5af05: --otel-external reaches agents, inherited OTEL_* is scrubbed, --otel-off replaces dummy endpoints, and the pasta capability interface runs support checks first. OQ4 (remote target allowlist) was added.
R3	6c5af05	3 medium (+1 dismissed as OQ4)	Fixed in b7566c4: external auth via the headers file (env, never argv; a 0600 file for agents), shared otlpenv.ParseEndpoint for the runner flag, and an explicit off state for agents.

No open findings. OQ1–OQ4 are with Matt in RIG-5237. rumdl check and design-ledger-gate:check are clean.

[rigel-mintaka]

Review loop on the RIG-5237 rewrite. Head 8f7f9e2.

Round	High	Medium	Low	Disposition
Critic	2	7	5	all fixed in d94c6c1's parent
R4	0	4	16	3 dismissed (public fork package name ×2, data-point merge); rest fixed in d94c6c1
R5	1	0	0	fixed in 67c49db (unpacked repeated scalars counted in the decode bound)

R5 was past K=3, and its fix was one bounded rule plus a test case, so there was no further round. 8f7f9e2 renames the decision file to DL-515 (lane-claimed id). The ledger gate is OK.