agentirc-cli 8.4.0__tar.gz → 8.6.0__tar.gz

{agentirc_cli-8.4.0 → agentirc_cli-8.6.0}/CHANGELOG.md

@@ -4,6 +4,40 @@ All notable changes to this project will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/).
 
+## [8.6.0] - 2026-04-26
+
+### Added
+
+- Harness-side OTEL: 3 spans (harness.irc.connect, harness.irc.message.handle, harness.llm.call) and 4 LLM metrics (culture.harness.llm.tokens.input/output, call.duration, calls).
+- W3C traceparent injection on outbound IRC + extraction on inbound — single trace_id now spans server, federation, and harness in the cross-process tree.
+- Per-backend telemetry citation across claude/codex/copilot/acp with all-backends parity test (24 tests across 6 dimensions) locking down drift.
+- docs/agentirc/harness-telemetry.md — new operator guide for the harness OTEL pillar.
+
+### Changed
+
+- packages/agent-harness/{telemetry.py,config.py,culture.yaml,irc_transport.py,daemon.py} — reference module for the citation pattern.
+- culture/clients/{claude,codex,copilot,acp}/{telemetry.py,config.py,culture.yaml,irc_transport.py,daemon.py,agent_runner.py} — telemetry citation, harness.llm.call span wrap, record_llm_call invocation.
+- tests/harness/ — 70 new tests (24 parity + 46 module/runner/transport/daemon).
+
+### Fixed
+
+- Code-quality fixes from review: zero-token usage extraction (0 no longer silenced), tracer-name from constant (no hardcoded strings), module-top imports of record_llm_call across all 4 backends.
+
+## [8.5.0] - 2026-04-25
+
+### Added
+
+- `culture/telemetry/audit.py` — `AuditSink` with bounded `asyncio.Queue` + dedicated writer task + daily/size rotation + `0600`/`0700` perms.
+- Public `culture.telemetry.AuditSink`, `init_audit`, `build_audit_record`, `utc_iso_timestamp`.
+- `TelemetryConfig.audit_enabled` (default `True`), `audit_dir`, `audit_max_file_bytes`, `audit_rotate_utc_midnight`, `audit_queue_depth` — independent of `telemetry.enabled` (audit fires even with OTEL off).
+- `culture/protocol/extensions/audit.md` — JSONL record schema as a stable contract.
+- `docs/agentirc/audit.md` — operator guide.
+- Audit metrics extend the Plan-3 `MetricsRegistry`: `culture.audit.writes` (Counter, labels `outcome=ok|error`) and `culture.audit.queue_depth` (UpDownCounter).
+- `IRCd.__init__` creates the sink; `IRCd.start()` awaits `sink.start()`; `IRCd.stop()` awaits `sink.shutdown()` so SERVER_WAKE / SERVER_SLEEP both land in the JSONL.
+- `IRCd.emit_event` submits one record per event after the `irc.event.emit` span; `trace_id` / `span_id` captured inside the span for cross-pillar joins.
+- `Client._process_buffer` submits `PARSE_ERROR` records for malformed inbound lines.
+- Federation audit: federated `message` events arrive on the receiver with `origin=federated`, `peer=<peer_name>`. Federated lifecycle events (JOIN/PART/QUIT) are deferred — see #296.
+
 ## [8.4.0] - 2026-04-25
 
 ### Added

{agentirc_cli-8.4.0 → agentirc_cli-8.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentirc-cli
-Version: 8.4.0
+Version: 8.6.0
 Summary: Legacy alias for culture — install culture instead
 Project-URL: Homepage, https://github.com/OriNachum/culture
 Author: Ori Nachum

{agentirc_cli-8.4.0 → agentirc_cli-8.6.0}/culture/agentirc/client.py

@@ -17,6 +17,7 @@ from culture.aio import maybe_await
 from culture.constants import SYSTEM_USER_PREFIX
 from culture.protocol import replies
 from culture.protocol.message import Message
+from culture.telemetry.audit import utc_iso_timestamp as _utc_iso_timestamp
 from culture.telemetry.context import TRACEPARENT_TAG as _TP_TAG_NAME
 from culture.telemetry.context import (
     context_from_traceparent,
@@ -148,6 +149,7 @@ class Client:
                             "error": type(exc).__name__,
                         },
                     )
