agentirc-cli 8.7.0__tar.gz → 8.7.1__tar.gz

{agentirc_cli-8.7.0 → agentirc_cli-8.7.1}/CHANGELOG.md

@@ -4,6 +4,21 @@ All notable changes to this project will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/).
 
+## [8.7.1] - 2026-04-27
+
+### Added
+
+- `tests/test_socket_path_convergence.py`: parametric regression test asserting all 8 daemon+skill resolvers agree with the CLI's `agent_socket_path()` for both `XDG_RUNTIME_DIR` set and unset.
+- `tests/test_constants.py`: unit tests pinning `culture_runtime_dir()` contract (env precedence, `~/.culture/run/` fallback, mode 0700).
+
+### Changed
+
+- `culture channel {message,list,read}`: when `CULTURE_NICK` is set but the daemon IPC is unreachable or rejects the request, the CLI now prints a stderr warning naming the nick, the socket path, and the GitHub issue tracker before falling back to the peek-nick observer. The fallback itself is preserved for human use (no `CULTURE_NICK`).
+
+### Fixed
+
+- Converged all socket-path resolvers (4 backend daemons, 4 skill irc_clients, overview collector, harness package reference impl) on `culture_runtime_dir()` so the CLI and daemon agree on the IPC socket path when `XDG_RUNTIME_DIR` is unset (macOS default). Previously the daemon listened on `/tmp/culture-<nick>.sock` while the CLI looked in `~/.culture/run/`, causing `culture channel message` to silently fall back to an anonymous `_peek<random>` nick (#302, regression of #203).
+
 ## [8.7.0] - 2026-04-26
 
 ### Added

{agentirc_cli-8.7.0 → agentirc_cli-8.7.1}/PKG-INFO

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

{agentirc_cli-8.7.0 → agentirc_cli-8.7.1}/culture/cli/channel.py

@@ -24,11 +24,43 @@ def _valid_nick(nick: str) -> bool:
     return len(parts) == 2 and all(parts)
 
 
+_ISSUE_TRACKER_URL = "https://github.com/agentculture/culture/issues"
+
+
+def _warn_observer_fallback(operation: str) -> None:
+    """Warn on stderr when an observer-fallback command silently went anonymous.
+
+    Called only by the three commands that do fall back to the observer
+    connection (`message`, `list`, `read`). `topic` and the `_require_ipc`
+    commands exit on failure instead, so this helper is not used there —
+    a misleading "falling back" notice would contradict the actual error.
+
+    Issue #302: a daemon/CLI socket-path mismatch on macOS hid behind the
+    silent peek fallback for two releases. The warning names the issue
+    tracker so the next reproducer takes seconds to file.
+    """
+    nick = os.environ.get("CULTURE_NICK")
+    if not nick or not _valid_nick(nick):
+        return  # Human use without CULTURE_NICK — observer is the intended path.
+    sock = agent_socket_path(nick)
+    print(
+        f"Warning: agent daemon IPC for {nick} failed ({sock}).\n"
+        f"  Falling back to observer connection — `{operation}` will not run\n"
+        f"  through the agent daemon and the action will not appear under {nick}.\n"
+        f"  Verify the daemon is running:    culture agent status {nick}\n"
+        f"  If it is running, this is a bug. Please open an issue:\n"
+        f"    {_ISSUE_TRACKER_URL}",
+        file=sys.stderr,
+    )
+
+
 def _try_ipc(msg_type: str, **kwargs) -> dict | None:
     """Try to route a command through the agent daemon's IPC socket.
 
     Returns the response dict if CULTURE_NICK is set and the daemon is
-    reachable, otherwise None (caller should fall back to observer).
+    reachable, otherwise None (caller should fall back to observer or
+    surface its own error — see `_warn_observer_fallback` for the
+    observer-fallback path).
     """
     nick = os.environ.get("CULTURE_NICK")
     if not nick or not _valid_nick(nick):
@@ -169,6 +201,7 @@ def _cmd_list(args: argparse.Namespace) -> None:
             print(f"  {ch}")
         return
 
+    _warn_observer_fallback("channel list")
     observer = get_observer(args.config)
     channels = asyncio.run(observer.list_channels())
 
@@ -199,6 +232,7 @@ def _cmd_read(args: argparse.Namespace) -> None:
             print(f"<{nick}> {text}")
         return
 
+    _warn_observer_fallback("channel read")
     observer = get_observer(args.config)
     messages = asyncio.run(observer.read_channel(channel, limit=args.limit))
 
@@ -267,6 +301,7 @@ def _cmd_message(args: argparse.Namespace) -> None:
         print(f"Sent to {target}")
         return
 
+    _warn_observer_fallback("channel message")
     observer = get_observer(args.config)
     asyncio.run(observer.send_message(target, text))
     print(f"Sent to {target}")

agentirc_cli-8.7.1/culture/cli/shared/constants.py

@@ -0,0 +1,54 @@
+"""Shared constants for culture CLI modules."""
+
+import os
+import stat
+
+from culture.bots.config import BOT_CONFIG_FILE  # noqa: F401
+
+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"
+_BOT_NAME_HELP = "Bot name"
+
+DEFAULT_CHANNEL = "#general"
+NO_AGENTS_MSG = "No agents configured"
+CULTURE_DIR = ".culture"
+AGENTS_YAML = "agents.yaml"
+
+DEFAULT_SERVER_CONFIG = os.path.expanduser("~/.culture/server.yaml")
+LEGACY_CONFIG = os.path.expanduser("~/.culture/agents.yaml")
+
+
+def culture_runtime_dir() -> str:
+    """Return a user-private directory for culture 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 culture 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-8.7.0 → agentirc_cli-8.7.1}/culture/clients/acp/daemon.py

@@ -18,6 +18,7 @@ import time
 from collections import deque
 
 from culture.aio import maybe_await
+from culture.cli.shared.constants import culture_runtime_dir
 from culture.clients.acp.agent_runner import ACPAgentRunner
 from culture.clients.acp.config import AgentConfig, DaemonConfig
 from culture.clients.acp.ipc import make_response
@@ -62,7 +63,7 @@ class ACPDaemon:
         self.skip_agent = skip_agent
 
         self._socket_path = os.path.join(
-            socket_dir or os.environ.get("XDG_RUNTIME_DIR", "/tmp"),
+            socket_dir or culture_runtime_dir(),
             f"culture-{agent.nick}.sock",
         )
 

{agentirc_cli-8.7.0 → agentirc_cli-8.7.1}/culture/clients/acp/skill/irc_client.py

@@ -16,6 +16,7 @@ import os
 import sys
 from typing import Any
 
+from culture.cli.shared.constants import culture_runtime_dir
 from culture.clients.acp.ipc import (
     MSG_TYPE_RESPONSE,
     MSG_TYPE_WHISPER,
@@ -192,8 +193,7 @@ def _sock_path_from_env() -> str:
     if not nick:
         print("ERROR: CULTURE_NICK environment variable is not set", file=sys.stderr)
         sys.exit(1)
-    runtime_dir = os.environ.get("XDG_RUNTIME_DIR", "/tmp")
-    return os.path.join(runtime_dir, f"culture-{nick}.sock")
+    return os.path.join(culture_runtime_dir(), f"culture-{nick}.sock")
 
 
 def _parse_ask_timeout(remaining: list[str]) -> tuple[int, list[str]]:

{agentirc_cli-8.7.0 → agentirc_cli-8.7.1}/culture/clients/claude/daemon.py

@@ -8,6 +8,7 @@ import re
 import time
 
 from culture.aio import maybe_await
+from culture.cli.shared.constants import culture_runtime_dir
 from culture.clients.claude.agent_runner import AgentRunner
 from culture.clients.claude.config import AgentConfig, DaemonConfig
 from culture.clients.claude.ipc import make_response
@@ -51,7 +52,7 @@ class AgentDaemon:
         self.skip_claude = skip_claude
 
         self._socket_path = os.path.join(
-            socket_dir or os.environ.get("XDG_RUNTIME_DIR", "/tmp"),
+            socket_dir or culture_runtime_dir(),
             f"culture-{agent.nick}.sock",
         )
 

{agentirc_cli-8.7.0 → agentirc_cli-8.7.1}/culture/clients/claude/skill/irc_client.py

@@ -16,6 +16,7 @@ import os
 import sys
 from typing import Any
 
+from culture.cli.shared.constants import culture_runtime_dir
 from culture.clients.claude.ipc import (
     MSG_TYPE_RESPONSE,
     MSG_TYPE_WHISPER,
@@ -189,8 +190,7 @@ def _sock_path_from_env() -> str:
     if not nick:
         print("ERROR: CULTURE_NICK environment variable is not set", file=sys.stderr)
         sys.exit(1)
-    runtime_dir = os.environ.get("XDG_RUNTIME_DIR", "/tmp")
-    return os.path.join(runtime_dir, f"culture-{nick}.sock")
+    return os.path.join(culture_runtime_dir(), f"culture-{nick}.sock")
 
 
 def _parse_ask_timeout(remaining: list[str]) -> tuple[int, list[str]]:

{agentirc_cli-8.7.0 → agentirc_cli-8.7.1}/culture/clients/codex/daemon.py

@@ -15,6 +15,7 @@ import time
 from collections import deque
 
 from culture.aio import maybe_await
+from culture.cli.shared.constants import culture_runtime_dir
 from culture.clients.codex.agent_runner import CodexAgentRunner
 from culture.clients.codex.config import AgentConfig, DaemonConfig
 from culture.clients.codex.ipc import make_response
@@ -66,7 +67,7 @@ class CodexDaemon:
         self.skip_codex = skip_codex
 
         self._socket_path = os.path.join(
-            socket_dir or os.environ.get("XDG_RUNTIME_DIR", "/tmp"),
+            socket_dir or culture_runtime_dir(),
             f"culture-{agent.nick}.sock",
         )
 

{agentirc_cli-8.7.0 → agentirc_cli-8.7.1}/culture/clients/codex/skill/irc_client.py

@@ -16,6 +16,7 @@ import os
 import sys
 from typing import Any
 
+from culture.cli.shared.constants import culture_runtime_dir
 from culture.clients.codex.ipc import (
     MSG_TYPE_RESPONSE,
     MSG_TYPE_WHISPER,
@@ -189,8 +190,7 @@ def _sock_path_from_env() -> str:
     if not nick:
         print("ERROR: CULTURE_NICK environment variable is not set", file=sys.stderr)
         sys.exit(1)
-    runtime_dir = os.environ.get("XDG_RUNTIME_DIR", "/tmp")
-    return os.path.join(runtime_dir, f"culture-{nick}.sock")
+    return os.path.join(culture_runtime_dir(), f"culture-{nick}.sock")
 
 
 def _parse_ask_timeout(remaining: list[str]) -> tuple[int, list[str]]:

{agentirc_cli-8.7.0 → agentirc_cli-8.7.1}/culture/clients/copilot/daemon.py

@@ -15,6 +15,7 @@ import time
 from collections import deque
 
 from culture.aio import maybe_await
+from culture.cli.shared.constants import culture_runtime_dir
 from culture.clients.copilot.agent_runner import CopilotAgentRunner
 from culture.clients.copilot.config import AgentConfig, DaemonConfig
 from culture.clients.copilot.ipc import make_response
@@ -59,7 +60,7 @@ class CopilotDaemon:
         self.skip_copilot = skip_copilot
 
         self._socket_path = os.path.join(
-            socket_dir or os.environ.get("XDG_RUNTIME_DIR", "/tmp"),
+            socket_dir or culture_runtime_dir(),
             f"culture-{agent.nick}.sock",
         )
 

{agentirc_cli-8.7.0 → agentirc_cli-8.7.1}/culture/clients/copilot/skill/irc_client.py

@@ -16,6 +16,7 @@ import os
 import sys
 from typing import Any
 
+from culture.cli.shared.constants import culture_runtime_dir
 from culture.clients.copilot.ipc import (
     MSG_TYPE_RESPONSE,
     MSG_TYPE_WHISPER,
@@ -192,8 +193,7 @@ def _sock_path_from_env() -> str:
     if not nick:
         print("ERROR: CULTURE_NICK environment variable is not set", file=sys.stderr)
         sys.exit(1)
-    runtime_dir = os.environ.get("XDG_RUNTIME_DIR", "/tmp")
-    return os.path.join(runtime_dir, f"culture-{nick}.sock")
+    return os.path.join(culture_runtime_dir(), f"culture-{nick}.sock")
 
 
 def _parse_ask_timeout(remaining: list[str]) -> tuple[int, list[str]]:

{agentirc_cli-8.7.0 → agentirc_cli-8.7.1}/culture/overview/collector.py

@@ -7,6 +7,7 @@ import glob
 import os
 
 from culture.bots.config import BOT_CONFIG_FILE
+from culture.cli.shared.constants import culture_runtime_dir
 from culture.protocol.message import Message as IRCMessage
 
 from .model import Agent, BotInfo, MeshState, Message, Room
@@ -428,8 +429,7 @@ async def _enrich_via_ipc(agents: dict[str, Agent], server_name: str) -> None:
     """Enrich local agents with daemon IPC status data."""
     from culture.clients.claude.ipc import decode_message, encode_message, make_request
 
-    runtime_dir = os.environ.get("XDG_RUNTIME_DIR", "/tmp")
-    socket_pattern = os.path.join(runtime_dir, "culture-*.sock")
+    socket_pattern = os.path.join(culture_runtime_dir(), "culture-*.sock")
 
     for sock_path in glob.glob(socket_pattern):
         # Extract nick from socket filename: culture-<nick>.sock

{agentirc_cli-8.7.0 → agentirc_cli-8.7.1}/docs/reference/architecture/agent-harness-spec.md

@@ -295,7 +295,18 @@ Unix socket.
 $XDG_RUNTIME_DIR/culture-<nick>.sock
 ```
 
-Falls back to `/tmp/culture-<nick>.sock` if `XDG_RUNTIME_DIR` is not set.
+Falls back to `~/.culture/run/culture-<nick>.sock` (mode 0700) if
+`XDG_RUNTIME_DIR` is not set — typical on macOS. The fallback is
+user-private rather than world-writable like `/tmp/`.
+
+All socket-path resolvers (4 backend daemons, 4 skill irc_clients, the
+CLI in `culture/cli/shared/constants.py::culture_runtime_dir()`, the
+overview collector, and the console status reader) MUST go through
+`culture_runtime_dir()`. A regression test in
+`tests/test_socket_path_convergence.py` parametrically asserts every
+site agrees, with `XDG_RUNTIME_DIR` both set and unset. Any future site
+that re-introduces a raw `os.environ.get("XDG_RUNTIME_DIR", "/tmp")`
+will fail that test (issue #302).
 
 ### Message Format
 

{agentirc_cli-8.7.0 → agentirc_cli-8.7.1}/docs/reference/cli/index.md

@@ -250,6 +250,19 @@ culture channel message "#general" "hello from the CLI"
 
 Uses an ephemeral IRC connection — no daemon required.
 
+**Sending under an agent's nick.** Set `CULTURE_NICK=<server>-<agent>` and
+`culture channel message` (along with `list` and `read`) routes through
+the agent daemon's Unix socket so the message appears under the agent's
+real nick instead of an ephemeral peek connection.
+
+If `CULTURE_NICK` is set but the daemon's IPC socket is unreachable (or
+the daemon rejects the request), the CLI falls back to the peek path
+*and* prints a stderr warning that names the nick, the socket path, and
+the issue tracker. Treat the warning as actionable: check
+`culture agent status <nick>`, and if the daemon is running, file a bug
+at <https://github.com/agentculture/culture/issues> — a silent fallback
+here masked a macOS path-mismatch bug for two releases (#302).
+
 **Multi-line messages.** The message text interprets `\n` as a newline and
 `\t` as a tab, so the shell can pass multi-line input without needing
 `$'...'` quoting. Each line is sent as a separate IRC `PRIVMSG` (required by

{agentirc_cli-8.7.0 → agentirc_cli-8.7.1}/packages/agent-harness/daemon.py

@@ -22,6 +22,7 @@ from typing import Any
 
 # These imports point to YOUR backend's copies of these files:
 from culture.aio import maybe_await
+from culture.cli.shared.constants import culture_runtime_dir
 from culture.clients.BACKEND.config import AgentConfig, DaemonConfig
 from culture.clients.BACKEND.ipc import make_response
 from culture.clients.BACKEND.irc_transport import IRCTransport
@@ -66,7 +67,7 @@ class AgentDaemon:
         self.skip_agent = skip_agent
 
         self._socket_path = os.path.join(
-            socket_dir or os.environ.get("XDG_RUNTIME_DIR", "/tmp"),
+            socket_dir or culture_runtime_dir(),
             f"culture-{agent.nick}.sock",
         )
 

{agentirc_cli-8.7.0 → agentirc_cli-8.7.1}/packages/agent-harness/skill/irc_client.py

@@ -19,6 +19,7 @@ import os
 import sys
 from typing import Any
 
+from culture.cli.shared.constants import culture_runtime_dir
 from culture.clients.BACKEND.ipc import (
     MSG_TYPE_RESPONSE,
     MSG_TYPE_WHISPER,
@@ -192,8 +193,7 @@ def _sock_path_from_env() -> str:
     if not nick:
         print("ERROR: CULTURE_NICK environment variable is not set", file=sys.stderr)
         sys.exit(1)
-    runtime_dir = os.environ.get("XDG_RUNTIME_DIR", "/tmp")
-    return os.path.join(runtime_dir, f"culture-{nick}.sock")
+    return os.path.join(culture_runtime_dir(), f"culture-{nick}.sock")
 
 
 def _parse_ask_timeout(remaining: list[str]) -> tuple[int, list[str]]:

{agentirc_cli-8.7.0 → agentirc_cli-8.7.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentirc-cli"
-version = "8.7.0"
+version = "8.7.1"
 description = "Legacy alias for culture — install culture instead"
 readme = "README.md"
 license = "MIT"

{agentirc_cli-8.7.0 → agentirc_cli-8.7.1}/tests/test_channel_cli.py

@@ -12,6 +12,7 @@ from culture.cli.channel import (
     _require_ipc,
     _try_ipc,
     _valid_nick,
+    _warn_observer_fallback,
     dispatch,
     register,
 )
@@ -87,7 +88,8 @@ class TestMessageIpcRouting:
         monkeypatch.setenv("CULTURE_NICK", "spark-claude")
         monkeypatch.setenv("XDG_RUNTIME_DIR", tempfile.mkdtemp())
 
-        # _try_ipc should return None when socket doesn't exist
+        # _try_ipc itself stays silent — the warning is emitted by the
+        # observer-fallback caller (see TestObserverFallbackWarning).
         result = _try_ipc("irc_send", channel="#general", message="hello")
         assert result is None
 
@@ -98,6 +100,81 @@ class TestMessageIpcRouting:
         assert result is None
 
 
+class TestObserverFallbackWarning:
+    """Issue #302: the three observer-fallback callers must warn loudly.
+
+    Before the fix, a daemon/CLI socket-path mismatch on macOS caused
+    `culture channel message` to silently fall back to an anonymous peek
+    connection. The CLI printed `Sent to #general` either way, so the
+    bug hid for two releases. The warning must (a) name the nick that
+    was attempted, (b) name the operation, and (c) point at the GitHub
+    issue tracker so the next reproducer takes seconds to file.
+
+    The warning lives in `_warn_observer_fallback`, called only by
+    `_cmd_message`, `_cmd_list`, and `_cmd_read`. `_topic_read` and the
+    `_require_ipc` commands exit on failure instead, so no spurious
+    "falling back" notice contradicts their actual error.
+    """
+
+    def test_warns_when_nick_set_and_daemon_unreachable(self, monkeypatch, capsys):
+        """CULTURE_NICK set + IPC down → stderr warning naming op + nick + issues URL."""
+        monkeypatch.setenv("CULTURE_NICK", "spark-claude")
+        monkeypatch.setenv("XDG_RUNTIME_DIR", tempfile.mkdtemp())
+
+        _warn_observer_fallback("channel message")
+
+        err = capsys.readouterr().err
+        assert "spark-claude" in err
+        assert "channel message" in err
+        assert "Falling back to observer" in err
+        assert "https://github.com/agentculture/culture/issues" in err
+
+    def test_warning_text_is_operation_specific(self, monkeypatch, capsys):
+        """Each caller passes its own operation name; helper renders it verbatim."""
+        monkeypatch.setenv("CULTURE_NICK", "spark-claude")
+        monkeypatch.setenv("XDG_RUNTIME_DIR", tempfile.mkdtemp())
+
+        _warn_observer_fallback("channel list")
+        err = capsys.readouterr().err
+        assert "channel list" in err
+        assert "channel message" not in err  # no leakage from sibling callers
+
+    def test_no_warning_when_nick_unset(self, monkeypatch, capsys):
+        """Human use without CULTURE_NICK is the legitimate observer path — no warning."""
+        monkeypatch.delenv("CULTURE_NICK", raising=False)
+
+        _warn_observer_fallback("channel message")
+
+        assert capsys.readouterr().err == ""
+
+    def test_no_warning_when_nick_invalid(self, monkeypatch, capsys):
+        """Invalid nick falls into the same human-use bucket — no warning."""
+        monkeypatch.setenv("CULTURE_NICK", "nodash")
+
+        _warn_observer_fallback("channel message")
+
+        assert capsys.readouterr().err == ""
+
+    def test_topic_read_does_not_warn(self, monkeypatch, capsys):
+        """_topic_read uses _try_ipc but exits on failure — no fallback, no warning.
+
+        Regression guard against the Qodo/Copilot review on PR #304: the
+        previous design auto-warned inside `_try_ipc` and printed a
+        misleading 'falling back' notice for `topic` (which actually exits).
+        """
+        from culture.cli.channel import _topic_read
+
+        monkeypatch.setenv("CULTURE_NICK", "spark-claude")
+        monkeypatch.setenv("XDG_RUNTIME_DIR", tempfile.mkdtemp())
+
+        with pytest.raises(SystemExit):
+            _topic_read("#general")
+
+        err = capsys.readouterr().err
+        assert "Falling back" not in err
+        assert "topic query requires" in err
+
+
 class TestNickValidation:
     """Issue #202 review: CULTURE_NICK must match <server>-<agent> format."""
 

agentirc_cli-8.7.1/tests/test_constants.py

@@ -0,0 +1,86 @@
+"""Unit tests for culture/cli/shared/constants.py.
+
+Issue #302 turned `culture_runtime_dir()` into the single source of truth
+for the daemon socket directory. Pin its contract so any future refactor
+that breaks the env-var precedence, fallback path, or 0700 mode is caught
+in CI rather than at runtime on macOS.
+"""
+
+from __future__ import annotations
+
+import os
+import stat
+from pathlib import Path
+
+from culture.cli.shared.constants import culture_runtime_dir
+
+
+def test_uses_xdg_runtime_dir_when_set(monkeypatch, tmp_path):
+    """When XDG_RUNTIME_DIR is set, the value is returned verbatim."""
+    monkeypatch.setenv("XDG_RUNTIME_DIR", str(tmp_path))
+    assert culture_runtime_dir() == str(tmp_path)
+
+
+def test_falls_back_to_culture_run_when_xdg_unset(monkeypatch, tmp_path):
+    """When XDG_RUNTIME_DIR is missing, fall back to ~/.culture/run/.
+
+    macOS regression: this used to fall back to /tmp in the daemons but to
+    ~/.culture/run/ in the CLI. The fix converged everyone on the latter.
+    """
+    monkeypatch.delenv("XDG_RUNTIME_DIR", raising=False)
+    monkeypatch.setenv("HOME", str(tmp_path))
+    expected = str(tmp_path / ".culture" / "run")
+    assert culture_runtime_dir() == expected
+
+
+def test_creates_fallback_dir_with_user_only_permissions(monkeypatch, tmp_path):
+    """The fallback directory is created mode 0700 (user-private).
+
+    /tmp would have been world-writable; ~/.culture/run/ is mode 0700 so
+    sockets there cannot be observed or hijacked by other local users.
+    """
+    monkeypatch.delenv("XDG_RUNTIME_DIR", raising=False)
+    monkeypatch.setenv("HOME", str(tmp_path))
+    path = Path(culture_runtime_dir())
+    assert path.exists()
+    assert path.is_dir()
+    mode = stat.S_IMODE(os.stat(path).st_mode)
+    assert mode == 0o700, f"expected mode 0700, got {oct(mode)}"
+
+
+def test_raises_when_home_unresolvable(monkeypatch):
+    """Both XDG_RUNTIME_DIR and HOME unset → RuntimeError, not a literal '~' dir.
+
+    Qodo flagged that the pre-fix resolver would silently `mkdir` a literal
+    `~/.culture/run` in CWD if `os.path.expanduser('~')` could not resolve.
+    Now that 9 daemons/skills depend on this resolver, fail loud instead.
+    """
+    monkeypatch.delenv("XDG_RUNTIME_DIR", raising=False)
+    monkeypatch.delenv("HOME", raising=False)
+    # On Linux, expanduser may still consult /etc/passwd via pwd. Force
+    # the fallback path by also clearing the user's pwd entry lookup.
+    monkeypatch.setattr(os.path, "expanduser", lambda p: p)
+
+    import pytest
+
+    with pytest.raises(RuntimeError, match="cannot resolve a home directory"):
+        culture_runtime_dir()
+
+
+def test_enforces_permissions_on_existing_dir(monkeypatch, tmp_path):
+    """Even if the fallback dir already exists with wrong perms, it's tightened.
+
+    Defensive: a previous version of culture (or a hand-created dir) may
+    have left ~/.culture/run/ at 0755. Re-tighten on every call so the
+    invariant always holds at runtime.
+    """
+    monkeypatch.delenv("XDG_RUNTIME_DIR", raising=False)
+    monkeypatch.setenv("HOME", str(tmp_path))
+    pre_existing = tmp_path / ".culture" / "run"
+    pre_existing.mkdir(parents=True, mode=0o755)
+    os.chmod(pre_existing, 0o755)  # noqa: S103 — intentional: test that loose perms get tightened
+
+    culture_runtime_dir()
+
+    mode = stat.S_IMODE(os.stat(pre_existing).st_mode)
+    assert mode == 0o700