cc-session-control 0.7.0__tar.gz → 0.7.2__tar.gz

{cc_session_control-0.7.0/src/cc_session_control.egg-info → cc_session_control-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cc-session-control
-Version: 0.7.0
+Version: 0.7.2
 Summary: TUI manager for Claude Code sessions and Remote Control
 Author: dzshzx
 License-Expression: MIT
@@ -104,6 +104,7 @@ csctl skill uninstall
 
 # Options
 csctl --workspace ~/projects   # Override workspace root
+csctl --theme light            # Force the TUI palette (auto/dark/light)
 csctl --version
 ```
 
@@ -114,6 +115,7 @@ csctl --version
 | `CSCTL_WORKSPACE` | `~/workspace` | Workspace root directory |
 | `CSCTL_RC_SESSION` | `rc` | tmux session name for RC servers |
 | `CSCTL_RC_STAGGER` | `2` | Seconds between starting RC servers |
+| `CSCTL_THEME` | `auto` | TUI palette: `auto` (detect the terminal background via OSC 11 / `$COLORFGBG`) / `dark` / `light`. tmux typically doesn't answer the OSC 11 query, so inside tmux `auto` falls back to `dark` — set this (or `--theme`) explicitly for a light terminal |
 | `XDG_CONFIG_HOME` | `~/.config` | Config directory base |
 
 RC auto-start list is stored at `$XDG_CONFIG_HOME/csctl/rc-enabled`.

{cc_session_control-0.7.0 → cc_session_control-0.7.2}/README.md

@@ -81,6 +81,7 @@ csctl skill uninstall
 
 # Options
 csctl --workspace ~/projects   # Override workspace root
+csctl --theme light            # Force the TUI palette (auto/dark/light)
 csctl --version
 ```
 
@@ -91,6 +92,7 @@ csctl --version
 | `CSCTL_WORKSPACE` | `~/workspace` | Workspace root directory |
 | `CSCTL_RC_SESSION` | `rc` | tmux session name for RC servers |
 | `CSCTL_RC_STAGGER` | `2` | Seconds between starting RC servers |
+| `CSCTL_THEME` | `auto` | TUI palette: `auto` (detect the terminal background via OSC 11 / `$COLORFGBG`) / `dark` / `light`. tmux typically doesn't answer the OSC 11 query, so inside tmux `auto` falls back to `dark` — set this (or `--theme`) explicitly for a light terminal |
 | `XDG_CONFIG_HOME` | `~/.config` | Config directory base |
 
 RC auto-start list is stored at `$XDG_CONFIG_HOME/csctl/rc-enabled`.

{cc_session_control-0.7.0 → cc_session_control-0.7.2}/src/cc_session_control/__init__.py

@@ -1,3 +1,3 @@
 """cc-session-control — TUI manager for Claude Code sessions and Remote Control."""
 
-__version__ = "0.7.0"
+__version__ = "0.7.2"

{cc_session_control-0.7.0 → cc_session_control-0.7.2}/src/cc_session_control/app.py

@@ -10,6 +10,7 @@ from typing import TYPE_CHECKING, Protocol, runtime_checkable
 
 import urwid
 
+from . import theme
 from .data import proc
 from .data.snapshot import WorldSnapshot, build_world_snapshot
 from .views.agents import AgentsView
@@ -47,28 +48,6 @@ class TabView(Protocol):
     def handle_key(self, key: str) -> None: ...
     def captures_text(self) -> bool: ...  # True while a text mode owns EVERY key (incl. tab/q)
 
-# 6-tuple: (name, fg_16, bg_16, mono, fg_256, bg_256)
-# ONE semantic set — views reference these names only (no per-tab duplicates;
-# the old rc_running/rc_stopped were aliases of alive/dead and are gone).
-# 256-color foregrounds are kept ≥ 4.5:1 against their background (WCAG-AA-ish,
-# checked via relative luminance): #aaa/#111 ≈ 8.1, #7ab/#111 ≈ 7.4,
-# #9cc/#181818 ≈ 10.0, #bbb/#111 ≈ 9.8, #d66/#111 ≈ 5.5.
-PALETTE = [
-    ("header",      "white,bold",  "black", "bold",     "#fff,bold",  "#111"),
-    ("footer",      "light gray",  "black", None,       "#aaa",       "#111"),
-    ("tab_on",      "white,bold",  "dark cyan", "bold,standout", "#fff,bold", "#068"),
-    ("tab_off",     "light cyan",  "black", None,       "#7ab",       "#111"),
-    ("alive",       "light green", "black", None,       "#6d6",       "#111"),
-    ("status_busy", "light green,bold", "black", "bold", "#6d6,bold", "#111"),
-    ("status_err",  "light red",   "black", None,       "#d66",       "#111"),
-    ("dead",        "light gray",  "black", None,       "#ccc",       "#111"),
-    ("selected",    "white,bold",  "dark cyan", "standout", "#fff,bold", "#068"),
-    ("notify",      "yellow,bold", "black", "bold",     "#ff0,bold",  "#111"),
-    ("status",      "light gray",  "black", None,       "#bbb",       "#111"),
-    ("body",        "light gray",  "black", None,       "#ccc",       "#111"),
-    ("col_header",  "dark cyan",   "black", None,       "#9cc",       "#181818"),
-]
-
 # Launcher-first order (ADR-0001): startup lands on 项目 (the tmux-first
 # dispatch entry), then 会话 / 后台. In lockstep with `self.views` below.
 TAB_NAMES = ["项目", "会话", "后台"]
@@ -80,6 +59,10 @@ FOOTER_PREFIX = " Tab 切换 · q 退出 · r 刷新 · "
 
 
 def _make_screen() -> urwid.raw_display.Screen:
+    # The theme query (OSC 11) runs here, before `loop.run()` puts the tty
+    # into urwid's hands; the palette itself lives in `theme.py` (ONE semantic
+    # attr set, dark/light generated from a single spec).
+    mode = theme.detect_mode()
     screen = urwid.raw_display.Screen()
     try:
         curses.setupterm()
@@ -88,7 +71,7 @@ def _make_screen() -> urwid.raw_display.Screen:
             screen.set_terminal_properties(colors=256)
     except Exception:
         pass
-    screen.register_palette(PALETTE)
+    screen.register_palette(theme.palette(mode))
     return screen
 
 

{cc_session_control-0.7.0 → cc_session_control-0.7.2}/src/cc_session_control/cli.py

@@ -17,6 +17,10 @@ def _build_parser() -> argparse.ArgumentParser:
     )
     parser.add_argument("--version", action="version", version=f"csctl {__version__}")
     parser.add_argument("--workspace", type=Path, help="Override workspace root directory")