+                    self._submit_parse_error_audit(line, exc)
                     continue
                 # Record received bytes + message size for every successfully-parsed
                 # line.  +2 accounts for the \r\n that was stripped during line-split.
@@ -160,6 +162,49 @@ class Client:
                     await self._dispatch(msg)
             return buffer
 
+    def _submit_parse_error_audit(self, line: str, exc: BaseException) -> None:
+        """Build and submit a PARSE_ERROR audit record for a malformed inbound line.
+
+        The record cannot go through build_audit_record (which expects an Event);
+        PARSE_ERROR is a synthetic event_type with no Event object behind it.
+        """
+        # Capture trace/span ids from the active span (the
+        # `irc.client.process_buffer` we're inside of).
+        span = _otel_trace.get_current_span()
+        ctx = span.get_span_context()
+        trace_id_hex = format(ctx.trace_id, "032x") if ctx.is_valid else ""
+        span_id_hex = format(ctx.span_id, "016x") if ctx.is_valid else ""
+
+        peer_info = self.writer.get_extra_info("peername")
+        remote_addr = f"{peer_info[0]}:{peer_info[1]}" if peer_info else ""
+
+        tags: dict[str, str] = {}
+        tp = current_traceparent()
+        if tp:
+            tags["culture.dev/traceparent"] = tp
+
+        record = {
+            "ts": _utc_iso_timestamp(time.time()),
+            "server": self.server.config.name,
+            "event_type": "PARSE_ERROR",
+            "origin": "local",
+            "peer": "",
+            "trace_id": trace_id_hex,
+            "span_id": span_id_hex,
+            "actor": {
+                "nick": self.nick or "",
+                "kind": "human",
+                "remote_addr": remote_addr,
+            },
+            "target": {"kind": "", "name": ""},
+            "payload": {
+                "line_preview": line[:64],
+                "error": type(exc).__name__,
+            },
+            "tags": tags,
+        }
+        self.server.audit.submit(record)
+
     async def handle(self, initial_msg: str | None = None) -> None:
         peer_info = self.writer.get_extra_info("peername")
         remote_addr = f"{peer_info[0]}:{peer_info[1]}" if peer_info else ""

{agentirc_cli-8.4.0 → agentirc_cli-8.6.0}/culture/agentirc/config.py

@@ -26,6 +26,13 @@ class TelemetryConfig:
     traces_sampler: str = "parentbased_always_on"
     metrics_enabled: bool = True
     metrics_export_interval_ms: int = 10000
+    # Audit JSONL sink (Plan 4). Independent of `enabled` — audit fires
+    # even when telemetry is off so admins always have the trail.
+    audit_enabled: bool = True
+    audit_dir: str = "~/.culture/audit"
+    audit_max_file_bytes: int = 256 * 1024 * 1024  # 256 MiB
+    audit_rotate_utc_midnight: bool = True
+    audit_queue_depth: int = 10000
 
 
 @dataclass

{agentirc_cli-8.4.0 → agentirc_cli-8.6.0}/culture/agentirc/ircd.py

@@ -23,12 +23,14 @@ from culture.constants import (
     SYSTEM_USER_PREFIX,
 )
 from culture.protocol.message import Message
+from culture.telemetry import build_audit_record, current_traceparent
 
 logger = logging.getLogger(__name__)
 
 # Span/metric attribute keys defined once so a future rename has one edit point.
 _ATTR_EVENT_TYPE = "event.type"
 
+
 if TYPE_CHECKING:
     from culture.agentirc.client import Client
     from culture.agentirc.remote_client import RemoteClient
@@ -39,11 +41,12 @@ class IRCd:
     """The culture IRC server."""
 
     def __init__(self, config: ServerConfig):
