agentirc-cli 9.3.0__tar.gz → 9.4.0__tar.gz

{agentirc_cli-9.3.0 → agentirc_cli-9.4.0}/CHANGELOG.md

@@ -4,6 +4,66 @@ All notable changes to this project will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/).
 
+## [9.4.0] - 2026-05-01
+
+### Added
+
+- `ServerConfig.from_yaml(path)` — public classmethod on
+  `agentirc.config.ServerConfig` that loads `~/.culture/server.yaml`
+  (or any YAML file). Recognises `server`, `telemetry`, `links`,
+  `webhook_port`, `data_dir`, `system_bots` keys; silently ignores
+  culture-only top-level keys (`supervisor`, `agents`, `buffer_size`,
+  `poll_interval`, `sleep_start`, `sleep_end`, `webhooks`) so the same
+  file can drive both `culture server` and `agentirc` daemons.
+- CLI handlers (`serve`, `start`, `restart`) now overlay CLI flags on
+  top of YAML config. Precedence: explicit CLI flag (sentinel-`None`
+  detection) > YAML key > built-in default. Closes the bootstrap
+  acceptance criterion *"`agentirc start --config <path>` behaves
+  indistinguishably from `culture server start`"*.
+- New runtime dependency: `pyyaml>=6.0`.
+- `docs/api-stability.md` — semver contract for the three public
+  modules (`agentirc.config`, `agentirc.cli`, `agentirc.protocol`),
+  full member list per module, internal-may-refactor list, wire-format
+  quirks paragraph, versioning history.
+- `docs/cli.md` — verb table (8 verbs), per-verb flag reference, exit
+  codes, stderr formatting, YAML/CLI precedence, and the agentirc-vs-
+  culture differences table.
+- `docs/deployment.md` — on-disk footprint, systemd `Type=simple`
+  example unit, container deployment, standalone deployment,
+  multi-host federation, log rotation (logrotate `copytruncate` rule),
+  coexistence with culture, backup recommendations.
+
+### Changed
+
+- `agentirc/cli.py:_add_start_flags` — argparse defaults for `--name`,
+  `--host`, `--port`, `--link`, `--webhook-port`, `--data-dir` are now
+  sentinel `None` rather than concrete values. The user-visible
+  defaults (`0.0.0.0`, `6667`, `7680`, `~/.culture/data`) are still
+  documented in help strings and live on the `ServerConfig` dataclass;
+  the change lets `_resolve_config` distinguish "user-supplied" from
+  "argparse-filled" when overlaying CLI on YAML.
+
+### Removed
+
+- `agentirc/cli.py:_maybe_warn_unused_config` — the
+  *"`--config` was supplied, but YAML config loading is not yet wired
+  (PR-B4)"* warning that PR #4 review (Qodo + Copilot) requested. YAML
+  loading is now wired; the warning was the placeholder for this PR.
+
+### Notes
+
+- Bootstrap is functionally + docs complete as of 9.4.0. Remaining
+  work per the spec status note: acceptance-criteria spot-check (Task
+  14) and release ceremony (Tasks 16–18 — tag, publish, report-back to
+  culture). The cross-repo wire-format fixes (Track A) and steward
+  backport of `pr-sonar.sh` are the only outstanding follow-ups.
+- 13 new tests in `tests/test_config_loader.py` exercise
+  `ServerConfig.from_yaml` (missing/empty/malformed files, unknown-key
+  tolerance, telemetry/links sections) and the `_resolve_config` merge
+  (CLI overrides YAML, YAML used when CLI absent, defaults on both
+  absent, links wholesale-replace). Total suite: 328 tests, ~28s under
+  `pytest -n auto`.
+
 ## [9.3.0] - 2026-05-01
 
 ### Added

{agentirc_cli-9.3.0 → agentirc_cli-9.4.0}/CLAUDE.md

@@ -2,21 +2,26 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-## Current state: bootstrap functionally complete (9.3.0); docs slice (PR-B4) remains
+## Current state: bootstrap functionally + docs complete (9.4.0); release ceremony remains
 
