An always-on second brain you talk to. Voice notes in Telegram → typed, linked knowledge in your Obsidian vault. Runs 24/7 on the Claude subscription you already have.
Python ai-agentsai-automationclaudeclaude-codeebbinghausknowledge-graphllmmemory-systemobsidianpersonal-assistantpkmproductivitypythonsecond-braintelegram-botvoice-assistant
"""Tests for ClaudeSession orchestration.
The real tmux/subprocess layer is replaced by FakeTmux, which models the
pane as a small state machine and returns scripted capture-pane output.
Clock, sleep and rid generation are injected so polling, timeout
and stall detection are deterministic and fast.
"""
import subprocess
from pathlib import Path
import pytest
from d_brain.services.claude_session import AskResult, ClaudeSession
READY = (
"────────────────────\n❯\n────────────────────\n"
" hello | Opus 4.8 (1M context) | ~/p\n"
" ⏵⏵ bypass permissions on (shift+tab to cycle)\n"
)
TRUST = (
" Quick safety check: Is this a project you created or one you trust?\n"
" ❯ 1. Yes, I trust this folder\n 2. No, exit\n"
)
BYPASS = (
" WARNING: Claude Code running in Bypass Permissions mode\n\n"
" In Bypass Permissions mode, Claude Code will not ask for your approval.\n"
" ❯ 1. No, exit\n 2. Yes, I accept\n"
)
THINKING = " ✻ Working… (esc to interrupt)\n"
RATE = " You've reached your usage limit. Your limit resets at 3:00 PM.\n❯\n"
LOGGED_OUT = " Invalid API key · Please run /login to authenticate.\n❯\n"
def _complete(rid: str, reply: str = "PONG") -> str:
return f"some echo <<<R:{rid}>>> inline\n<<<R:{rid}>>>\n{reply}\n<<<E:{rid}>>>\n❯\n"
def _inline_echo(rid: str) -> str:
"""Echo of the typed prompt: markers appear INLINE (mid-sentence)."""
return f"> reply, wrap between <<<R:{rid}>>> and <<<E:{rid}>>> markers\n{THINKING}"
class FakeTmux:
"""Callable stand-in for subprocess.run over `tmux ...`."""
def __init__(self, capture_script: list[str], exists: bool = False) -> None:
self._captures = list(capture_script)
self.exists = exists
self.calls: list[list[str]] = []
def __call__(self, args, **kwargs): # noqa: ANN001
self.calls.append(args)
sub = args[1] if args and args[0] == "tmux" else args[0]
out, rc = "", 0
if sub == "has-session":
rc = 0 if self.exists else 1
elif sub == "new-session":
self.exists = True
elif sub == "capture-pane":
out = (
self._captures.pop(0)
if len(self._captures) > 1
else (self._captures[0] if self._captures else "")
)
return subprocess.CompletedProcess(args, rc, stdout=out, stderr="")
def sent_subcommands(self) -> list[str]:
return [c[1] for c in self.calls if c and c[0] == "tmux"]
def sent_keys(self) -> list[list[str]]:
return [c for c in self.calls if len(c) > 1 and c[1] == "send-keys"]
def enter_count(self) -> int:
return sum(1 for c in self.sent_keys() if c[-1] == "Enter")
@pytest.fixture
def clock():
return {"now": 0.0}
def make_session(
tmp_path: Path,
fake: FakeTmux,
clock: dict,
*,
rid: str = "rid00001",
) -> ClaudeSession:
def sleep_fn(seconds: float) -> None:
clock["now"] += seconds
return ClaudeSession(
session_name="dbrain_test",
work_dir=tmp_path / "vault",
runtime_dir=tmp_path / ".dbrain",
runner=fake,
sleep_fn=sleep_fn,
clock_fn=lambda: clock["now"],
rid_factory=lambda: rid,
poll_interval=1.0,
startup_timeout=30.0,
stall_timeout=10.0,
)
# ── ensure_session ──────────────────────────────────────────────────────
def test_ensure_session_creates_when_absent(tmp_path, clock):
fake = FakeTmux([READY], exists=False)
s = make_session(tmp_path, fake, clock)
s.ensure_session()
assert "new-session" in fake.sent_subcommands()
assert "pipe-pane" in fake.sent_subcommands()
assert (tmp_path / ".dbrain" / "ready").exists()
def test_ensure_session_noop_when_present(tmp_path, clock):
fake = FakeTmux([READY], exists=True)
s = make_session(tmp_path, fake, clock)
s.ensure_session()
assert "new-session" not in fake.sent_subcommands()
def test_ensure_session_handles_trust_prompt(tmp_path, clock):
fake = FakeTmux([TRUST, READY], exists=False)
s = make_session(tmp_path, fake, clock)
s.ensure_session()
assert fake.enter_count() >= 1
def test_ensure_session_does_not_enter_spam_on_trust(tmp_path, clock):
"""Trust persists for several captures; Enter must be debounced to the
transition, not sent on every poll (M2)."""
fake = FakeTmux([TRUST, TRUST, TRUST, READY], exists=False)
s = make_session(tmp_path, fake, clock)
s.ensure_session()
assert fake.enter_count() == 1
def _digit_sends(fake: FakeTmux, digit: str) -> int:
return sum(1 for c in fake.sent_keys() if c[-1] == digit)
def test_ensure_session_accepts_bypass_prompt(tmp_path, clock):
"""Fresh config dir under --dangerously-skip-permissions shows the bypass
accept screen; the session must actively pick "2. Yes, I accept" (the safe
default sits on "1. No, exit") and then reach READY."""
fake = FakeTmux([BYPASS, READY], exists=False)
s = make_session(tmp_path, fake, clock)
s.ensure_session()
assert _digit_sends(fake, "2") == 1
assert (tmp_path / ".dbrain" / "ready").exists()
def test_ensure_session_does_not_spam_bypass(tmp_path, clock):
"""Bypass persists for several captures; "2" debounced to the transition."""
fake = FakeTmux([BYPASS, BYPASS, BYPASS, READY], exists=False)
s = make_session(tmp_path, fake, clock)
s.ensure_session()
assert _digit_sends(fake, "2") == 1
def test_ensure_session_raises_if_never_ready(tmp_path, clock):
fake = FakeTmux([THINKING], exists=False)
s = make_session(tmp_path, fake, clock)
with pytest.raises(RuntimeError):
s.ensure_session()
# ── sending (buffer) ─────────────────────────────────────────────────────
def test_send_text_pipes_long_payload_via_stdin(tmp_path, clock):
"""Regression: a long prompt must be streamed to `tmux load-buffer -` over
stdin, never passed as an argv element — argv data trips tmux's
`set-buffer: command too long` and the prompt is silently dropped."""
recorded: list[tuple[list[str], dict]] = []
def runner(args, **kwargs):
recorded.append((args, kwargs))
return subprocess.CompletedProcess(args, 0, stdout="", stderr="")
s = make_session(tmp_path, runner, clock)
big = "x" * 200_000
s._send_text(big)
loads = [
(a, k)
for (a, k) in recorded
if len(a) > 1 and a[1] in ("set-buffer", "load-buffer")
]
assert loads, "expected a buffer-load tmux call"
args, kwargs = loads[0]
assert big not in args, "payload must not be passed as an argv element"
assert kwargs.get("input") == big, "payload must be piped via stdin"
assert args[1] == "load-buffer" and "-" in args
def test_send_text_noop_on_empty(tmp_path, clock):
"""`load-buffer -` of zero bytes creates no buffer, so a following
paste-buffer would fail `no buffer` — empty text must send nothing."""
recorded: list[list[str]] = []
def runner(args, **kwargs):
recorded.append(args)
return subprocess.CompletedProcess(args, 0, stdout="", stderr="")
s = make_session(tmp_path, runner, clock)
s._send_text("")
subs = [a[1] for a in recorded if len(a) > 1 and a[0] == "tmux"]
assert "load-buffer" not in subs and "paste-buffer" not in subs
# ── ask ─────────────────────────────────────────────────────────────────
def test_ask_returns_reply_on_completion(tmp_path, clock):
rid = "abcd0001"
fake = FakeTmux([READY, THINKING, _complete(rid)], exists=True)
s = make_session(tmp_path, fake, clock, rid=rid)
res = s.ask("ping", timeout=60)
assert isinstance(res, AskResult)
assert res.ok
assert res.reply == "PONG"
def test_ask_ignores_inline_echo_contamination(tmp_path, clock):
"""The echoed prompt has inline markers; ask must NOT complete on it,
only on the real line-anchored answer (H1 at session level)."""
rid = "echo0001"
fake = FakeTmux([READY, _inline_echo(rid), _complete(rid)], exists=True)
s = make_session(tmp_path, fake, clock, rid=rid)
res = s.ask("ping", timeout=60)
assert res.reply == "PONG"
def test_ask_detects_rate_limit_without_hanging(tmp_path, clock):
fake = FakeTmux([RATE], exists=True)
s = make_session(tmp_path, fake, clock)
res = s.ask("ping", timeout=60)
assert res.status == "rate_limited"
assert not res.ok
def test_ask_detects_logged_out(tmp_path, clock):
fake = FakeTmux([LOGGED_OUT], exists=True)
s = make_session(tmp_path, fake, clock)
res = s.ask("ping", timeout=60)
assert res.status == "logged_out"
def test_ask_times_out_when_no_reply(tmp_path, clock):
fake = FakeTmux([READY, THINKING], exists=True)
# the working spinner is visible, so it's a timeout, not a stall
s = make_session(tmp_path, fake, clock)
res = s.ask("ping", timeout=3)
assert res.status == "timeout"
def test_ask_detects_stall_and_interrupts(tmp_path, clock):
"""v3.0 stall model: a turn with NO visible work (no 'esc to interrupt'
spinner, no markers) longer than stall_timeout is stuck — the prompt got
eaten or the turn is waiting on something undrivable. Interrupt promptly."""
fake = FakeTmux([READY, READY], exists=True) # never shows work
s = make_session(tmp_path, fake, clock)
res = s.ask("ping", timeout=600)
assert res.status == "error"
assert "stall" in (res.detail or "").lower()
assert any(c[-1] == "C-c" for c in fake.sent_keys())
def test_ask_long_silent_work_not_interrupted(tmp_path, clock):
"""The working spinner is visible → the turn is ALIVE however quiet it
is. No C-c; the hard timeout (not a stall) ends the wait."""
fake = FakeTmux([READY, THINKING], exists=True)
s = make_session(tmp_path, fake, clock)
res = s.ask("ping", timeout=30)
assert res.status == "timeout"
assert not any(c[-1] == "C-c" for c in fake.sent_keys())
def test_ask_returns_error_when_ensure_fails(tmp_path, clock):
"""ensure_session failing must surface as AskResult('error'), never an
exception out of ask() (C2)."""
fake = FakeTmux([THINKING], exists=False) # never becomes READY
s = make_session(tmp_path, fake, clock)
res = s.ask("ping", timeout=60)
assert res.status == "error"
def test_ask_leaves_inflight_orphan_on_timeout(tmp_path, clock):
"""A timed-out prompt is still physically in the pane; inflight marker
must persist as a stuck-signal (M6)."""
fake = FakeTmux([READY, THINKING], exists=True)
s = make_session(tmp_path, fake, clock)
s.ask("ping", timeout=3)
assert (tmp_path / ".dbrain" / "inflight").exists()
def test_ask_clears_inflight_on_success(tmp_path, clock):
rid = "abcd0005"
fake = FakeTmux([READY, _complete(rid)], exists=True)
s = make_session(tmp_path, fake, clock, rid=rid)
s.ask("ping", timeout=60)
assert not (tmp_path / ".dbrain" / "inflight").exists()
def test_ask_sends_prompt_via_buffer_then_enter(tmp_path, clock):
rid = "abcd0006"
fake = FakeTmux([READY, _complete(rid)], exists=True)
s = make_session(tmp_path, fake, clock, rid=rid)
s.ask("do the thing", timeout=60)
assert "paste-buffer" in fake.sent_subcommands()
assert any(c[-1] == "Enter" for c in fake.sent_keys())
# ── health ──────────────────────────────────────────────────────────────
def test_is_healthy_true_when_session_exists(tmp_path, clock):
fake = FakeTmux([READY], exists=True)
s = make_session(tmp_path, fake, clock)
assert s.is_healthy() is True
def test_is_healthy_false_when_absent(tmp_path, clock):
fake = FakeTmux([READY], exists=False)
s = make_session(tmp_path, fake, clock)
assert s.is_healthy() is False
def test_kill_sends_kill_session(tmp_path, clock):
fake = FakeTmux([READY], exists=True)
s = make_session(tmp_path, fake, clock)
s.kill()
assert "kill-session" in fake.sent_subcommands()
# ── optional markers (wrap=False) + idle-based completion ──────────────────
class FakeTmuxText(FakeTmux):
"""FakeTmux that also records text streamed to load-buffer."""
def __init__(self, *args, **kwargs) -> None:
super().__init__(*args, **kwargs)
self.texts: list[str] = []
def __call__(self, args, **kwargs): # noqa: ANN001
if kwargs.get("input") is not None:
self.texts.append(kwargs["input"])
return super().__call__(args, **kwargs)
def test_ask_wrap_false_does_not_append_marker_instruction(tmp_path, clock):
fake = FakeTmuxText(
[READY, THINKING, "ответ\n" + READY, "ответ\n" + READY], exists=True
)
(tmp_path / ".dbrain").mkdir()
(tmp_path / ".dbrain" / "ready").touch()
s = make_session(tmp_path, fake, clock)
s.ask("/clear", timeout=30, wrap=False)
assert fake.texts, "prompt was not streamed to the pane"
assert "<<<R:" not in fake.texts[0]
assert "When done" not in fake.texts[0]
def test_ask_wrap_false_completes_on_idle(tmp_path, clock):
fake = FakeTmuxText(
[READY, THINKING, THINKING, "ответ модели\n" + READY, "ответ модели\n" + READY],
exists=True,
)
(tmp_path / ".dbrain").mkdir()
(tmp_path / ".dbrain" / "ready").touch()
s = make_session(tmp_path, fake, clock)
res = s.ask("сделай дело", timeout=30, wrap=False)
assert res.ok, res
assert "ответ модели" in (res.reply or "")
assert "bypass permissions" not in (res.reply or "")
def test_ask_wrap_true_still_appends_markers(tmp_path, clock):
rid = "rid00001"
fake = FakeTmuxText([READY, _complete(rid)], exists=True)
(tmp_path / ".dbrain").mkdir()
(tmp_path / ".dbrain" / "ready").touch()
s = make_session(tmp_path, fake, clock)
res = s.ask("ping", timeout=30)
assert res.ok and res.reply == "PONG"
assert fake.texts and f"<<<R:{rid}>>>" in fake.texts[0]
# ── steering: inject input into a LIVE turn (no exclusive lock) ─────────────
def test_steer_sends_text_while_lock_is_held(tmp_path, clock):
"""steer() must work WHILE an ask() holds the pane lock — it types into
the live turn, so it must not take the blocking lock (no deadlock)."""
import fcntl
import os
fake = FakeTmuxText([READY], exists=True)
s = make_session(tmp_path, fake, clock)
lock_fd = os.open(tmp_path / ".dbrain" / "pane.lock", os.O_CREAT | os.O_RDWR)
fcntl.flock(lock_fd, fcntl.LOCK_EX) # simulate an in-flight ask()
try:
s.steer("уточнение: пиши короче")
finally:
fcntl.flock(lock_fd, fcntl.LOCK_UN)
os.close(lock_fd)
assert fake.texts and "уточнение" in fake.texts[0]
assert fake.enter_count() >= 1
def test_interrupt_sends_escape(tmp_path, clock):
"""interrupt() uses the TUI-native Escape (stops the current response);
C-c is reserved for the stall path (double C-c would begin app exit)."""
fake = FakeTmux([READY], exists=True)
s = make_session(tmp_path, fake, clock)
s.interrupt()
assert any(c[-1] == "Escape" for c in fake.sent_keys())
assert not any(c[-1] == "C-c" for c in fake.sent_keys())
def test_is_turn_active_reflects_lock_state(tmp_path, clock):
import fcntl
import os
fake = FakeTmux([READY], exists=True)
s = make_session(tmp_path, fake, clock)
assert s.is_turn_active() is False # lock free → no ask in flight
lock_fd = os.open(tmp_path / ".dbrain" / "pane.lock", os.O_CREAT | os.O_RDWR)
fcntl.flock(lock_fd, fcntl.LOCK_EX)
try:
assert s.is_turn_active() is True
finally:
fcntl.flock(lock_fd, fcntl.LOCK_UN)
os.close(lock_fd)
# ── runtime privacy: the pane transcript is owner-only ──────────────────
def test_runtime_dir_is_owner_only(tmp_path, clock):
fake = FakeTmux([READY], exists=False)
make_session(tmp_path, fake, clock)
mode = (tmp_path / ".dbrain").stat().st_mode & 0o777
assert mode == 0o700
def test_pane_log_precreated_owner_only_before_pipe(tmp_path, clock):
# pipe-pane appends the FULL Claude transcript via `cat >>` under the
# tmux server's umask — the file must ALREADY be 0600 when pipe-pane
# starts, not fixed up afterwards.
log = tmp_path / ".dbrain" / "pane.log"
seen = {}
class Spy(FakeTmux):
def __call__(self, args, **kwargs): # noqa: ANN001
if len(args) > 1 and args[1] == "pipe-pane":
seen["mode_at_pipe"] = (
log.stat().st_mode & 0o777 if log.exists() else None
)
return super().__call__(args, **kwargs)
s = make_session(tmp_path, Spy([READY], exists=False), clock)
s.ensure_session()
assert seen["mode_at_pipe"] == 0o600
assert (log.stat().st_mode & 0o777) == 0o600
# ── steering gate: maintenance turns must not swallow user input ────────
def _hold_pane_lock(s):
import fcntl
fh = open(s._pane_lock, "w")
fcntl.flock(fh, fcntl.LOCK_EX)
return fh
def test_is_steerable_turn_distinguishes_chat_from_maintenance(tmp_path, clock):
s = make_session(tmp_path, FakeTmux([READY]), clock)
inflight = tmp_path / ".dbrain" / "inflight"
assert s.is_steerable_turn() is False # idle: nothing to steer
fh = _hold_pane_lock(s)
try:
# lock held but no inflight → startup/recovery/control, not a turn
assert s.is_steerable_turn() is False
inflight.write_text("rid12345\n0.0\n")
assert s.is_steerable_turn() is True # a chat turn
inflight.write_text("maint-daily\n0.0\n")
assert s.is_steerable_turn() is False # the nightly pipeline
finally:
fh.close()
def test_inflight_claimed_before_session_startup(tmp_path, clock):
# A stale inflight left by a timed-out chat turn must not misrepresent
# the new holder to the steering gate while session startup (up to
# startup_timeout) is still running.
inflight = tmp_path / ".dbrain" / "inflight"
seen = {}
class Spy(FakeTmux):
def __call__(self, args, **kwargs): # noqa: ANN001
if len(args) > 1 and args[1] == "new-session":
seen["at_startup"] = (
inflight.read_text() if inflight.exists() else None
)
return super().__call__(args, **kwargs)
fake = Spy([READY, READY, _complete("rid00001")], exists=False)
s = make_session(tmp_path, fake, clock)
inflight.write_text("stale-chat-rid\n0.0\n") # leftover from a timeout
s.ask("nightly run", request_id="maint-process")
assert seen["at_startup"] is not None
assert seen["at_startup"].startswith("maint-process")
def test_ask_dismisses_feedback_survey_instead_of_stalling(tmp_path, clock):
# Claude Code periodically shows "How is Claude doing this session?" —
# it polluted the chrome, the stall detector fired Escape and the user
# got a session error. The session must press 0 (Dismiss) and carry on.
survey = (
"● How is Claude doing this session? (optional)\n"
" 1: Bad 2: Fine 3: Good 0: Dismiss\n" + READY
)
fake = FakeTmux(
[READY, survey, THINKING, _complete("rid00001")], exists=True
)
s = make_session(tmp_path, fake, clock)
res = s.ask("привет")
assert res.status == "ok"
pressed = [c for c in fake.sent_keys() if c[-1] == "0"]
assert pressed, "survey was not dismissed with 0"
escapes = [c for c in fake.sent_keys() if c[-1] == "Escape"]
assert not escapes, "stall interrupt fired instead of dismissing survey"
def test_growing_pane_log_prevents_false_stall(tmp_path, clock):
# Version-proof liveness: even if a future spinner format is
# unrecognized, a transcript that keeps growing means the brain is
# working — it must not be killed as a stall.
log = tmp_path / ".dbrain" / "pane.log"
log.parent.mkdir(parents=True, exist_ok=True)
log.write_text("")
busy = "thinking, but with a spinner we do not recognize\n"
fake = FakeTmux([READY] + [busy] * 20 + [_complete("rid00001")], exists=True)
s = make_session(tmp_path, fake, clock) # stall_timeout=10, poll=1
def grow_sleep(seconds: float) -> None:
clock["now"] += seconds
with log.open("a") as f:
f.write("x" * 100) # transcript advancing → alive
s._sleep = grow_sleep
res = s.ask("long task")
assert res.status == "ok"
assert not any(c[-1] in ("Escape", "C-c") for c in fake.sent_keys())
def test_static_pane_log_and_no_spinner_still_stalls(tmp_path, clock):
# The fallback must not disable stall detection: a genuinely wedged
# turn (no spinner, transcript frozen) still gets interrupted.
log = tmp_path / ".dbrain" / "pane.log"
log.parent.mkdir(parents=True, exist_ok=True)
log.write_text("frozen")
busy = "no spinner, no markers, nothing changing\n"
fake = FakeTmux([READY] + [busy] * 40, exists=True)
s = make_session(tmp_path, fake, clock)
res = s.ask("x", timeout=600)
assert res.status == "error"
assert "stall" in (res.detail or "").lower()