+    parser.add_argument(
+        "--theme", choices=("auto", "dark", "light"),
+        help="TUI palette (default: auto-detect the terminal background; env CSCTL_THEME)",
+    )
 
     sub = parser.add_subparsers(dest="command")
 
@@ -67,10 +71,12 @@ def _build_parser() -> argparse.ArgumentParser:
     return parser
 
 
-def _apply_workspace(args: argparse.Namespace) -> None:
+def _apply_global_flags(args: argparse.Namespace) -> None:
+    from .config import cfg
     if args.workspace:
-        from .config import cfg
         cfg.workspace = args.workspace
+    if args.theme:
+        cfg.theme = args.theme
 
 
 def _cmd_rc(args: argparse.Namespace) -> None:
@@ -311,7 +317,7 @@ def _cmd_tui(args: argparse.Namespace) -> None:
 def main() -> None:
     parser = _build_parser()
     args = parser.parse_args()
-    _apply_workspace(args)
+    _apply_global_flags(args)
 
     if args.command == "rc":
         _cmd_rc(args)

{cc_session_control-0.7.0 → cc_session_control-0.7.2}/src/cc_session_control/config.py

@@ -18,6 +18,8 @@ class Config:
         self.rc_stagger: int = int(os.environ.get("CSCTL_RC_STAGGER", "2"))
         # Age threshold (days) for the time/global-keyed cleanup strategy.
         self.cleanup_age_days: int = int(os.environ.get("CSCTL_CLEANUP_AGE_DAYS", "14"))