-        from culture.telemetry import init_metrics, init_telemetry
+        from culture.telemetry import init_audit, init_metrics, init_telemetry
 
         self.config = config
         self.tracer = init_telemetry(config)
         self.metrics = init_metrics(config)
+        self.audit = init_audit(config, self.metrics)
         self.clients: dict[str, Client | VirtualClient] = {}  # nick -> Client
         self.channels: dict[str, Channel] = {}  # name -> Channel
         self.skills: list[Skill] = []
@@ -74,6 +77,8 @@ class IRCd:
         logger.info("Bootstrapping system identity...")
         self._bootstrap_system_identity()
 
+        await self.audit.start()
+
         await self.emit_event(
             Event(
                 type=EventType.SERVER_WAKE,
@@ -223,14 +228,25 @@ class IRCd:
         self.metrics.events_emitted.add(1, {_ATTR_EVENT_TYPE: event_type_str, "origin": origin_str})
         render_started = time.perf_counter()
 
+        trace_id_hex = ""
+        span_id_hex = ""
+        tp: str | None = None
+
         # Per-call get_tracer: the `tracing_exporter` test fixture swaps the
         # global provider between tests; a cached Tracer would bind to the
         # first test's provider and stop delivering to later ones.
         with _otel_trace.get_tracer("culture.agentirc").start_as_current_span(
             "irc.event.emit", attributes=attrs
-        ):
+        ) as span:
             seq = self.next_seq()
             self._event_log.append((seq, event))
+            ctx = span.get_span_context()
+            if ctx.is_valid:
+                trace_id_hex = format(ctx.trace_id, "032x")
+                span_id_hex = format(ctx.span_id, "016x")
+            # Capture traceparent inside the span so trace_flags reflect
+            # the actual sampling decision for this span, not a hardcoded -01.
+            tp = current_traceparent()
             await self._run_skill_hooks(event)
             if not origin_tag:
                 await self._relay_to_peers(event)
@@ -240,6 +256,22 @@ class IRCd:
         render_ms = (time.perf_counter() - render_started) * 1000.0
         self.metrics.events_render_duration.record(render_ms, {_ATTR_EVENT_TYPE: event_type_str})
 
+        # Audit submit happens after the span exits so it doesn't sit inside
+        # the irc.event.emit span (would skew render duration). The trace_id/
+        # span_id captured inside the span point back at it for cross-pillar
+        # joins.
+        tags: dict[str, str] = {"culture.dev/traceparent": tp} if tp else {}
+        self.audit.submit(
+            build_audit_record(
+                server_name=self.config.name,
+                event=event,
+                origin_tag=origin_tag,
+                trace_id=trace_id_hex,
+                span_id=span_id_hex,
+                extra_tags=tags,
+            )
+        )
+
     _NO_SURFACE_TYPES = NO_SURFACE_EVENT_TYPES
 
     @staticmethod
@@ -395,6 +427,7 @@ class IRCd:
             if self._server:
                 self._server.close()
                 await self._server.wait_closed()
+            await self.audit.shutdown()
         finally:
             self._stopped.set()
 

{agentirc_cli-8.4.0 → agentirc_cli-8.6.0}/culture/clients/acp/agent_runner.py

@@ -12,9 +12,16 @@ import logging
 import os
 import shutil
 import tempfile
-from typing import Any, Awaitable, Callable
+import time
+from typing import TYPE_CHECKING, Any, Awaitable, Callable
+
+from opentelemetry import trace as _otel_trace
 
 from culture.aio import maybe_await
+from culture.clients.acp.telemetry import _HARNESS_TRACER_NAME, record_llm_call
+
+if TYPE_CHECKING:
+    from culture.clients.acp.telemetry import HarnessMetricsRegistry
 
 logger = logging.getLogger(__name__)
 
@@ -36,6 +43,8 @@ class ACPAgentRunner:
         on_exit: Callable[[int], Awaitable[None]] | None = None,
         on_message: Callable[[dict[str, Any]], Awaitable[None]] | None = None,
         on_turn_error: Callable[[], Awaitable[None] | None] | None = None,
+        metrics: HarnessMetricsRegistry | None = None,
+        nick: str = "",
     ) -> None:
         self.model = model
         self.directory = directory
