design(compass-agent): loop OpenTelemetry activation record (RIG-2508)

[rigel-mintaka]

Frozen-on-merge design record for activating OpenTelemetry on the compass-agent
agent loop and composing it with the transport's already-merged Effect-scoped
OTel (RIG-2518).

The finding that reframes the issue

RIG-2508 was scoped as "adopt OTel on the loop" on the premise that the loop is
plain-TS on the OMP SDK and needs a from-scratch adoption. That premise is
false. OMP (@oh-my-pi/pi-agent-core, pi-coding-agent) ships full native
GenAI-semantic-convention loop telemetry (invoke_agent > chat / execute_tool
/ handoff spans) that is opt-in and simply never switched on: compass-agent's
sole createAgentSession call passes no telemetry and sources no OTEL_*.
So this is activation + composition, not adoption.

What the record decides

• Approach: mirror OMP's own CLI activation pattern in compass-agent's
  first-party entrypoint (cli.ts main()) — reuse
  @oh-my-pi/pi-coding-agent/telemetry-export's initTelemetryExport() /
  isTelemetryExportEnabled() (a declared wildcard subpath export) rather than
  writing a first-party registration module. Off by default (no OTLP endpoint →
  no provider → no egress → black-box behaviour bit-identical to today).
• OQ1 (the load-bearing fork), RULED by Matt → (b): the loop and transport
  run as two independent providers exporting to one collector, not unified
  into one global trace tree. (a) unify is cheap to build but buys almost
  nothing — the parent/child links are fictional (transport pump/batch/reconnect
  fibers fork at construction, outside any loop span's async-local context), and
  a genuinely unified view is a span-links problem for later, not parentage.
  (b) is zero transport delta and keeps the merged RIG-2518 record frozen.
• No new dependencies, no agent-image FOD bump: reuse keeps all OTel code
  inside pi-coding-agent's own dependency closure, already in bun.lock.
• Correlation join key: both signals stamp service.name = compass-agent
  plus a shared compass.session.id resource attribute (via
  OTEL_RESOURCE_ATTRIBUTES, read natively by both providers, zero transport
  code), so two agents on one collector are separable.

Provenance

Drafted by a design subagent, red-teamed by a design-critic (0 blockers; all
five should-fix findings folded — the service-name split, the off-is-bit-
identical ??= gating, the test global-registration isolation hazard, the
16.4.8→16.5.2 version drift, and the endpoint-gate asymmetry). Every code claim
carries file+line grounded in the pinned OMP build and the compass-agent tree.

Freezes on merge; T1/T2 impl follow as their own gated PRs.

Spec-impact: none. Refs RIG-2508, RIG-2384, RIG-2518

Co-authored-by: Matt Wilkinson matt@rigel.build

[linear-code]

RIG-2508

RIG-2384

RIG-2518

[github-actions]

Compass engineering docs preview: https://compass-agent-rig-2508-loop.compass-eng-docs.pages.dev

Deployed from compass-agent/rig-2508-loop-otel-design at 4ac8ba2.

Changed pages:

• docs/designs/platform/compass-agent-loop-otel/design.md