+        # TUI palette: "auto" (detect the terminal background) | "dark" | "light".
+        self.theme: str = os.environ.get("CSCTL_THEME", "auto")
         self._workspace: Path | None = None
 
     @property

{cc_session_control-0.7.0 → cc_session_control-0.7.2}/src/cc_session_control/data/rc.py

@@ -183,6 +183,15 @@ def scan() -> list[RCProject]:
     for name in all_names:
         directory = str(cfg.workspace / name)
         in_windows = name in windows
+        dir_exists = os.path.isdir(directory)
+        if not dir_exists and name not in enabled and not in_windows:
+            # Pure trust residue: the directory is gone and only claude's own
+            # trust record (~/.claude.json) still references it. csctl can't
+            # act on it (no start, and it never edits claude's files), so it
+            # is dropped instead of rendered as a ✖ 缺失 row. Missing-dir
+            # projects that ARE actionable (in the autostart list, or with a
+            # live/dead tmux window) stay listed.
+            continue
         if in_windows:
             status = "running" if _is_alive(name) else "dead"
         else:
@@ -195,7 +204,7 @@ def scan() -> list[RCProject]:
             auto_start=name in enabled,
             rc_at_startup=_read_rc_at_startup(directory),
             spawn_mode=_read_spawn_mode(name),
-            dir_exists=os.path.isdir(directory),
+            dir_exists=dir_exists,
         ))
     return result
 

cc_session_control-0.7.2/src/cc_session_control/theme.py