@@ -44,6 +53,8 @@ class ACPAgentRunner:
         self.on_exit = on_exit
         self.on_message = on_message
         self.on_turn_error = on_turn_error
+        self._metrics = metrics
+        self._nick = nick
 
         self._isolated_home: str | None = None
         self._process: asyncio.subprocess.Process | None = None
@@ -431,16 +442,47 @@ class ACPAgentRunner:
 
     async def _execute_single_prompt(self, text: str) -> None:
         """Send one prompt and handle its result, managing the busy flag."""
-        try:
-            self._busy = True
-            resp = await self._send_prompt_with_retry(text)
-            await self._handle_prompt_result(resp)
-        except Exception:
-            logger.exception("ACP turn error")
-            if self.on_turn_error:
-                await maybe_await(self.on_turn_error())
-        finally:
-            self._busy = False
+        start_perf = time.perf_counter()
+        outcome = "success"
+        tracer = _otel_trace.get_tracer(_HARNESS_TRACER_NAME)
+        with tracer.start_as_current_span(
+            "harness.llm.call",
+            attributes={
+                "harness.backend": "acp",
+                "harness.model": self.model,
+                "harness.nick": self._nick,
+            },
+        ):
+            try:
+                self._busy = True
+                resp = await self._send_prompt_with_retry(text)
+                await self._handle_prompt_result(resp)
+            except TimeoutError:  # bubbles from _send_prompt_with_retry's retry-then-fail
+                outcome = "timeout"
+                logger.exception("ACP turn timeout")
+                if self.on_turn_error:
+                    await maybe_await(self.on_turn_error())
+            except Exception:
+                outcome = "error"
+                logger.exception("ACP turn error")
+                if self.on_turn_error:
+                    await maybe_await(self.on_turn_error())
+            finally:
+                self._busy = False
+        duration_ms = (time.perf_counter() - start_perf) * 1000.0
+        if self._metrics is not None:
+            # ACP token usage MAY arrive in session/update stopReason payload;
+            # current implementation does not extract — usage=None for v1.
+            # When we add extraction (per backing agent), thread through here.
+            record_llm_call(
+                self._metrics,
+                backend="acp",
+                model=self.model,
+                nick=self._nick,
+                usage=None,
+                duration_ms=duration_ms,
+                outcome=outcome,
+            )
 
     async def _prompt_loop(self) -> None:
         """Process queued prompts one at a time."""

{agentirc_cli-8.4.0 → agentirc_cli-8.6.0}/culture/clients/acp/config.py

@@ -62,6 +62,27 @@ class AgentConfig:
     icon: str | None = None
 
 
+@dataclass
+class TelemetryConfig:
+    """OpenTelemetry settings for the agent harness.
+
+    ``enabled: false`` by default so freshly installed harnesses don't
+    try to connect to a non-existent OTLP collector. Flip to ``true``
+    once your collector is running.
+    """
+
+    enabled: bool = False
+    service_name: str = "culture.harness.acp"
+    otlp_endpoint: str = "http://localhost:4317"
+    otlp_protocol: str = "grpc"  # grpc | http/protobuf (only grpc supported initially)
+    otlp_timeout_ms: int = 5000
+    otlp_compression: str = "gzip"
+    traces_enabled: bool = True
+    traces_sampler: str = "parentbased_always_on"
+    metrics_enabled: bool = True
+    metrics_export_interval_ms: int = 10000
+
+
 @dataclass
 class DaemonConfig:
     """Top-level daemon configuration."""
@@ -69,6 +90,7 @@ class DaemonConfig:
     server: ServerConnConfig = field(default_factory=ServerConnConfig)
     supervisor: SupervisorConfig = field(default_factory=SupervisorConfig)
     webhooks: WebhookConfig = field(default_factory=WebhookConfig)
