agentirc-cli 9.1.0__tar.gz → 9.2.0__tar.gz

agentirc_cli-9.2.0/CHANGELOG.md

@@ -0,0 +1,118 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/).
+
+## [9.2.0] - 2026-05-01
+
+### Added
+
+- `agentirc/protocol.py` — public, semver-tracked module consolidating
+  IRC verb names, numeric reply codes (re-exported from
+  `_internal.protocol.replies`), and IRCv3 / agentirc tag names. Wire-
+  format quirks (`ROOMETAEND`, `ROOMETASET` typos; `ERR_NOSUCHCHANNEL`
+  semantic misuse; `STHREAD` verb collapse) are preserved verbatim with
+  explanatory comments — they require coordinated cross-repo bumps to
+  fix.
+- `agentirc/client.py` — IRC client transport vendored from
+  `culture/agentirc/client.py` at SHA `df50942`. Body unchanged; only
+  imports rewritten. The bootstrap spec originally said this would
+  "stay in culture" but its dependency surface (already-vendored
+  `_internal` support modules + opentelemetry) made vendoring the
+  cleaner path. Without it, `agentirc/ircd.py:580`'s runtime
+  `from agentirc.client import Client` raised `ImportError` on the
+  first TCP IRC connection.
+- Real `agentirc/cli.py` — verb dispatch extracted from
+  `culture/cli/server.py`. New verbs: `serve` (foreground, no PID;
+  for systemd `Type=simple` and containers), `restart`, `link`
+  (peer-spec validator), `logs` (cat / tail of `~/.culture/logs/server-
+  <name>.log`). Existing verbs `start`/`stop`/`status` reuse culture's
+  proven daemonize / `_wait_for_port` / `_wait_for_graceful_stop` /
+  `_force_kill` helpers.
+- Internal support modules:
+  - `agentirc/_internal/pidfile.py` — PID/port file management.
+    `is_managed_process()` recognizes both `culture` and
+    `agentirc`/`agentirc-cli` argv tokens; `is_culture_process` is
+    preserved as a thin alias.
+  - `agentirc/_internal/cli_shared/{constants,mesh}.py` — minimal
+    subset of `culture/cli/shared`. Keeps `DEFAULT_CONFIG`, `LOG_DIR`,
+    `culture_runtime_dir()`, `parse_link()`. Drops everything that
+    touched `culture.bots.config`, `culture.credentials`,
+    `culture.mesh_config`.
+- Citations recorded in `[tool.citation]`: `culture-pidfile`,
+  `culture-cli-shared`, `culture-client`, `culture-cli-server`.
+
+### Changed
+
+- Default server name changed from `culture` to `agentirc` in
+  `agentirc.cli`. PID/port files at `~/.culture/pids/server-<name>.{pid,
+  port}` keep their existing layout per the "Defaults preserve culture
+  continuity" rule, but the default fallback name no longer collides
+  with culture's daemon when both run on the same host.
+- Dropped culture-only verbs (`default`, `rename`, `archive`,
+  `unarchive`) from agentirc's CLI surface — they manage culture's
+  agent manifest, which agentirc does not own.
+- Dropped `--mesh-config` from `agentirc start` — depends on
+  `culture.credentials` / `culture.mesh_config` (out of scope).
+
+### Notes
+
+- End-to-end smoke verified: `agentirc start --port 16667` boots,
+  TCP NICK/USER handshake returns `001 RPL_WELCOME` from a real
+  `IRCd`, `agentirc stop` shuts cleanly. `agentirc serve` is now
+  byte-indistinguishable from `culture server start` for the lifecycle
+  contract culture's shim relies on.
+- Test suite migration (PR-B3) is the only remaining bootstrap slice.
+
+## [9.1.0] - 2026-04-30
+
+### Added
+
+- Server-core vendored from `culture` at SHA `df50942`. The `agentirc`
+  package now contains the IRCd (`ircd.py`), server-to-server linking
+  (`server_link.py`), channel/event/store/skill modules, `remote_client.py`
+  (peer-server ghost client), and the four built-in skills
+  (`skills/{rooms,threads,history,icon}.py`).
+- Internal vendored support modules under `agentirc/_internal/`:
+  - `aio` (`maybe_await`)
+  - `constants` (system user/channel constants)
+  - `protocol/` (IRC `Message` and numeric `replies`)
+  - `telemetry/` (OpenTelemetry audit/tracing/metrics — full subpackage)
+  - `virtual_client` (`VirtualClient` for in-process bot integration)
+  - `bots/{bot_manager,http_listener}` (no-op stubs; culture replaces
+    these at runtime when wrapping an `IRCd`)
+- `[tool.citation]` block in `pyproject.toml` enumerating every vendored
+  file with a quote/paraphrase/synthesize status, source URL, and
+  sha256, validated by `cite check`.
+- Runtime dependencies: `opentelemetry-api`, `opentelemetry-sdk`,
+  `opentelemetry-exporter-otlp-proto-grpc` (all `>=1.22`).
+- Dev dependency: `citation-cli` (provides the `cite` console script).
+
+### Changed
+
+- Bootstrap spec deviation: `remote_client.py` was originally listed as
+  "do not copy" but turned out to be server-side (used by `server_link`
+  and `virtual_client` for peer-server users in channel member lists).
+  Vendored as public `agentirc/remote_client.py`. See commit `8b4a6d8`.
+
+### Notes
+
+- `agentirc/cli.py` still ships only `version`; the `serve|start|stop|
+  restart|status|link|logs` lifecycle verbs remain stubs. The real CLI
+  is the next slice (PR-B2).
+- Tests are not migrated yet (PR-B3).
+
+## [9.0.0] - 2026-04-30
+
+### Added
+
+- Initial bootstrap of `agentirc-cli` as an installable Python package.
+- Skeleton `agentirc/{__init__,__main__,cli}.py` with `version` verb
+  wired up and lifecycle verbs (`serve|start|stop|restart|status|link|
+  logs`) as stubs.
+- Console scripts: both `agentirc` and `agentirc-cli` map to
+  `agentirc.cli:main`.
+- Major version starts at `9.0.0` to leapfrog the
+  `agentirc-cli==8.7.X.devN` squat that culture previously published to
+  TestPyPI, so dev releases sort as the actual "Latest".