@@ -0,0 +1,189 @@
+"""Terminal-theme seam: background detection + the dark/light palettes.
+
+Top-level helper like `clipboard.py` — it touches only the controlling tty
+(an OSC 11 background-color query) and the process env; `app._make_screen`
+is the sole consumer. Views keep referencing the ONE semantic attr set; this
+module only decides which fg/bg pair each name resolves to.
+
+Detection order (`detect_mode`): explicit `CSCTL_THEME` (dark/light) →
+OSC 11 tty query → `$COLORFGBG` → dark. The query MUST run before urwid
+takes over the tty — `App.__init__` builds the screen before `loop.run()`,
+so stdin is still in normal mode there.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import select
+import sys
+import termios
+import time
+
+from .config import cfg
+
+Mode = str  # "light" | anything else = dark
+
+# (name, mono, dark (fg16, bg16, fg256, bg256), light (fg16, bg16, fg256, bg256))
+# ONE semantic set, table-driven like `_colspec`/`_keytable`: both palettes are
+# generated from this single spec so their attr names can never diverge.
+# Body-content attrs use bg "default" (inherit the terminal's own background —
+# the adaptive part); only the structural bands (header/footer/tabs/status/
+# notify) and the selection keep an explicit bg. 256-color foregrounds stay
+# ≥ 4.5:1 (WCAG-AA-ish, relative luminance) against the assumed backdrop —
+# dark: near-black (#6d6/#d66 ≈ 5.5+, #aaa ≈ 8.1); light: near-white
+# (#070 ≈ 5.7, #a00 ≈ 7.7, #666 ≈ 5.7, #850/#ddd ≈ 4.7).
+_SPEC: list[tuple[str, str | None, tuple[str, str, str, str], tuple[str, str, str, str]]] = [
+    ("header", "bold",
+     ("white,bold", "black", "#fff,bold", "#111"),
+     ("black,bold", "light gray", "#000,bold", "#ddd")),
+    ("footer", None,
+     ("light gray", "black", "#aaa", "#111"),
+     ("dark gray", "light gray", "#555", "#ddd")),
+    ("tab_on", "bold,standout",
+     ("white,bold", "dark cyan", "#fff,bold", "#068"),
+     ("white,bold", "dark cyan", "#fff,bold", "#068")),
+    ("tab_off", None,
+     ("light cyan", "black", "#7ab", "#111"),
+     ("dark cyan", "light gray", "#067", "#ddd")),
+    ("alive", None,
+     ("light green", "default", "#6d6", "default"),
+     ("dark green", "default", "#070", "default")),
+    ("status_busy", "bold",
+     ("light green,bold", "default", "#6d6,bold", "default"),
+     ("dark green,bold", "default", "#070,bold", "default")),
+    ("status_err", None,
+     ("light red", "default", "#d66", "default"),
+     ("dark red", "default", "#a00", "default")),
+    ("dead", None,
+     ("light gray", "default", "#ccc", "default"),
+     ("dark gray", "default", "#666", "default")),
+    ("selected", "standout",
+     ("white,bold", "dark cyan", "#fff,bold", "#068"),
+     ("white,bold", "dark cyan", "#fff,bold", "#068")),
+    ("notify", "bold",
+     ("yellow,bold", "black", "#ff0,bold", "#111"),
+     ("brown,bold", "light gray", "#850,bold", "#ddd")),
+    ("status", None,
+     ("light gray", "black", "#bbb", "#111"),
+     ("dark gray", "light gray", "#444", "#ddd")),
+    ("body", None,
+     ("light gray", "default", "#ccc", "default"),
+     ("black", "default", "#222", "default")),
+    ("col_header", None,
+     ("dark cyan", "default", "#9cc", "default"),
+     ("dark cyan", "default", "#067", "default")),
+]
+
+
+def palette(mode: Mode) -> list[tuple[str, str, str, str | None, str, str]]:
+    """The urwid 6-tuple palette (name, fg16, bg16, mono, fg256, bg256)."""
+    out = []
+    for name, mono, dark, light in _SPEC:
+        fg16, bg16, fg256, bg256 = light if mode == "light" else dark
+        out.append((name, fg16, bg16, mono, fg256, bg256))
+    return out
+
+
+def detect_mode() -> Mode:
+    """`CSCTL_THEME` override → OSC 11 query → `$COLORFGBG` → dark."""
+    forced = cfg.theme.strip().lower()
+    if forced in ("dark", "light"):
+        return forced
+    rgb = _query_bg_rgb()
+    if rgb is not None:
+        return _mode_from_rgb(*rgb)
+    return _parse_colorfgbg(os.environ.get("COLORFGBG", "")) or "dark"
+
+
+# Reply looks like `ESC]11;rgb:1111/1111/1111 BEL` (xterm also emits `rgba:`
+# and 1-4 hex digits per channel; terminator is BEL or ST `ESC \`).
+_OSC11_RGB = re.compile(r"rgba?:([0-9a-fA-F]{1,4})/([0-9a-fA-F]{1,4})/([0-9a-fA-F]{1,4})")
+# OSC 11 query + DA1 (Primary Device Attributes) as a SENTINEL: terminals
+# answer queries in order and virtually every terminal answers DA1, so its
+# reply (`ESC[?...c`) means "the OSC 11 answer, if any, has already arrived".
+# Terminals that ignore OSC 11 (tmux 3.7 without an explicit bg — measured
+# 0.3ms — the common csctl case) return in one round-trip instead of eating
+# the full timeout on EVERY startup. Reading through to the DA1 reply also
+# keeps the tty buffer clean: no reply bytes are left over to leak into urwid
+# as phantom keys.
+_QUERY = b"\x1b]11;?\x07\x1b[c"
+_DA1_REPLY = re.compile(r"\x1b\[\?[0-9;]*c")
+# Hard cap only — with the sentinel, any real terminal answers in one RTT;
+# this bounds fake ptys that answer neither query.
+_REPLY_TIMEOUT = 0.25
+
+
+def _parse_osc11_reply(buf: str) -> tuple[float, float, float] | None:
+    m = _OSC11_RGB.search(buf)
+    if not m:
+        return None
+
+    def chan(h: str) -> float:
+        return int(h, 16) / (16 ** len(h) - 1)
+
+    return chan(m.group(1)), chan(m.group(2)), chan(m.group(3))
+
+
+def _mode_from_rgb(r: float, g: float, b: float) -> Mode:
+    lum = 0.2126 * r + 0.7152 * g + 0.0722 * b
+    return "light" if lum > 0.5 else "dark"
+
+
+def _parse_colorfgbg(value: str) -> Mode | None:
+    """rxvt/konsole convention: "fg;bg" or "fg;default;bg".
+
+    vim's rule for the bg code: 0-6 and 8 mean a dark background."""
+    parts = value.split(";")
+    if len(parts) < 2:
+        return None
+    try:
+        bg = int(parts[-1])
+    except ValueError:
+        return None
+    return "dark" if bg in (0, 1, 2, 3, 4, 5, 6, 8) else "light"
+
+
+def _query_bg_rgb(timeout: float = _REPLY_TIMEOUT) -> tuple[float, float, float] | None:
+    """Ask the terminal its background color via OSC 11; None on any failure."""
+    try:
+        if not (sys.stdin.isatty() and sys.stdout.isatty()):
+            return None
+        return _query_bg_rgb_on(sys.stdin.fileno(), sys.stdout.fileno(), timeout)
+    except Exception:
+        return None
+
+
+def _query_bg_rgb_on(
+    in_fd: int, out_fd: int, timeout: float
+) -> tuple[float, float, float] | None:
+    """The fd-level query — separated so tests can drive a bare pty pair
+    (pytest's capture owns `sys.stdin`/`sys.stdout` during a test, so the
+    wrapper above cannot be exercised end-to-end). May raise; the wrapper
+    swallows."""
+    old = termios.tcgetattr(in_fd)
+    try:
+        # Raw enough to read the reply: no line buffering, no echo (the reply
+        # bytes must not be painted onto the screen). Set directly instead of
+        # via tty.setcbreak, whose ECHO handling changed across 3.12.x.
+        new = termios.tcgetattr(in_fd)
+        new[3] &= ~(termios.ICANON | termios.ECHO)
+        termios.tcsetattr(in_fd, termios.TCSANOW, new)
+        os.write(out_fd, _QUERY)
+        buf = ""
+        deadline = time.monotonic() + timeout
+        # Stop on the DA1 sentinel, NOT on the OSC terminator — see _QUERY.
+        while not _DA1_REPLY.search(buf):
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                break
+            ready, _, _ = select.select([in_fd], [], [], remaining)
+            if not ready:
+                break
+            buf += os.read(in_fd, 128).decode("ascii", "ignore")
+        return _parse_osc11_reply(buf)
+    finally:
+        try:
+            termios.tcsetattr(in_fd, termios.TCSADRAIN, old)
+        except Exception:
+            pass