+    telemetry: TelemetryConfig = field(default_factory=TelemetryConfig)
     buffer_size: int = 500
     poll_interval: int = 60
     sleep_start: str = "23:00"
@@ -91,6 +113,7 @@ def load_config(path: str | Path) -> DaemonConfig:
     supervisor = SupervisorConfig(**raw.get("supervisor", {}))
 
     webhooks = WebhookConfig(**raw.get("webhooks", {}))
+    telemetry = TelemetryConfig(**raw.get("telemetry", {}))
 
     agents = []
     known_agent_fields = {f.name for f in AgentConfig.__dataclass_fields__.values()}
@@ -102,6 +125,7 @@ def load_config(path: str | Path) -> DaemonConfig:
         server=server,
         supervisor=supervisor,
         webhooks=webhooks,
+        telemetry=telemetry,
         buffer_size=raw.get("buffer_size", 500),
         poll_interval=raw.get("poll_interval", 60),
         sleep_start=raw.get("sleep_start", "23:00"),

agentirc_cli-8.6.0/culture/clients/acp/culture.yaml

@@ -0,0 +1,32 @@
+suffix: harness-acp
+backend: claude
+model: claude-opus-4-6
+channels:
+  - "#harness"
+acp_command:
+  - opencode
+  - acp
+system_prompt: |
+  You maintain the ACP agent backend in culture/clients/acp/.
+  Listen on #harness for propagation instructions from spark-harness.
+  Apply changes using the citation pattern (cite, don't import),
+  adapting for ACP (Cline, OpenCode, Kiro)
+  specifics (agent_runner.py, supervisor.py).
+tags:
+  - harness
+  - acp
+
+# OpenTelemetry configuration for the agent harness.
+# Set enabled: true once your OTLP collector is running.
+# See docs/agentirc/harness-telemetry.md for a setup guide.
+telemetry:
+  enabled: false                          # master switch — flip to true to start exporting
+  service_name: culture.harness.acp       # overridden per-backend (e.g. culture.harness.acp)
+  otlp_endpoint: http://localhost:4317    # OTLP/gRPC receiver endpoint
+  otlp_protocol: grpc                     # grpc or http/protobuf
+  otlp_timeout_ms: 5000                   # export request timeout in milliseconds
+  otlp_compression: gzip                  # gzip | none
+  traces_enabled: true                    # enable distributed tracing
+  traces_sampler: parentbased_always_on   # honor the server's sampling decision
+  metrics_enabled: true                   # enable LLM call metrics export
+  metrics_export_interval_ms: 10000       # how often to push metric batches (ms)

{agentirc_cli-8.4.0 → agentirc_cli-8.6.0}/culture/clients/acp/daemon.py

@@ -25,6 +25,7 @@ from culture.clients.acp.irc_transport import IRCTransport
 from culture.clients.acp.message_buffer import MessageBuffer
 from culture.clients.acp.socket_server import SocketServer
 from culture.clients.acp.supervisor import Supervisor, make_sdk_evaluate_fn
+from culture.clients.acp.telemetry import init_harness_telemetry
 from culture.clients.acp.webhook import AlertEvent, WebhookClient
 from culture.pidfile import remove_pid, write_pid
 
@@ -71,6 +72,8 @@ class ACPDaemon:
         self._socket_server: SocketServer | None = None
         self._agent_runner: ACPAgentRunner | None = None
         self._supervisor: Supervisor | None = None
+        self._tracer = None
+        self._metrics = None
 
         # FIFO queue of relay targets — each @mention enqueues a target,
         # each agent response dequeues one, ensuring correct routing even
@@ -134,6 +137,9 @@ class ACPDaemon:
         self._pid_name = f"agent-{self.agent.nick}"
         write_pid(self._pid_name, os.getpid())
 
+        # 0.5. OTEL telemetry (if telemetry.enabled, installs SDK providers; else no-op).
+        self._tracer, self._metrics = init_harness_telemetry(self.config)
+
         # 1. Message buffer
         self._buffer = MessageBuffer(max_per_channel=self.config.buffer_size)
 
@@ -148,6 +154,9 @@ class ACPDaemon:
             on_mention=self._on_mention,
             tags=list(self.agent.tags),
             on_roominvite=self._on_roominvite,
+            tracer=self._tracer,
+            metrics=self._metrics,
+            backend="acp",
         )
         await self._transport.connect()
 