{agentirc_cli-9.1.0 → agentirc_cli-9.2.0}/CLAUDE.md

@@ -2,14 +2,20 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-## Current state: server-core landed (9.1.0), CLI stubbed (PR-B2 next)
+## Current state: server-core + real CLI + protocol module landed (9.2.0)
 
-This repo is the agentirc server-core extraction out of the sibling project [`culture`](https://github.com/OriNachum/culture). As of 9.1.0, the IRCd server core is in place — `agentirc/{ircd,server_link,channel,events,skill,remote_client,…}.py` and `agentirc/skills/{rooms,threads,history,icon}.py` are all present, copied from `culture@df50942` via the `cite-don't-copy` pattern (see `[tool.citation]` in `pyproject.toml`). Internal vendored support modules live under `agentirc/_internal/` (`aio`, `constants`, `protocol/`, `telemetry/`, `virtual_client`, `bots/` stubs).
+This repo is the agentirc server-core extraction out of the sibling project [`culture`](https://github.com/OriNachum/culture). As of 9.2.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`.
+- **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.
+- **Internal support** (`agentirc/_internal/`) — `aio`, `constants`, `protocol/`, `telemetry/`, `virtual_client`, `pidfile` (PR-B2), `cli_shared/` (PR-B2), `bots/` stubs.
+
+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.
 
 What is **not** done yet:
-- **`agentirc/cli.py`** is still the Shape A stub. All lifecycle verbs (`serve`, `start`, `stop`, `restart`, `status`, `link`, `logs`) print "not yet implemented" and exit 1. The real CLI lands in PR-B2 (extracted from `../culture/culture/cli/server.py`).
-- **`agentirc/protocol.py`** does not exist yet (PR-B2 also).
-- **Test suite migration** is PR-B3.
+- **Test suite migration** is PR-B3 — only remaining bootstrap slice.
 
 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.
 
@@ -31,11 +37,12 @@ There are three different names in play. Don't conflate them:
 
 ## What lives here vs. in culture
 
-- **Server-core (here):** `ircd.py`, `server_link.py`, `channel.py`, `config.py`, `events.py`, the stores (`room_store`, `thread_store`, `history_store`), `rooms_util.py`, `skill.py`, `remote_client.py`, and the `skills/` directory (`rooms`, `threads`, `history`, `icon`). Vendored support under `agentirc/_internal/` (`aio`, `constants`, `protocol/`, `telemetry/`, `virtual_client`, `bots/` stubs).
-- **Stays in culture:** `client.py` (full IRC client transport, used by bots) and any test that exercises the IRC *client transport* rather than the server. Note: the bootstrap spec originally also listed `remote_client.py` as "stays in culture", but it turned out to be a 43-line server-side ghost-client stub used by `server_link.py`; it's vendored here. See PR-B1 commit history.
-- **Newly created here:** `agentirc/cli.py` (today: skeleton stub from PR Shape A; PR-B2 extracts the real one from `../culture/culture/cli/server.py`), `agentirc/__main__.py`. **Coming in PR-B2:** `agentirc/protocol.py` (consolidates verb names, numerics, and extension tag names currently inlined as string literals in `ircd.py` / `client.py`).
+- **Server-core (here):** `ircd.py`, `server_link.py`, `channel.py`, `config.py`, `events.py`, the stores (`room_store`, `thread_store`, `history_store`), `rooms_util.py`, `skill.py`, `remote_client.py`, and the `skills/` directory (`rooms`, `threads`, `history`, `icon`).
+- **Client transport (here, since 9.2.0):** `client.py` — vendored in PR-B2. Pre-9.2 the bootstrap spec said "stays in culture"; that assumption broke down once we found `client.py` only imports already-vendored modules and that the IRCd needs it at runtime to accept TCP clients.
+- **Internal support (here):** `agentirc/_internal/{aio, constants, protocol/, telemetry/, virtual_client, pidfile, cli_shared/}` plus `bots/` no-op stubs (the real `culture.bots.*` depends on backend SDKs forbidden by agentirc's dependency boundary; culture replaces the stubs at runtime when wrapping an IRCd).
+- **Stays in culture:** `culture.bots.*` (the real bot manager), `culture.config` / `culture.bots.config` (agent-manifest concerns), `culture.cli.shared.{ipc,display,formatting,process}` (CLI ergonomics agentirc doesn't need), `culture.credentials` / `culture.mesh_config` (OS-keyring + mesh.yaml).
 
-When migrating tests, the rule is: pure server tests come here, transport tests stay in culture, mixed tests stay in culture and get rewritten to drive `agentirc serve` as a subprocess fixture rather than importing `IRCd` directly. When unsure, **prefer copying the test here** — this repo owns the IRCd.
+When migrating tests, the rule is: pure server tests come here, transport tests **also** come here now that we own `client.py`, mixed tests stay in culture and get rewritten to drive `agentirc serve` as a subprocess fixture rather than importing `IRCd` directly. When unsure, **prefer copying the test here** — this repo owns the IRCd and the client transport.
 
 ## Public API contract (semver-tracked)
 
@@ -49,6 +56,11 @@ Only three modules are public. Everything else is internal and may be refactored
 
 `agentirc.cli.dispatch(argv)` is the function `culture`'s `culture server` shim calls — it must accept the exact same flag set, exit codes, and stderr formatting that `culture server` produces today. Do not "improve" CLI ergonomics during the bootstrap; that breaks the transparency contract culture relies on. `dispatch()` returns `int` on successful command dispatch and lets argparse's `SystemExit` propagate on `--help`/`--version`/parse-errors per Python convention; in-process callers (i.e. culture's shim) must catch `SystemExit` themselves or use `subprocess`.
 
+Two intentional, additive deltas vs. culture's CLI:
+
+- `agentirc status` prints `Server 'X': running (PID N, port P)` when a port file is present — culture only prints `(PID N)`. Strictly a superset; culture's shim relies on exit codes, not output parsing.
+- `agentirc start` no longer accepts `--mesh-config` (depends on `culture.credentials` and `culture.mesh_config`, out of agentirc's scope). Use `--link name:host:port:password[:trust]` flags instead.
+
 ## Defaults preserve culture continuity
 
 - Default `--config` path: `~/.culture/server.yaml` (yes, `.culture/`, not `.agentirc/`).
@@ -76,14 +88,19 @@ pytest -n auto
 # Run a single test
 pytest tests/path/to/test_file.py::test_name -v
 
-# CLI smoke (works today against the skeleton)
+# CLI smoke
 agentirc --help
 agentirc-cli --help          # alias of agentirc
-agentirc version             # prints "agentirc 9.0.0"
+agentirc version             # prints "agentirc 9.2.0"
 python -m agentirc version   # equivalent
 
-# Lifecycle verbs (stubs in 9.0.0; real impls land with the IRCd extraction)
-agentirc serve --config ~/.culture/server.yaml
+# Lifecycle (functional since 9.2.0)
+agentirc serve --config ~/.culture/server.yaml          # foreground, no PID
+agentirc start --name spark --host 127.0.0.1 --port 6667  # daemonize
+agentirc status --name spark
+agentirc stop --name spark
+agentirc logs --name spark -f                            # tail -f the daemon log
+agentirc link 'peer1:host:6667:secret:full'              # parse + validate spec
 ```
 
 CLI verbs: `serve`, `start`, `stop`, `restart`, `status`, `link`, `logs`, `version`. Of these, only `start`, `stop`, `status` have a `culture server …` analogue today; the rest are agentirc-only additions. Culture's pure-passthrough shim only ever emits its existing verbs, so the additions don't break it.
@@ -129,7 +146,7 @@ Per-machine paths for these skills go in `.claude/skills.local.yaml` (gitignored
 
 The full list lives in §"Acceptance criteria" of the bootstrap spec. The non-obvious ones:
 
-- `pip install agentirc-cli==9.0.0` on a clean venv produces working `agentirc` *and* `agentirc-cli` binaries (both pointing at `agentirc.cli:main`).
-- `agentirc serve` is byte-indistinguishable from `culture server start` (same socket, same logs, same systemd integration).
-- `agentirc.config.LinkConfig`, `agentirc.config.PeerSpec`, `agentirc.cli.dispatch`, `agentirc.protocol.*` all import from a clean Python session.
-- `docs/api-stability.md` names the three public modules.
+- `pip install agentirc-cli==9.2.0` on a clean venv produces working `agentirc` *and* `agentirc-cli` binaries (both pointing at `agentirc.cli:main`). ✅ since 9.0.0.
+- `agentirc serve` is byte-indistinguishable from `culture server start` (same socket, same logs, same systemd integration). ✅ since 9.2.0.
+- `agentirc.config.{ServerConfig, LinkConfig, TelemetryConfig}`, `agentirc.cli.{main, dispatch}`, `agentirc.protocol.*` all import from a clean Python session. ✅ since 9.2.0.
+- `docs/api-stability.md` names the three public modules. ⏳ pending.

{agentirc_cli-9.1.0 → agentirc_cli-9.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentirc-cli
-Version: 9.1.0
+Version: 9.2.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

agentirc_cli-9.2.0/agentirc/_internal/cli_shared/constants.py

@@ -0,0 +1,56 @@
+"""Shared constants for the agentirc CLI.
+
+Vendored from culture@df50942 (`culture/cli/shared/constants.py`) and
+trimmed to the subset agentirc actually consumes. Bot-related constants
+(``BOT_CONFIG_FILE``, ``LEGACY_CONFIG``, ``AGENTS_YAML``, etc.) are
+dropped; agentirc has no bot configuration concept.
+
+Default paths (``~/.culture/server.yaml``, ``~/.culture/logs``) are kept
+intact per the "Defaults preserve culture continuity" rule in
+CLAUDE.md, so agentirc and culture daemons share state directories on a
+host without separate config trees.
+"""
+
+from __future__ import annotations
+
+import os
+import stat
+
+DEFAULT_CONFIG = os.path.expanduser("~/.culture/server.yaml")
+LOG_DIR = os.path.expanduser("~/.culture/logs")
+
+_CONFIG_HELP = "Config file path"
+_SERVER_NAME_HELP = "Server name"
+
+
+def culture_runtime_dir() -> str:
+    """Return a user-private directory for daemon sockets.
+
+    Resolution order:
+
+    1. ``$XDG_RUNTIME_DIR`` when set (Linux/systemd default — already
+       user-private at ``/run/user/<uid>``).
+    2. ``~/.culture/run/`` otherwise (typical macOS path), created mode
+       0700 if missing and re-tightened to 0700 on every call so a
+       hand-created or pre-existing dir cannot leak sockets.
+
+    Raises ``RuntimeError`` when neither ``XDG_RUNTIME_DIR`` nor a
+    resolvable home directory is available — silently writing a literal
+    ``~/.culture/run`` directory in CWD would surprise callers and the
+    daemons (which now route through this resolver) would fail at
+    socket-bind time anyway.
+    """
+    xdg = os.environ.get("XDG_RUNTIME_DIR")
+    if xdg:
+        return xdg
+    home = os.path.expanduser("~")
+    if not home or home == "~" or not os.path.isabs(home):
+        raise RuntimeError(
+            "culture_runtime_dir(): cannot resolve a home directory "
+            "(os.path.expanduser('~') returned %r). Set $HOME or "
+            "$XDG_RUNTIME_DIR before running agentirc commands." % home
+        )
+    fallback = os.path.join(home, ".culture", "run")
+    os.makedirs(fallback, mode=0o700, exist_ok=True)
+    os.chmod(fallback, stat.S_IRWXU)
+    return fallback

agentirc_cli-9.2.0/agentirc/_internal/cli_shared/mesh.py

@@ -0,0 +1,39 @@
+"""Mesh and link helpers for the agentirc CLI.
+
+Vendored from culture@df50942 (`culture/cli/shared/mesh.py`), reduced
+to the single helper agentirc needs: ``parse_link``. The upstream
+helpers ``resolve_links_from_mesh`` and ``generate_mesh_from_agents``
+depend on culture's ``mesh_config`` / ``credentials`` modules, which
+manage agent mesh and OS-keyring credential lookup — concepts that do
+not belong in agentirc's dependency-bounded surface.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+
+def parse_link(value: str):
+    """Parse a link spec: ``name:host:port:password[:trust]``.
+
+    Trust is extracted from the end if it matches a known value. This
+    allows passwords containing colons to round-trip through argparse
+    without escaping.
+    """
+    from agentirc.config import LinkConfig
+
+    trust = "full"
+    if value.endswith(":full") or value.endswith(":restricted"):
+        value, trust = value.rsplit(":", 1)
+
+    parts = value.split(":", 3)
+    if len(parts) != 4:
+        raise argparse.ArgumentTypeError(
+            f"Link must be name:host:port:password[:trust], got: {value}"
+        )
+    name, host, port_str, password = parts
+    try:
+        port = int(port_str)
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError(f"Invalid port: {port_str}") from exc
+    return LinkConfig(name=name, host=host, port=port, password=password, trust=trust)

agentirc_cli-9.2.0/agentirc/_internal/pidfile.py

@@ -0,0 +1,238 @@
+"""PID file management for agentirc daemon instances.
+
+Vendored from culture@df50942 (`culture/pidfile.py`) and adapted for
+agentirc per the cite-don't-copy convention. The on-disk layout
+(`~/.culture/pids/<name>.{pid,port}`) is preserved unchanged so culture
+and agentirc daemons can coexist on a host without separate state
+directories.
+
+Adaptation versus the upstream copy: `is_managed_process()` accepts
+both ``culture`` and ``agentirc`` argv tokens. ``is_culture_process``
+remains as a thin alias so call sites that haven't migrated keep
+working.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+
+PID_DIR = os.path.expanduser("~/.culture/pids")
+
+_MANAGED_PROCESS_TOKENS = ("culture", "agentirc", "agentirc-cli")
+
+
+def _safe_name(name: str) -> str:
+    """Sanitize a daemon name to prevent path traversal."""
+    return re.sub(r"[^a-zA-Z0-9._-]", "_", Path(name).name)
+
+
+def write_pid(name: str, pid: int) -> Path:
+    """Write a PID file for the named daemon. Creates the directory if needed."""
+    pid_dir = Path(PID_DIR)
+    pid_dir.mkdir(parents=True, exist_ok=True)
+    pid_path = pid_dir / f"{_safe_name(name)}.pid"
+    pid_path.write_text(str(pid))
+    return pid_path
+
+
+def read_pid(name: str) -> int | None:
+    """Read the PID for the named daemon. Returns None if file is missing."""
+    pid_path = Path(PID_DIR) / f"{_safe_name(name)}.pid"
+    if not pid_path.exists():
+        return None
+    try:
+        return int(pid_path.read_text().strip())
+    except (ValueError, OSError):
+        return None
+
+
+def remove_pid(name: str) -> None:
+    """Remove the PID file for the named daemon if it exists."""
+    pid_path = Path(PID_DIR) / f"{_safe_name(name)}.pid"
+    try:
+        pid_path.unlink()
+    except FileNotFoundError:
+        pass
+
+
+def write_port(name: str, port: int) -> Path:
+    """Write a port file for the named daemon. Creates the directory if needed."""
+    pid_dir = Path(PID_DIR)
+    pid_dir.mkdir(parents=True, exist_ok=True)
+    port_path = pid_dir / f"{_safe_name(name)}.port"
+    port_path.write_text(str(port))
+    return port_path
+
+
+def read_port(name: str) -> int | None:
+    """Read the port for the named daemon. Returns None if file is missing."""
+    port_path = Path(PID_DIR) / f"{_safe_name(name)}.port"
+    if not port_path.exists():
+        return None
+    try:
+        return int(port_path.read_text().strip())
+    except (ValueError, OSError):
+        return None
+
+
+def remove_port(name: str) -> None:
+    """Remove the port file for the named daemon if it exists."""
+    port_path = Path(PID_DIR) / f"{_safe_name(name)}.port"
+    try:
+        port_path.unlink()
+    except FileNotFoundError:
+        pass
+
+
+def is_managed_process(pid: int) -> bool:
+    """Check whether the given PID belongs to a culture or agentirc process.
+
+    Reads /proc/<pid>/cmdline on Linux and checks NUL-separated argv
+    tokens for an exact match against ``culture``, ``agentirc``, or
+    ``agentirc-cli`` (e.g. argv[0] basename or a ``-m culture``
+    argument). On platforms without /proc (macOS, Windows) or when
+    /proc parsing fails, falls back to ``ps -p <pid> -o command=``
+    when available; if neither identification path succeeds, returns
+    False (fail closed) so a stale PID file can never SIGTERM an
+    unrelated reused-PID process. Upstream culture treated the
+    macOS/Windows case as "assume valid"; PR #4 review flagged that
+    as exploitable when PIDs are reused.
+    """
+    if os.path.isdir("/proc"):
+        try:
+            raw = Path(f"/proc/{pid}/cmdline").read_bytes()
+            tokens = [t for t in raw.decode(errors="replace").split("\x00") if t]
+            return any(
+                os.path.basename(t) in _MANAGED_PROCESS_TOKENS
+                or t in _MANAGED_PROCESS_TOKENS
+                for t in tokens
+            )
+        except OSError:
+            return False
+    return _is_managed_via_ps(pid)
+
+
+def _is_managed_via_ps(pid: int) -> bool:
+    """Fallback identity check using ``ps`` for non-/proc platforms.
+
+    Uses ``ps -p <pid> -o command=`` (POSIX) to recover the command
+    line and tests for a managed-process token. Any failure (no
+    ``ps``, non-zero exit, parse error) returns False so we fail
+    closed rather than signalling an unknown process.
+    """
+    import shutil
+    import subprocess
+
+    ps = shutil.which("ps")
+    if ps is None:
+        return False
+    try:
+        # argv is a fixed token list with the pid coerced to int — no shell
+        # interpretation, no path that traverses untrusted input.
+        result = subprocess.run(
+            [ps, "-p", str(int(pid)), "-o", "command="],
+            capture_output=True,
+            text=True,
+            timeout=2,
+            check=False,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return False
+    if result.returncode != 0:
+        return False
+    cmdline = result.stdout.strip()
+    if not cmdline:
+        return False
+    tokens = cmdline.split()
+    return any(
+        os.path.basename(t) in _MANAGED_PROCESS_TOKENS or t in _MANAGED_PROCESS_TOKENS
+        for t in tokens
+    )
+
+
+def is_culture_process(pid: int) -> bool:
+    """Backwards-compatible alias for :func:`is_managed_process`.
+
+    The upstream culture API used this name; preserved so existing call
+    sites in vendored code keep working without churn.
+    """
+    return is_managed_process(pid)
+
+
+def is_process_alive(pid: int) -> bool:
+    """Check whether a process with the given PID is alive.
+
+    Uses signal 0 (existence test, no signal delivered) per POSIX. The
+    ``# NOSONAR S4828`` marker is intentional: signal 0 cannot deliver
+    a signal to the target — it only reports whether the kernel can
+    locate the PID. Sonar's "sending signals is safe here" rule is a
+    false positive for this idiom.
+    """
+    try:
+        os.kill(pid, 0)  # NOSONAR S4828 — sig=0 is existence test, no delivery
+        return True
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+
+
+def list_servers() -> list[dict]:
+    """List running culture/agentirc servers.
+
+    Returns list of dicts with keys: name, pid, port.
+    """
+    pid_dir = Path(PID_DIR)
+    if not pid_dir.exists():
+        return []
+    servers = []
+    prefix = "server-"
+    for pid_path in sorted(pid_dir.glob(f"{prefix}*.pid")):
+        pid_name = pid_path.stem
+        name = pid_name[len(prefix) :]
+        pid = read_pid(pid_name)
+        if pid is None or not is_process_alive(pid) or not is_managed_process(pid):
+            continue
+        port = read_port(pid_name) or 6667
+        servers.append({"name": name, "pid": pid, "port": port})
+    return servers
+
+
+def read_default_server() -> str | None:
+    """Read the default server name. Returns None if unset."""
+    default_path = Path(PID_DIR) / "default_server"
+    if not default_path.exists():
+        return None
+    try:
+        return default_path.read_text().strip() or None
+    except OSError:
+        return None
+
+
+def write_default_server(name: str) -> None:
+    """Set the default server name."""
+    pid_dir = Path(PID_DIR)
+    pid_dir.mkdir(parents=True, exist_ok=True)
+    (pid_dir / "default_server").write_text(name)
+
+
+def rename_pid(old_name: str, new_name: str) -> bool:
+    """Rename a PID file and its associated port file.
+
+    Best-effort: returns True if at least one file was renamed.
+    Failures are silently ignored to avoid raising during cleanup paths.
+    """
+    pid_dir = Path(PID_DIR)
+    renamed = False
+    for suffix in (".pid", ".port"):
+        old_path = pid_dir / f"{_safe_name(old_name)}{suffix}"
+        new_path = pid_dir / f"{_safe_name(new_name)}{suffix}"
+        if old_path.exists():
+            try:
+                old_path.rename(new_path)
+                renamed = True
+            except OSError:
+                pass
+    return renamed