{cc_session_control-0.7.0 → cc_session_control-0.7.2}/src/cc_session_control/views/rc.py

@@ -179,8 +179,8 @@ class RCView(ListTabView):
         sections=("项目操作（仅对「项目」行生效）:", "批量操作:"),
         suffix=(
             "目录缺失（✖ 缺失）:",
-            "  项目目录已删除，但 claude 的信任记录（~/.claude.json）或自启列表仍引用它。",
-            "  csctl 不改写 claude 的文件；用 a 键可将其移出自启列表，信任记录需手动清理。",
+            "  项目目录已删除，但自启列表仍引用它（或其远控服务还在跑）；用 a 键移出自启列表。",
+            "  只剩 claude 信任记录（~/.claude.json）引用的已删项目不再显示；信任记录需手动清理。",
             "",
             "RC 服务（只读）:",
             "  外部服务只展示，不接管、不重启。",

{cc_session_control-0.7.0 → cc_session_control-0.7.2/src/cc_session_control.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cc-session-control
-Version: 0.7.0
+Version: 0.7.2
 Summary: TUI manager for Claude Code sessions and Remote Control
 Author: dzshzx
 License-Expression: MIT
@@ -104,6 +104,7 @@ csctl skill uninstall
 
 # Options
 csctl --workspace ~/projects   # Override workspace root
+csctl --theme light            # Force the TUI palette (auto/dark/light)
 csctl --version
 ```
 
@@ -114,6 +115,7 @@ csctl --version
 | `CSCTL_WORKSPACE` | `~/workspace` | Workspace root directory |
 | `CSCTL_RC_SESSION` | `rc` | tmux session name for RC servers |
 | `CSCTL_RC_STAGGER` | `2` | Seconds between starting RC servers |
+| `CSCTL_THEME` | `auto` | TUI palette: `auto` (detect the terminal background via OSC 11 / `$COLORFGBG`) / `dark` / `light`. tmux typically doesn't answer the OSC 11 query, so inside tmux `auto` falls back to `dark` — set this (or `--theme`) explicitly for a light terminal |
 | `XDG_CONFIG_HOME` | `~/.config` | Config directory base |
 
 RC auto-start list is stored at `$XDG_CONFIG_HOME/csctl/rc-enabled`.

{cc_session_control-0.7.0 → cc_session_control-0.7.2}/src/cc_session_control.egg-info/SOURCES.txt

@@ -8,6 +8,7 @@ src/cc_session_control/cli.py
 src/cc_session_control/clipboard.py
 src/cc_session_control/config.py
 src/cc_session_control/models.py
+src/cc_session_control/theme.py
 src/cc_session_control.egg-info/PKG-INFO
 src/cc_session_control.egg-info/SOURCES.txt
 src/cc_session_control.egg-info/dependency_links.txt
@@ -57,4 +58,5 @@ tests/test_sessions.py
 tests/test_skill_ops.py
 tests/test_smoke.py
 tests/test_snapshot.py
+tests/test_theme.py
 tests/test_views.py

{cc_session_control-0.7.0 → cc_session_control-0.7.2}/tests/test_cli.py

@@ -96,3 +96,17 @@ def test_prune_sweep_zombies_refuses_without_proc(tmp_path, monkeypatch, capsys)
     out = capsys.readouterr().out
     assert "Refused" in out
     assert os.path.exists(os.path.join(sessions_dir, "1.json"))  # nothing removed
+
+
+def test_theme_flag_sets_cfg(monkeypatch):
+    monkeypatch.setattr(cfg, "theme", "auto")
+    args = cli._build_parser().parse_args(["--theme", "light"])
+    cli._apply_global_flags(args)
+    assert cfg.theme == "light"
+
+
+def test_theme_flag_absent_keeps_cfg(monkeypatch):
+    monkeypatch.setattr(cfg, "theme", "auto")
+    args = cli._build_parser().parse_args([])
+    cli._apply_global_flags(args)
+    assert cfg.theme == "auto"

{cc_session_control-0.7.0 → cc_session_control-0.7.2}/tests/test_rc.py

@@ -204,21 +204,27 @@ def test_scan_populates_spawn_mode(tmp_path, monkeypatch):
 
 
 def test_scan_marks_missing_directory(tmp_path, monkeypatch):
-    """A trusted/enabled project whose workspace dir is gone stays listed
-    (claude.json / rc-enabled still reference it) but gets dir_exists=False."""
+    """A missing-dir project stays listed (dir_exists=False) only while it is
+    still actionable — in the autostart list or holding a tmux window. Pure
+    trust residue (only ~/.claude.json references the deleted dir) is dropped:
+    csctl can't act on it and never edits claude's files."""
     ws = tmp_path / "workspace"
     (ws / "alive").mkdir(parents=True)
     cj = _write_claude_json(tmp_path, {
         str(ws / "alive"): {"hasTrustDialogAccepted": True},
         str(ws / "deleted"): {"hasTrustDialogAccepted": True},
+        str(ws / "gone-running"): {"hasTrustDialogAccepted": True},
     })
     monkeypatch.setattr(rc.cfg, "claude_json", cj)
     monkeypatch.setattr(rc.cfg, "workspace", ws)
     monkeypatch.setattr(rc, "list_enabled", lambda: ["gone-enabled"])
-    monkeypatch.setattr(rc, "_tmux_windows", lambda: [])
+    monkeypatch.setattr(rc, "_tmux_windows", lambda: ["gone-running"])
+    monkeypatch.setattr(rc, "_is_alive", lambda name: True)
 
     rows = {p.name: p for p in rc.scan()}
-    assert set(rows) == {"alive", "deleted", "gone-enabled"}
+    assert set(rows) == {"alive", "gone-enabled", "gone-running"}
+    assert "deleted" not in rows                     # trust-only residue hidden
     assert rows["alive"].dir_exists is True
-    assert rows["deleted"].dir_exists is False       # stale trust entry
     assert rows["gone-enabled"].dir_exists is False  # stale rc-enabled entry
+    assert rows["gone-running"].dir_exists is False  # window survives dir removal
+    assert rows["gone-running"].status == "running"

cc_session_control-0.7.2/tests/test_theme.py

@@ -0,0 +1,178 @@
+"""Adaptive terminal theme: palette generation + background detection."""
+
+from __future__ import annotations
+
+import os
+import threading
+import time
+
+import pytest
+
+from cc_session_control import theme
+from cc_session_control.config import cfg
+
+# The ONE semantic attr set views reference (see views/*).
+EXPECTED_NAMES = {
+    "header", "footer", "tab_on", "tab_off", "alive", "status_busy",
+    "status_err", "dead", "selected", "notify", "status", "body", "col_header",
+}
+
+
+def test_palettes_share_one_semantic_set() -> None:
+    dark = theme.palette("dark")
+    light = theme.palette("light")
+    assert {e[0] for e in dark} == EXPECTED_NAMES
+    assert [e[0] for e in dark] == [e[0] for e in light]
+
+
+def test_palette_entries_are_urwid_6_tuples() -> None:
+    for entry in theme.palette("dark") + theme.palette("light"):
+        assert len(entry) == 6
+        name, fg16, bg16, _mono, fg256, bg256 = entry
+        for field in (fg16, bg16, fg256, bg256):
+            assert isinstance(field, str) and field, (name, field)
+
+
+def test_unknown_mode_falls_back_to_dark() -> None:
+    assert theme.palette("weird") == theme.palette("dark")
+
+
+@pytest.mark.parametrize(
+    ("rgb", "expected"),
+    [
+        ((1.0, 1.0, 1.0), "light"),   # white
+        ((0.0, 0.0, 0.0), "dark"),    # black
+        ((0.99, 0.96, 0.89), "light"),  # solarized light #fdf6e3
+        ((0.0, 0.17, 0.21), "dark"),    # solarized dark #002b36
+    ],
+)
+def test_mode_from_rgb(rgb: tuple[float, float, float], expected: str) -> None:
+    assert theme._mode_from_rgb(*rgb) == expected
+
+
+@pytest.mark.parametrize(
+    ("reply", "expected"),
+    [
+        ("\x1b]11;rgb:ffff/ffff/ffff\x07", (1.0, 1.0, 1.0)),
+        ("\x1b]11;rgb:0000/0000/0000\x1b\\", (0.0, 0.0, 0.0)),
+        ("\x1b]11;rgb:ff/00/00\x07", (1.0, 0.0, 0.0)),  # 2-digit channels
+        ("\x1b]11;rgba:ffff/ffff/ffff/ffff\x07", (1.0, 1.0, 1.0)),
+        ("", None),
+        ("\x1b]11;?\x07", None),          # our own query echoed back
+        ("garbage without rgb", None),
+    ],
+)
+def test_parse_osc11_reply(reply: str, expected: tuple | None) -> None:
+    got = theme._parse_osc11_reply(reply)
+    if expected is None:
+        assert got is None
+    else:
+        assert got == pytest.approx(expected)
+
+
+@pytest.mark.parametrize(
+    ("value", "expected"),
+    [
+        ("15;0", "dark"),
+        ("0;15", "light"),
+        ("12;8", "dark"),
+        ("0;default;15", "light"),  # 3-field rxvt form: bg is the LAST field
+        ("0;7", "light"),
+        ("", None),
+        ("15", None),          # single field — no bg
+        ("15;default", None),  # non-numeric bg
+    ],
+)
+def test_parse_colorfgbg(value: str, expected: str | None) -> None:
+    assert theme._parse_colorfgbg(value) == expected
+
+
+def test_detect_mode_env_override_skips_probing(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(cfg, "theme", "LIGHT")
+
+    def boom() -> None:
+        raise AssertionError("forced theme must not probe the tty")
+
+    monkeypatch.setattr(theme, "_query_bg_rgb", boom)
+    assert theme.detect_mode() == "light"
+
+
+def test_detect_mode_uses_osc_reply(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(cfg, "theme", "auto")
+    monkeypatch.setattr(theme, "_query_bg_rgb", lambda: (1.0, 1.0, 1.0))
+    assert theme.detect_mode() == "light"
+
+
+def test_detect_mode_colorfgbg_fallback(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(cfg, "theme", "auto")
+    monkeypatch.setattr(theme, "_query_bg_rgb", lambda: None)
+    monkeypatch.setenv("COLORFGBG", "0;15")
+    assert theme.detect_mode() == "light"
+
+
+def test_detect_mode_defaults_dark(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(cfg, "theme", "auto")
+    monkeypatch.setattr(theme, "_query_bg_rgb", lambda: None)
+    monkeypatch.delenv("COLORFGBG", raising=False)
+    assert theme.detect_mode() == "dark"
+
+
+def test_query_bg_rgb_refuses_non_tty(monkeypatch: pytest.MonkeyPatch) -> None:
+    class NotATty:
+        def isatty(self) -> bool:
+            return False
+
+    monkeypatch.setattr(theme.sys, "stdin", NotATty())
+    assert theme._query_bg_rgb() is None
+
+
+# --- end-to-end against a real pty. Tests drive the fd-level
+# `_query_bg_rgb_on` directly: pytest's capture plugin owns
+# `sys.stdin`/`sys.stdout` during a test, so the isatty wrapper can't be
+# exercised here (it is covered by the non-tty refusal test above). The fake
+# terminal answers on the master side. ---
+
+
+@pytest.fixture
+def pty_pair():
+    master, slave = os.openpty()
+    yield master, slave
+    os.close(master)
+    os.close(slave)
+
+
+def _answer(master: int, reply: bytes) -> None:
+    os.read(master, 64)  # wait until the query arrives
+    os.write(master, reply)
+
+
+def test_query_bg_rgb_end_to_end(pty_pair: tuple[int, int]) -> None:
+    master, slave = pty_pair
+    # xterm-style: OSC 11 answer, then the DA1 sentinel reply.
+    t = threading.Thread(
+        target=_answer, args=(master, b"\x1b]11;rgb:ffff/ffff/ffff\x07\x1b[?1;2c")
+    )
+    t.start()
+    got = theme._query_bg_rgb_on(slave, slave, timeout=5.0)
+    t.join()
+    assert got == pytest.approx((1.0, 1.0, 1.0))
+
+
+def test_query_bg_rgb_da1_sentinel_short_circuits(pty_pair: tuple[int, int]) -> None:
+    master, slave = pty_pair
+    # tmux-style: OSC 11 ignored, only DA1 answered — must return on the
+    # sentinel immediately, NOT sit out the timeout (given generously here so
+    # a cap-hit fails loudly even on a slow CI box).
+    t = threading.Thread(target=_answer, args=(master, b"\x1b[?1;2;4c"))
+    t.start()
+    t0 = time.monotonic()
+    got = theme._query_bg_rgb_on(slave, slave, timeout=5.0)
+    elapsed = time.monotonic() - t0
+    t.join()
+    assert got is None
+    assert elapsed < 2.0
+
+
+def test_query_bg_rgb_times_out_on_silent_pty(pty_pair: tuple[int, int]) -> None:
+    _master, slave = pty_pair
+    assert theme._query_bg_rgb_on(slave, slave, timeout=0.05) is None