-This repo is the agentirc server-core extraction out of the sibling project [`culture`](https://github.com/OriNachum/culture). As of 9.3.0:
+This repo is the agentirc server-core extraction out of the sibling project [`culture`](https://github.com/OriNachum/culture). As of 9.4.0:
 
 - **Server-core** (`agentirc/{ircd,server_link,channel,events,skill,remote_client,…}.py`, `agentirc/skills/{rooms,threads,history,icon}.py`) — vendored from `culture@df50942` via the `cite-don't-copy` pattern (see `[tool.citation]` in `pyproject.toml`).
-- **Client transport** (`agentirc/client.py`) — vendored from `culture/agentirc/client.py` in PR-B2. The bootstrap spec originally said this would "stay in culture", but the dependency-boundary analysis after PR-B1 showed `client.py` only imports already-vendored support modules plus opentelemetry. Without it, `agentirc/ircd.py:580`'s runtime `from agentirc.client import Client` raised `ImportError` on the first TCP IRC connection.
-- **Public CLI** (`agentirc/cli.py`) — real verb dispatch extracted from `culture/cli/server.py`. Verbs: `serve` (foreground, no PID; for systemd `Type=simple` and containers), `start`/`stop`/`status` (lifecycle), `restart`, `link` (peer-spec validator), `logs` (cat / tail of `~/.culture/logs/server-<name>.log`), `version`.
+- **Client transport** (`agentirc/client.py`) — vendored from `culture/agentirc/client.py` in PR-B2.
+- **Public CLI** (`agentirc/cli.py`) — real verb dispatch extracted from `culture/cli/server.py`. Verbs: `serve` (foreground, no PID; for systemd `Type=simple` and containers), `start`/`stop`/`status` (lifecycle), `restart`, `link` (peer-spec validator), `logs` (cat / tail of `~/.culture/logs/server-<name>.log`), `version`. Since 9.4.0, `serve`/`start`/`restart` overlay CLI flags on `--config` YAML (precedence: CLI > YAML > built-in default).
+- **Public config** (`agentirc/config.py`) — `ServerConfig`, `LinkConfig`, `TelemetryConfig` dataclasses plus the `ServerConfig.from_yaml(path)` classmethod (added 9.4.0). Recognises `server`/`telemetry`/`links`/`webhook_port`/`data_dir`/`system_bots` keys; silently ignores culture-only keys (`supervisor`, `agents`, `buffer_size`, etc.) so the same `~/.culture/server.yaml` can drive both daemons.
 - **Public protocol** (`agentirc/protocol.py`) — verb name constants, numerics, IRCv3 tag names. Wire-format quirks (`ROOMETAEND`, `ROOMETASET` typos, `ERR_NOSUCHCHANNEL` semantic misuse, `STHREAD` verb collapse) preserved verbatim — they need coordinated cross-repo bumps to fix.
-- **Test suite** (PR-B3, 9.3.0) — 36 tests vendored from `culture@df50942` (~6.5kloc), 315 tests run under `pytest -n auto` in ~29s on default workers. Three telemetry tests (`test_bot_event_dispatch_span`, `test_bot_run_span`, `test_metrics_bots`) and `test_welcome_bot` stay in culture because they depend on the real `BotManager`. `tests/conftest.py` was adapted to drop bot-loader sandboxing and the `server_with_bot` / `server_with_bots` fixtures.
-- **Internal support** (`agentirc/_internal/`) — `aio`, `constants`, `protocol/`, `telemetry/`, `virtual_client`, `pidfile` (PR-B2), `cli_shared/` (PR-B2), `bots/` stubs.
+- **Test suite** (PR-B3, 9.3.0; +13 in 9.4.0) — 36 tests vendored from `culture@df50942` (~6.5kloc) plus 13 new agentirc-native tests in `tests/test_config_loader.py`. 328 tests run under `pytest -n auto` in ~28s on default workers. Three telemetry tests (`test_bot_event_dispatch_span`, `test_bot_run_span`, `test_metrics_bots`) and `test_welcome_bot` stay in culture because they depend on the real `BotManager`.
+- **Internal support** (`agentirc/_internal/`) — `aio`, `constants`, `protocol/`, `telemetry/`, `virtual_client`, `pidfile`, `cli_shared/`, `bots/` stubs.
+- **Bootstrap docs** (PR-B4, 9.4.0) — `docs/api-stability.md` (3 public modules + semver contract), `docs/cli.md` (verb table, flag reference, exit codes, YAML/CLI precedence, agentirc-vs-culture diff table), `docs/deployment.md` (on-disk footprint, systemd `Type=simple` example, container deployment, multi-host federation, log rotation, coexistence with culture, backup).
 
-End-to-end verified: `agentirc start --port <p>` boots a real IRCd, TCP NICK/USER handshake returns `001 RPL_WELCOME`, `agentirc stop` shuts cleanly. `agentirc serve` is byte-indistinguishable from `culture server start` for the lifecycle contract culture's shim relies on.
+End-to-end verified: `agentirc start --port <p>` boots a real IRCd, TCP NICK/USER handshake returns `001 RPL_WELCOME`, `agentirc stop` shuts cleanly. `agentirc serve --config server.yaml --port 9999` correctly overlays CLI flag on YAML.
 
 What is **not** done yet:
-- **Bootstrap docs (PR-B4)** — `docs/api-stability.md`, `docs/cli.md`, `docs/deployment.md`. Pure prose; not gating on culture's cutover (the public API surface is already importable; PR-B4 just documents the contract).
+- **Acceptance-criteria spot-check** (Task 14 in the bootstrap spec) — read-only audit to confirm every bullet in §"Acceptance criteria" is ✅ before tagging.
+- **Release ceremony** (Tasks 16–18) — tag `v9.4.0`, the existing `publish.yml` CI pushes to PyPI on push to `main`, then report version + source SHA back so culture's cutover PR can pin against it.
+- **Cross-repo wire-format fixes (Track A)** — `ROOMETAEND`/`ROOMETASET` typos, `ERR_NOSUCHCHANNEL` overload, `STHREAD` collapse. Each requires culture-side change first then agentirc bump.
+- **Steward backport** — port the 9.3.0 `pr-sonar.sh` + `workflow.sh` SonarCloud wiring back to the steward skills repo.
 
 Read the bootstrap spec at `docs/superpowers/specs/2026-04-30-bootstrap-design.md` for the full plan; it is the operative source of truth and is intentionally self-contained. The culture-side counterpart spec is at `../culture/docs/superpowers/specs/2026-04-30-agentirc-extraction-design.md` — not normally needed, but explains *why* if a decision looks arbitrary.
 

{agentirc_cli-9.3.0 → agentirc_cli-9.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentirc-cli
-Version: 9.3.0
+Version: 9.4.0
 Summary: Agent-friendly IRCd: server core for AI agent meshes
 Project-URL: Homepage, https://github.com/OriNachum/agentirc
 Project-URL: Issues, https://github.com/OriNachum/agentirc/issues
@@ -40,6 +40,7 @@ Requires-Python: >=3.11
 Requires-Dist: opentelemetry-api>=1.22
 Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.22
 Requires-Dist: opentelemetry-sdk>=1.22
+Requires-Dist: pyyaml>=6.0
 Provides-Extra: dev
 Requires-Dist: bandit; extra == 'dev'
 Requires-Dist: black; extra == 'dev'

{agentirc_cli-9.3.0 → agentirc_cli-9.4.0}/agentirc/cli.py

@@ -54,6 +54,8 @@ import time
 from pathlib import Path
 from typing import Sequence
 
+import yaml
+
 from agentirc import __version__
 from agentirc._internal.cli_shared.constants import (
     DEFAULT_CONFIG,
@@ -92,23 +94,116 @@ def _safe_log_name(name: str) -> str:
     return _safe_name(name)
 
 
-def _maybe_warn_unused_config(args: argparse.Namespace) -> None:
-    """Emit a warning when ``--config`` is set to something that won't be loaded.
+def _load_raw_yaml(cfg_path: str) -> dict:
+    """Read ``cfg_path`` as YAML and return the top-level mapping.
+
+    Missing files return ``{}``; malformed YAML raises ``yaml.YAMLError``
+    from the underlying loader. Empty files return ``{}``. A YAML
+    document whose root is a list/scalar (valid YAML but wrong shape)
+    raises ``yaml.YAMLError`` with a clear message rather than letting
+    a downstream ``AttributeError`` leak through.
+    """
+    p = Path(cfg_path).expanduser()
+    if not p.exists():
+        return {}
+    with p.open() as f:
+        raw = yaml.safe_load(f)
+    if raw is None:
+        return {}
+    if not isinstance(raw, dict):
+        raise yaml.YAMLError(
+            f"agentirc config {cfg_path!r}: root must be a mapping, "
+            f"got {type(raw).__name__}"
+        )
+    return raw
+
+
+def _build_telemetry(yaml_telemetry: dict) -> "TelemetryConfig":  # noqa: F821
+    """Build a TelemetryConfig from a YAML ``telemetry:`` block.
 
-    ``agentirc`` does not yet wire ``~/.culture/server.yaml`` into the
-    IRCd construction path — ``ServerConfig`` is built purely from CLI
-    flags. Silently ignoring a non-default ``--config`` was flagged as
-    confusing in PR #4 review (Qodo + Copilot). Until YAML loading
-    lands, warn explicitly so users notice.
+    Drops keys not declared on the dataclass — culture extending
+    TelemetryConfig in the future shouldn't crash agentirc on read.
+    """
+    from agentirc.config import TelemetryConfig
+
+    if not yaml_telemetry:
+        return TelemetryConfig()
+    known = {f.name for f in TelemetryConfig.__dataclass_fields__.values()}
+    tcfg = {k: v for k, v in yaml_telemetry.items() if k in known}
+    return TelemetryConfig(**tcfg)
+
+
+def _resolve_links(cli_links, yaml_links: list) -> list:
+    """Pick CLI links if any, else build from YAML, else empty.
+
+    CLI links replace YAML wholesale — there is no merge.
+    """
+    from agentirc.config import LinkConfig
+
+    if cli_links:
+        return list(cli_links)
+    if yaml_links:
+        return [LinkConfig(**entry) for entry in yaml_links]
+    return []
+
+
+def _resolve_config(args: argparse.Namespace) -> "ServerConfig":  # noqa: F821 (forward ref)
+    """Build a ServerConfig from ``--config`` YAML, overlaid with CLI flags.
+
+    Precedence (highest first): explicit CLI flag (``not None``) >
+    matching YAML key > built-in default. Loads raw YAML so we can
+    distinguish "key absent from YAML" from "key present but matching
+    the dataclass default" — needed to let downstream
+    ``_resolve_server_name`` handle the "no name anywhere" case via
+    the default-server file rather than the ``ServerConfig`` dataclass
+    default ``"culture"``.
+
+    Mutates ``args`` in place so ``args.host`` / ``args.port`` /
+    ``args.name`` / ``args.webhook_port`` / ``args.data_dir`` /
+    ``args.link`` reflect the resolved values for the daemonize / log
+    / status code that reads them directly. ``args.name`` is left
+    ``None`` if neither CLI nor YAML supplied a name; the handler
+    then calls ``_resolve_server_name`` to pick up the default-server
+    file or the ``agentirc`` fallback.
     """
-    cfg = getattr(args, "config", None)
-    if cfg and cfg != DEFAULT_CONFIG:
-        print(
-            f"agentirc: warning: --config {cfg!r} was supplied, but YAML config "
-            "loading is not yet wired (PR-B4). Server settings will come from "
-            "CLI flags (--host/--port/--link/--data-dir) only.",
-            file=sys.stderr,
+    from agentirc.config import ServerConfig
+
+    raw = _load_raw_yaml(getattr(args, "config", None) or DEFAULT_CONFIG)
+    yaml_server = raw.get("server") or {}
+
+    def _pick(cli_value, yaml_value, default):
+        if cli_value is not None:
+            return cli_value
+        return yaml_value if yaml_value is not None else default
+
+    name = _pick(args.name, yaml_server.get("name"), None)
+    host = _pick(args.host, yaml_server.get("host"), "0.0.0.0")
+    port = _pick(args.port, yaml_server.get("port"), 6667)
+    webhook_port = _pick(args.webhook_port, raw.get("webhook_port"), 7680)
+    data_dir = os.path.expanduser(
+        _pick(
+            args.data_dir, raw.get("data_dir"), os.path.expanduser("~/.culture/data")
         )
+    )
+
+    cfg = ServerConfig(
+        name=name or "agentirc",
+        host=host,
+        port=port,
+        webhook_port=webhook_port,
+        data_dir=data_dir,
+        links=_resolve_links(getattr(args, "link", None), raw.get("links") or []),
+        system_bots=raw.get("system_bots") or {},
+        telemetry=_build_telemetry(raw.get("telemetry") or {}),
+    )
+
+    args.name = name  # may be None — handler resolves via default-server file
+    args.host = cfg.host
+    args.port = cfg.port
+    args.webhook_port = cfg.webhook_port
+    args.data_dir = cfg.data_dir
+    args.link = cfg.links
+    return cfg
 
 
 # ---------------------------------------------------------------------------
@@ -117,21 +212,34 @@ def _maybe_warn_unused_config(args: argparse.Namespace) -> None:
 
 
 def _add_start_flags(parser: argparse.ArgumentParser) -> None:
-    """Attach the lifecycle flag set used by ``serve``/``start``/``restart``."""
+    """Attach the lifecycle flag set used by ``serve``/``start``/``restart``.
+
+    All flags default to ``None`` (the *sentinel* default) rather than
+    their concrete values. ``_resolve_config`` distinguishes "user
+    supplied this flag" from "argparse filled in the default" and
+    overlays CLI values on top of YAML; sentinel defaults are required
+    for that distinction. The user-visible defaults — ``0.0.0.0``,
+    ``6667``, ``7680``, ``~/.culture/data`` — are documented in the
+    help strings and live on the ``ServerConfig`` dataclass.
+    """
     parser.add_argument("--name", default=None, help=_SERVER_NAME_HELP)
-    parser.add_argument("--host", default="0.0.0.0", help="Listen address")
-    parser.add_argument("--port", type=int, default=6667, help="Listen port")
+    parser.add_argument(
+        "--host", default=None, help="Listen address (default: 0.0.0.0)"
+    )
+    parser.add_argument(
+        "--port", type=int, default=None, help="Listen port (default: 6667)"
+    )
     parser.add_argument(
         "--link",
         type=parse_link,
         action="append",
-        default=[],
+        default=None,
         help="Link to peer: name:host:port:password[:trust]",
     )
     parser.add_argument(
         "--webhook-port",
         type=int,
-        default=7680,
+        default=None,
         help=(
             "HTTP port for bot webhooks (default: 7680; "
             "inert in agentirc until a bot harness is wired in)"
@@ -139,7 +247,7 @@ def _add_start_flags(parser: argparse.ArgumentParser) -> None:
     )
     parser.add_argument(
         "--data-dir",
-        default=os.path.expanduser("~/.culture/data"),
+        default=None,
         help="Data directory for persistent storage (default: ~/.culture/data)",
     )
     parser.add_argument("--config", default=DEFAULT_CONFIG, help=_CONFIG_HELP)
@@ -309,29 +417,21 @@ def _force_kill(pid: int, name: str) -> None:
 # ---------------------------------------------------------------------------
 
 
-async def _run_server(
-    name: str,
-    host: str,
-    port: int,
-    links: list | None = None,
-    webhook_port: int = 7680,
-    data_dir: str = "",
-) -> None:
-    """Run the IRC server (called in the daemon child process)."""
-    from agentirc.config import ServerConfig
+async def _run_server(config: "ServerConfig") -> None:  # noqa: F821 (forward ref)
+    """Run the IRC server (called in the daemon child process).
+
+    Takes a fully-merged ``ServerConfig`` so YAML-supplied telemetry,
+    system_bots, and any future dataclass fields reach the IRCd.
+    Caller (``_run_foreground`` / ``_daemonize_server``) is responsible
+    for resolving CLI/YAML precedence via ``_resolve_config``.
+    """
     from agentirc.ircd import IRCd
 
-    config = ServerConfig(
-        name=name,
-        host=host,
-        port=port,
-        webhook_port=webhook_port,
-        links=links or [],
-        data_dir=data_dir,
-    )
     ircd = IRCd(config)
     await ircd.start()
-    logger.info("Server '%s' listening on %s:%d", name, host, port)
+    logger.info(
+        "Server '%s' listening on %s:%d", config.name, config.host, config.port
+    )
 
     for lc in config.links:
         try:
@@ -356,41 +456,41 @@ async def _run_server(
             signal.signal(sig, lambda *_: stop_event.set())
 
     await stop_event.wait()
-    logger.info("Server '%s' shutting down", name)
+    logger.info("Server '%s' shutting down", config.name)
     await ircd.stop()
 
 
-def _run_foreground(args: argparse.Namespace, pid_name: str, links: list) -> None:
+def _run_foreground(pid_name: str, cfg: "ServerConfig") -> None:  # noqa: F821
     """Run the server in the foreground (blocking).
 
     A PID file is written when *pid_name* is non-empty (``start
     --foreground``). The agentirc-only ``serve`` verb passes ``""`` to
     skip PID writes — useful for systemd ``Type=simple`` and containers
-    that own process supervision.
+    that own process supervision. All runtime values come from *cfg*;
+    ``args`` is no longer needed since the verb-handler resolves the
+    YAML+CLI merge before calling here.
     """
     if pid_name:
         write_pid(pid_name, os.getpid())
-        if args.port:
+        if cfg.port:
             # Mirror daemonize: write the port file so `agentirc status`
             # can report `(PID N, port P)` for foreground-managed runs.
-            write_port(pid_name, args.port)
+            write_port(pid_name, cfg.port)
     os.makedirs(LOG_DIR, exist_ok=True)
-    print(f"Server '{args.name}' starting in foreground (PID {os.getpid()})")
-    print(f"  Listening on {args.host}:{args.port}")
-    print(f"  Webhook port: {args.webhook_port}")
+    print(f"Server '{cfg.name}' starting in foreground (PID {os.getpid()})")
+    print(f"  Listening on {cfg.host}:{cfg.port}")
+    print(f"  Webhook port: {cfg.webhook_port}")
     if pid_name:
-        _maybe_set_default_server(args.name)
+        _maybe_set_default_server(cfg.name)
     try:
-        asyncio.run(
-            _run_server(args.name, args.host, args.port, links, args.webhook_port, args.data_dir)
-        )
+        asyncio.run(_run_server(cfg))
     finally:
         if pid_name:
             remove_pid(pid_name)
             remove_port(pid_name)
 
 
-def _daemonize_server(args: argparse.Namespace, pid_name: str, links: list) -> None:
+def _daemonize_server(args: argparse.Namespace, pid_name: str, cfg: "ServerConfig") -> None:  # noqa: F821
     """Fork and set up the daemon child process for the server."""
     if sys.platform == "win32":
         print("Daemon mode not supported on Windows. Use --foreground.", file=sys.stderr)
@@ -404,7 +504,7 @@ def _daemonize_server(args: argparse.Namespace, pid_name: str, links: list) -> N
     os.setsid()
 
     os.makedirs(LOG_DIR, exist_ok=True)
-    log_path = os.path.join(LOG_DIR, f"server-{_safe_log_name(args.name)}.log")
+    log_path = os.path.join(LOG_DIR, f"server-{_safe_log_name(cfg.name)}.log")
     log_fd = os.open(log_path, os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o644)
     os.dup2(log_fd, 1)
     os.dup2(log_fd, 2)
@@ -426,8 +526,8 @@ def _daemonize_server(args: argparse.Namespace, pid_name: str, links: list) -> N
     )
 
     write_pid(pid_name, os.getpid())
-    if args.port:
-        write_port(pid_name, args.port)
+    if cfg.port:
+        write_port(pid_name, cfg.port)
 
     # PR #4 review (Qodo): the previous version called os._exit(0)
     # unconditionally in the finally block, masking crashes inside
@@ -436,16 +536,14 @@ def _daemonize_server(args: argparse.Namespace, pid_name: str, links: list) -> N
     # and propagate it.
     rc = 0
     try:
-        asyncio.run(
-            _run_server(args.name, args.host, args.port, links, args.webhook_port, args.data_dir)
-        )
+        asyncio.run(_run_server(cfg))
     except Exception:
         # Catch ordinary failures so the daemon child can record them and
         # exit non-zero. SystemExit / KeyboardInterrupt / GeneratorExit
         # deliberately propagate (the asyncio signal handlers translate
         # SIGINT/SIGTERM into a clean stop_event.set, so we never reach
         # this except via an actual fault).
-        logger.exception("Daemon for server '%s' crashed", args.name)
+        logger.exception("Daemon for server '%s' crashed", cfg.name)
         rc = 1
     finally:
         remove_pid(pid_name)
@@ -460,25 +558,26 @@ def _daemonize_server(args: argparse.Namespace, pid_name: str, links: list) -> N
 
 def _server_serve(args: argparse.Namespace) -> None:
     """``agentirc serve`` — run the IRCd in the foreground without writing a PID file."""
-    args.name = _resolve_server_name(args)
-    _maybe_warn_unused_config(args)
-    links = list(getattr(args, "link", []) or [])
-    _run_foreground(args, pid_name="", links=links)
+    cfg = _resolve_config(args)
+    if args.name is None:
+        args.name = _resolve_server_name(args)
+        cfg.name = args.name
+    _run_foreground(pid_name="", cfg=cfg)
 
 
 def _server_start(args: argparse.Namespace) -> None:
     """``agentirc start`` — daemonize (or run foreground if ``--foreground``)."""
-    args.name = _resolve_server_name(args)
-    _maybe_warn_unused_config(args)
+    cfg = _resolve_config(args)
+    if args.name is None:
+        args.name = _resolve_server_name(args)
+        cfg.name = args.name
     pid_name = f"server-{args.name}"
     _check_already_running(pid_name, args.name)
 
-    links = list(getattr(args, "link", []) or [])
-
     if getattr(args, "foreground", False):
-        _run_foreground(args, pid_name, links)
+        _run_foreground(pid_name, cfg)
     else:
-        _daemonize_server(args, pid_name, links)
+        _daemonize_server(args, pid_name, cfg)
 
 
 def _server_stop(args: argparse.Namespace) -> int:
@@ -522,8 +621,16 @@ def _server_stop(args: argparse.Namespace) -> int:
 
 
 def _server_restart(args: argparse.Namespace) -> int:
-    """``agentirc restart`` — stop (best-effort) then start with the same args."""
-    args.name = _resolve_server_name(args)
+    """``agentirc restart`` — stop (best-effort) then start with the same args.
+
+    Resolves the YAML+CLI merge once up-front so ``server.name`` from
+    ``--config`` is honoured for both the stop half and the subsequent
+    ``_server_start`` call. Without the pre-resolution, the default-
+    server file would shadow ``server.name``.
+    """
+    _resolve_config(args)
+    if args.name is None:
+        args.name = _resolve_server_name(args)
     pid_name = f"server-{args.name}"
     pid = read_pid(pid_name)
     if pid and is_process_alive(pid):

agentirc_cli-9.4.0/agentirc/config.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+@dataclass
+class LinkConfig:
+    """Configuration for a server-to-server link."""
+
+    name: str
+    host: str
+    port: int
+    password: str
+    trust: str = "full"  # "full" or "restricted"
+
+
+@dataclass
+class TelemetryConfig:
+    """OpenTelemetry settings. Mirrors server.yaml `telemetry:` block."""
+
+    enabled: bool = False
+    service_name: str = "culture.agentirc"
+    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"  # gzip | none
+    traces_enabled: bool = True
+    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
+class ServerConfig:
+    """Configuration for a culture server instance."""
+
+    name: str = "culture"
+    host: str = "0.0.0.0"
+    port: int = 6667
+    webhook_port: int = 7680
+    data_dir: str = ""
+    links: list[LinkConfig] = field(default_factory=list)
+    system_bots: dict = field(default_factory=dict)
+    telemetry: TelemetryConfig = field(default_factory=TelemetryConfig)
+
+    @classmethod
+    def from_yaml(cls, path: str | Path) -> "ServerConfig":
+        """Load a ServerConfig from a YAML file.
+
+        Recognises top-level ``server`` (host/port/name), ``telemetry``,
+        ``links``, ``webhook_port``, ``data_dir``, and ``system_bots``.
+        Unknown top-level keys (``supervisor``, ``agents``, ``buffer_size``,
+        ``poll_interval``, ``sleep_start``, ``sleep_end``) are silently
+        ignored — those belong to culture's broader process supervisor,
+        and agentirc must coexist with culture using the same
+        ``~/.culture/server.yaml`` file. Unknown keys *inside* the
+        ``server:`` block are also tolerated for the same reason
+        (culture's ``ServerConnConfig`` carries ``archived``,
+        ``archived_at``, ``archived_reason`` that agentirc has no use
+        for).
+
+        A missing path returns the dataclass defaults rather than
+        raising — callers (CLI handlers) treat the file as optional.
+        Malformed YAML raises ``yaml.YAMLError`` from the underlying
+        loader; we deliberately do not catch it so users see the parse
+        error.
+        """
+        p = Path(path).expanduser()
+        if not p.exists():
+            return cls()
+        raw = _load_root_mapping(p)
+        return cls(**_yaml_kwargs(raw))
+
+
+def _load_root_mapping(p: Path) -> dict[str, Any]:
+    """Load YAML at *p* and require the root to be a mapping."""
+    with p.open() as f:
+        loaded = yaml.safe_load(f)
+    if loaded is None:
+        return {}
+    if not isinstance(loaded, dict):
+        raise yaml.YAMLError(
+            f"agentirc config {str(p)!r}: root must be a mapping, "
+            f"got {type(loaded).__name__}"
+        )
+    return loaded
+
+
+def _yaml_kwargs(raw: dict[str, Any]) -> dict[str, Any]:
+    """Project a raw YAML mapping onto ServerConfig constructor kwargs."""
+    server_section = raw.get("server") or {}
+    kwargs: dict[str, Any] = {}
+    for key in ("name", "host", "port"):
+        if key in server_section:
+            kwargs[key] = server_section[key]
+    for key in ("webhook_port", "data_dir"):
+        if key in raw:
+            kwargs[key] = raw[key]
+    links_section = raw.get("links") or []
+    if links_section:
+        kwargs["links"] = [LinkConfig(**entry) for entry in links_section]
+    telemetry_section = raw.get("telemetry") or {}
+    if telemetry_section:
+        kwargs["telemetry"] = _build_telemetry(telemetry_section)
+    system_bots = raw.get("system_bots") or {}
+    if system_bots:
+        kwargs["system_bots"] = system_bots
+    return kwargs
+
+
+def _build_telemetry(yaml_telemetry: dict) -> TelemetryConfig:
+    """Build a TelemetryConfig, dropping keys not on the dataclass."""
+    known = {f.name for f in TelemetryConfig.__dataclass_fields__.values()}
+    tcfg = {k: v for k, v in yaml_telemetry.items() if k in known}
+    return TelemetryConfig(**tcfg)