@@ -389,6 +398,8 @@ class ACPDaemon:
             on_exit=self._on_agent_exit,
             on_message=self._on_agent_message,
             on_turn_error=self._on_turn_error,
+            metrics=self._metrics,
+            nick=self.agent.nick,
         )
         # Absorb the system prompt response without relaying to IRC
         self._mention_targets.append(None)

{agentirc_cli-8.4.0 → agentirc_cli-8.6.0}/culture/clients/acp/irc_transport.py

@@ -1,20 +1,38 @@
 from __future__ import annotations
 
 import asyncio
+import contextlib
 import logging
 import re
-from typing import Callable
+from contextlib import AbstractContextManager
+from typing import TYPE_CHECKING, Callable
 
 from culture.aio import maybe_await
 from culture.clients.acp.message_buffer import MessageBuffer
 from culture.constants import SYSTEM_USER_PREFIX
 from culture.protocol.message import Message
+from culture.telemetry.context import (
+    TRACEPARENT_TAG,
+    context_from_traceparent,
+    current_traceparent,
+    extract_traceparent_from_tags,
+)
+
+if TYPE_CHECKING:
+    from opentelemetry.trace import Tracer
+
+    from culture.clients.acp.telemetry import HarnessMetricsRegistry
 
 logger = logging.getLogger(__name__)
 
 
 class IRCTransport:
-    """Async IRC client for the daemon."""
+    """Async IRC client for the daemon.
+
+    Optional kwargs ``tracer``, ``metrics``, and ``backend`` enable OTEL
+    tracing and LLM metrics when an SDK provider is installed. Pass ``None``
+    (the default) for all three to run without instrumentation.
+    """
 
     def __init__(
         self,
@@ -28,6 +46,9 @@ class IRCTransport:
         tags: list[str] | None = None,
         on_roominvite: Callable[[str, str], None] | None = None,
         icon: str | None = None,
+        tracer: Tracer | None = None,
+        metrics: HarnessMetricsRegistry | None = None,
+        backend: str = "acp",
     ):
         self.host = host
         self.port = port
@@ -39,6 +60,10 @@ class IRCTransport:
         self.tags = tags or []
         self.on_roominvite = on_roominvite
         self.icon = icon
+        self._tracer = tracer
+        # accepted for future per-message metrics (e.g. byte counters); unused in v1
+        self._metrics = metrics
+        self._backend = backend
         self.connected = False
         self._reader: asyncio.StreamReader | None = None
         self._writer: asyncio.StreamWriter | None = None
@@ -57,23 +82,46 @@ class IRCTransport:
             "332": self._on_numeric_topic,
         }
 
+    def _span(self, name: str, attrs: dict | None = None) -> AbstractContextManager:
+        """Return a real span context manager when tracing is enabled, else a no-op.
+
+        Keeps the no-tracer fast path clean — all callers write the same
+        ``with self._span(...):`` pattern regardless of whether a tracer is
+        configured.
+
+        Does NOT accept a ``context=`` argument; callers that need a span
+        parented to a remote trace context (e.g. inbound message handling in
+        ``_handle``) call ``self._tracer.start_as_current_span`` directly.
+        """
+        if self._tracer is not None:
+            return self._tracer.start_as_current_span(name, attributes=attrs or {})
+        return contextlib.nullcontext()
+
     async def connect(self) -> None:
         self._should_run = True
         await self._do_connect()
 
     async def _do_connect(self) -> None:
-        try:
-            self._reader, self._writer = await asyncio.open_connection(self.host, self.port)
-        except OSError as exc:
-            raise ConnectionError(
-                f"Cannot connect to IRC server at {self.host}:{self.port} "
-                f"- is the server running?"
-            ) from exc
-        await self._send_raw("CAP REQ :message-tags")
-        await self._send_raw(f"NICK {self.nick}")
-        await self._send_raw(f"USER {self.user} 0 * :{self.user}")
-        await self._send_raw("CAP END")
-        self._read_task = asyncio.create_task(self._read_loop())
+        with self._span(
+            "harness.irc.connect",
+            attrs={
+                "harness.backend": self._backend,
+                "harness.nick": self.nick,
+                "harness.server": f"{self.host}:{self.port}",
+            },
+        ):
+            try:
+                self._reader, self._writer = await asyncio.open_connection(self.host, self.port)
+            except OSError as exc:
+                raise ConnectionError(
+                    f"Cannot connect to IRC server at {self.host}:{self.port} "
+                    f"- is the server running?"
+                ) from exc
+            await self._send_raw("CAP REQ :message-tags")
+            await self._send_raw(f"NICK {self.nick}")
+            await self._send_raw(f"USER {self.user} 0 * :{self.user}")
+            await self._send_raw("CAP END")
+            self._read_task = asyncio.create_task(self._read_loop())
 
     async def disconnect(self) -> None:
         self._should_run = False
@@ -145,12 +193,23 @@ class IRCTransport:
             await self._send_raw(f"TOPIC {channel}")
 
     async def send_raw(self, line: str) -> None:
-        """Send a raw IRC line. Public for commands like HISTORY."""
+        """Send a raw IRC line. Public for commands like HISTORY.
+
+        When a tracer is configured and a span is active, prepends the W3C
+        ``@culture.dev/traceparent=`` IRCv3 tag so all outbound paths — whether
+        called via the internal ``_send_raw`` helper or directly by daemon code
+        — carry trace context consistently.
+        """
+        if self._tracer is not None and not line.startswith("@"):
+            tp = current_traceparent()
+            if tp is not None:
+                line = f"@{TRACEPARENT_TAG}={tp} {line}"
         if self._writer:
             self._writer.write(f"{line}\r\n".encode())
             await self._writer.drain()
 
     async def _send_raw(self, line: str) -> None:
+        """Internal send helper; delegates to send_raw (injection lives there)."""
         await self.send_raw(line)
 
     async def _read_loop(self) -> None:
@@ -193,9 +252,41 @@ class IRCTransport:
                 delay = min(delay * 2, 60)
 
     async def _handle(self, msg: Message) -> None:
-        handler = self._cmd_handlers.get(msg.command)
-        if handler:
-            await maybe_await(handler(msg))
+        # Extract inbound traceparent before opening any span so the new span
+        # can be correctly parented to the remote trace context.
+        result = extract_traceparent_from_tags(msg, peer=None)
+
+        if self._tracer is not None:
+            if result.status == "valid":
+                ctx = context_from_traceparent(result.traceparent)
+                span_cm = self._tracer.start_as_current_span(
+                    "harness.irc.message.handle",
+                    context=ctx,
+                    attributes={
+                        "irc.command": msg.command,
+                        "irc.client.nick": self.nick,
+                        "culture.trace.origin": "remote",
+                    },
+                )
+            else:
+                attrs = {
+                    "irc.command": msg.command,
+                    "irc.client.nick": self.nick,
+                    "culture.trace.origin": ("local" if result.status == "missing" else "remote"),
+                }
+                if result.status in ("malformed", "too_long"):
+                    attrs["culture.trace.dropped_reason"] = result.status
+                span_cm = self._tracer.start_as_current_span(
+                    "harness.irc.message.handle",
+                    attributes=attrs,
+                )
+        else:
+            span_cm = contextlib.nullcontext()
+
+        with span_cm:
+            handler = self._cmd_handlers.get(msg.command)
+            if handler:
+                await maybe_await(handler(msg))
 
     async def _on_ping(self, msg: Message) -> None:
         token = msg.params[0] if msg.params else ""