handoff-cli 0.3.6__tar.gz → 0.3.7__tar.gz

handoff_cli-0.3.6/README.md → handoff_cli-0.3.7/PKG-INFO

@@ -1,3 +1,12 @@
+Metadata-Version: 2.4
+Name: handoff-cli
+Version: 0.3.7
+Summary: Multi coding-agent task dispatcher — a CLI proxy for claude that sends coding tasks to configurable AI backends
+Requires-Python: >=3.9
+Requires-Dist: pyyaml<7,>=6
+Requires-Dist: textual<3,>=2
+Description-Content-Type: text/markdown
+
 <div align="center">
 <img src="https://raw.githubusercontent.com/dazuiba/handoff/main/docs/assets/handoff-hero.jpg" width="100%" alt="hero">
 
@@ -139,6 +148,15 @@ Dispatching and resuming are the AI's job (`handoff run` / `handoff resume` unde
 
 </details>
 
+<details>
+<summary><b>Can I change the TUI theme?</b></summary>
+
+<br>
+
+Yes. Inside `handoff list` and `handoff tail`, press `D` to toggle between `textual-dark` and `textual-light`. Your choice is saved automatically to `~/.handoff/tui_state.json` and restored next time you run the TUI.
+
+</details>
+
 <details>
 <summary><b>Can I dispatch several tasks at once?</b></summary>
 

handoff_cli-0.3.6/PKG-INFO → handoff_cli-0.3.7/README.md

@@ -1,12 +1,3 @@
-Metadata-Version: 2.4
-Name: handoff-cli
-Version: 0.3.6
-Summary: Multi coding-agent task dispatcher — a CLI proxy for claude that sends coding tasks to configurable AI backends
-Requires-Python: >=3.9
-Requires-Dist: pyyaml<7,>=6
-Requires-Dist: textual<3,>=2
-Description-Content-Type: text/markdown
-
 <div align="center">
 <img src="https://raw.githubusercontent.com/dazuiba/handoff/main/docs/assets/handoff-hero.jpg" width="100%" alt="hero">
 
@@ -148,6 +139,15 @@ Dispatching and resuming are the AI's job (`handoff run` / `handoff resume` unde
 
 </details>
 
+<details>
+<summary><b>Can I change the TUI theme?</b></summary>
+
+<br>
+
+Yes. Inside `handoff list` and `handoff tail`, press `D` to toggle between `textual-dark` and `textual-light`. Your choice is saved automatically to `~/.handoff/tui_state.json` and restored next time you run the TUI.
+
+</details>
+
 <details>
 <summary><b>Can I dispatch several tasks at once?</b></summary>
 

{handoff_cli-0.3.6 → handoff_cli-0.3.7}/cli/commands/list.py

@@ -47,7 +47,8 @@ def cmd_list(argv: list[str], config: Config):
                 "FROM runs ORDER BY created_at DESC LIMIT 50"
             ).fetchall()
 
-        app = RunListApp(rows, full_cwd, refresh_fn=_refresh_rows)
+        from ..config import read_tui_theme
+        app = RunListApp(rows, full_cwd, refresh_fn=_refresh_rows, theme_name=read_tui_theme())
         app.run(mouse=False)
         conn.close()
 

{handoff_cli-0.3.6 → handoff_cli-0.3.7}/cli/commands/tail.py

@@ -44,5 +44,6 @@ def cmd_tail(argv: list[str], config=None):
         "out_path": out_path,
     }
 
+    from ..config import read_tui_theme
     from ..jsonl_viewer import run_tail
-    run_tail(jsonl_path, prompt_path, result_path, run_info)
+    run_tail(jsonl_path, prompt_path, result_path, run_info, theme_name=read_tui_theme())

{handoff_cli-0.3.6 → handoff_cli-0.3.7}/cli/config.py

@@ -18,6 +18,7 @@ Backend resolution:
 
 from __future__ import annotations
 
+import json
 import os
 import re
 import sys
@@ -35,6 +36,50 @@ except ImportError:
 
 _BACKEND_TYPES_PATH = os.path.join(os.path.dirname(__file__), "backend_types.yaml")
 _USER_CONFIG_TEMPLATE_PATH = os.path.join(os.path.dirname(__file__), "user_config_template.yaml")
+DEFAULT_DARK_THEME = "textual-dark"
+DEFAULT_LIGHT_THEME = "textual-light"
+
+# ── TUI state persistence (theme, independent from config.yaml) ──────────
+
+_TUI_STATE_FILENAME = "tui_state.json"
+
+
+def _tui_state_path() -> str:
+    return os.path.join(user_config_dir(), _TUI_STATE_FILENAME)
+
+
+def read_tui_theme() -> str:
+    """Read the persisted TUI theme name from ``~/.handoff/tui_state.json``.
+
+    Falls back to ``textual-dark`` when the file is missing, corrupt, or
+    the stored theme name is empty / invalid.  Never raises.
+    """
+    path = _tui_state_path()
+    try:
+        if os.path.isfile(path):
+            with open(path, "r") as f:
+                data = json.load(f)
+            theme = data.get("theme", "")
+            if isinstance(theme, str) and theme.strip():
+                return theme.strip()
+    except (OSError, json.JSONDecodeError, ValueError):
+        pass
+    return DEFAULT_DARK_THEME
+
+
+def write_tui_theme(theme: str) -> None:
+    """Persist the TUI theme name to ``~/.handoff/tui_state.json``.
+
+    Best-effort: failures are silently ignored so the app never crashes
+    on a write.
+    """
+    path = _tui_state_path()
+    try:
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        with open(path, "w") as f:
+            json.dump({"theme": theme}, f)
+    except OSError:
+        pass
 
 # Top-level config keys that belong to the mechanism layer or are otherwise
 # removed.  Warn once and ignore.  system_prompt is deliberately absent from

{handoff_cli-0.3.6 → handoff_cli-0.3.7}/cli/jsonl_parser.py

@@ -7,6 +7,8 @@ import json
 from dataclasses import dataclass
 from typing import TextIO
 
+from rich.text import Text
+
 
 @dataclass
 class ParsedEvent:
@@ -160,6 +162,46 @@ def format_event_for_viewer(event: ParsedEvent) -> str | None:
     return f"`{ts}` {kind_mark} {_truncate(event.text)}"
 
 
+def format_event_as_rich(event: ParsedEvent) -> Text | None:
+    """Format one parsed event as a rich Text with styled spans.
+
+    Returns None for result_text/error_text events (handled separately by
+    the viewer as Markdown content).  The returned Text uses colour/emphasis
+    per kind: tool=cyan, text=default, result=green, error=red, task=yellow,
+    info=dim.
+    """
+    if event.kind in ("result_text", "error_text"):
+        return None
+
+    ts = event.ts or " " * 8
+    mark_map = {
+        "tool": "▷",
+        "text": "✎",
+        "result": "✓",
+        "error": "✗",
+        "task": "▶",
+        "info": "·",
+    }
+    colour_map = {
+        "tool": "cyan",
+        "text": "",
+        "result": "green",
+        "error": "red",
+        "task": "yellow",
+        "info": "dim",
+    }
+    mark = mark_map.get(event.kind, " ")
+    colour = colour_map.get(event.kind, "")
+
+    text = Text()
+    text.append(f"{ts:8}", style="dim")
+    text.append(" │ ", style="dim")
+    text.append(mark, style=colour)
+    text.append(" ")
+    text.append(_truncate(event.text))
+    return text
+
+
 def format_event_for_stream(event: ParsedEvent) -> str | None:
     """Return the single-line text stream shown during `handoff run`."""
     if event.kind != "text":

{handoff_cli-0.3.6 → handoff_cli-0.3.7}/cli/jsonl_viewer.py

@@ -1,7 +1,7 @@
 """Shared JSONL viewer for handoff list (detail) and tail commands.
 
-Uses Textual to render Claude stream-json output: compact progress log,
-input prompt (markdown), and final result (markdown). No external cclean dependency.
+Uses Textual to render Claude stream-json output: compact progress log
+(RichLog), input prompt (Markdown), and final result (Markdown).
 
 Modes:
   - static:  list detail page; Escape dismisses back to list
@@ -11,27 +11,54 @@ Modes:
 from __future__ import annotations
 
 import os
+import re
 import asyncio
 from typing import Optional
 
+from markdown_it import MarkdownIt
+from rich.text import Text
 from textual import work
 from textual.app import App, ComposeResult
 from textual.screen import Screen
 from textual.widgets import (
     Footer,
+    Markdown,
+    RichLog,
+    Static,
     TabbedContent,
     TabPane,
-    Static,
 )
 from textual.containers import VerticalScroll
 from textual.binding import Binding
-from .jsonl_parser import ParsedEvent, format_event_for_viewer, read_events
+from .config import read_tui_theme
+from .jsonl_parser import ParsedEvent, format_event_as_rich, read_events
+from .tui import HandoffTuiApp
 
 
 # ═══════════════════════════════════════════════════════════════════════════════
 # JsonlViewerScreen
 # ═══════════════════════════════════════════════════════════════════════════════
 
+
+def _markdown_parser_factory() -> MarkdownIt:
+    """Create a Markdown parser with all link/image/autolink tokens disabled.
+
+    Textual 2.1.2's Markdown renderer calls ``Style.from_meta({"@click": action})``
+    for every ``link_open`` / ``image`` token.  The resulting meta data can contain
+    arbitrary strings (e.g. ``/tmp/a:1`` from ``[x](/tmp/a:1)``) which crash
+    Python's marshal with ``ValueError: bad marshal data (unknown type code)``
+    downstream in Textual's render pipeline.
+
+    Disabling the relevant MarkdownIt rules ensures such tokens are never emitted
+    and the input is rendered as plain text instead.
+    """
+    md = MarkdownIt("gfm-like", options_update={"linkify": False})
+    # Explicit markdown links e.g. [text](...), images e.g. ![alt](...),
+    # and autolinks e.g. <https://...>
+    md.disable(["link", "image", "autolink"])
+    return md
+
+
 class JsonlViewerScreen(Screen):
     """Shared JSONL viewer screen for handoff list (detail) and tail.
 
@@ -42,22 +69,26 @@ class JsonlViewerScreen(Screen):
     """
 
     BINDINGS = [
+        # Tab navigation (shown)
+        Binding("tab", "next_tab", "Next", show=True),
+        Binding("shift+tab", "prev_tab", "Prev", show=True),
+        # Actions (shown, ordered by frequency of use)
         Binding("escape", "back", "← Back", show=True),
-        Binding("o", "go_resume", "Open in Claude", show=True),
-        Binding("c", "copy_session", "Copy Session", show=True),
+        Binding("o", "go_resume", "Open", show=True),
+        Binding("c", "copy_session", "Copy", show=True),
         Binding("q", "quit", "Quit", show=True),
-        Binding("tab", "next_tab", "Next Tab", show=True),
-        Binding("shift+tab", "prev_tab", "Prev Tab", show=True),
-        Binding("1", "show_tab('stream')", "Stream", show=True),
-        Binding("2", "show_tab('output')", "Output", show=True),
-        Binding("3", "show_tab('prompt')", "Prompt", show=True),
-        Binding("4", "show_tab('result')", "Result", show=True),
-        Binding("up,k", "scroll_active('up')", "Scroll up", show=False),
-        Binding("down,j", "scroll_active('down')", "Scroll down", show=False),
-        Binding("pageup", "scroll_active('page_up')", "Page up", show=False),
-        Binding("pagedown", "scroll_active('page_down')", "Page down", show=False),
-        Binding("home", "scroll_active('home')", "Top", show=False),
-        Binding("end", "scroll_active('end')", "Bottom", show=False),
+        # Numeric tab shortcuts (hidden from Footer, keys still work)
+        Binding("1", "show_tab('stream')", "", show=False),
+        Binding("2", "show_tab('output')", "", show=False),
+        Binding("3", "show_tab('prompt')", "", show=False),
+        Binding("4", "show_tab('result')", "", show=False),
+        # Scrolling (hidden — Textual built-in keymap covers these)
+        Binding("up,k", "scroll_active('up')", "", show=False),
+        Binding("down,j", "scroll_active('down')", "", show=False),
+        Binding("pageup", "scroll_active('page_up')", "", show=False),
+        Binding("pagedown", "scroll_active('page_down')", "", show=False),
+        Binding("home", "scroll_active('home')", "", show=False),
+        Binding("end", "scroll_active('end')", "", show=False),
     ]
 
     def __init__(
@@ -82,9 +113,8 @@ class JsonlViewerScreen(Screen):
         self._last_ts = ""
         self._fpos = 0
         self._out_fpos = 0
+        self._out_buffer = ""      # partial last line buffer for .out parsing
         self._result_text: Optional[str] = None
-        self._stream_raw = ""      # accumulated stream content for incremental update
-        self._out_raw = ""         # accumulated .out.txt content
         self._last_stream_line = ""
         self._poll_interval = 0.5
         # Auto-follow state
@@ -103,52 +133,68 @@ class JsonlViewerScreen(Screen):
         )
         with TabbedContent(initial="stream"):
             with TabPane("1 Stream JSONL", id="stream"):
-                with VerticalScroll(id="stream_scroll"):
-                    yield Static("Loading…", id="stream_text", markup=False)
+                yield RichLog(id="stream_log", auto_scroll=False, highlight=False, markup=False)
             with TabPane("2 Output .out", id="output"):
-                with VerticalScroll(id="output_scroll"):
-                    yield Static("Loading…", id="output_text", markup=False)
+                yield RichLog(id="output_log", auto_scroll=False, highlight=False, markup=False)
             with TabPane("3 Prompt", id="prompt"):
                 with VerticalScroll(id="prompt_scroll"):
-                    yield Static("", id="prompt_text", markup=False)
+                    yield Static("", id="prompt_header")
+                    yield Markdown(
+                        "",
+                        id="prompt_md",
+                        parser_factory=_markdown_parser_factory,
+                        open_links=False,
+                    )
             with TabPane("4 Result", id="result"):
                 with VerticalScroll(id="result_scroll"):
-                    yield Static("", id="result_text", markup=False)
+                    yield Static("", id="result_header")
+                    yield Markdown(
+                        "",
+                        id="result_md",
+                        parser_factory=_markdown_parser_factory,
+                        open_links=False,
+                    )
         yield Footer()
 
     def on_mount(self) -> None:
-        # Load prompt text
+        # ── Prompt tab ──────────────────────────────────────────────────────
         if os.path.isfile(self._p_path):
             try:
                 with open(self._p_path, "r", encoding="utf-8", errors="replace") as f:
                     pt = f.read().strip()
+                self.query_one("#prompt_header", Static).update(
+                    self._header_line("Prompt", self._p_path)
+                )
                 if pt:
-                    self.query_one("#prompt_text", Static).update(
-                        self._text_with_path("Prompt", self._p_path, pt)
-                    )
+                    self.query_one("#prompt_md", Markdown).update(pt)
             except (OSError, UnicodeDecodeError):
                 pass
         else:
-            self.query_one("#prompt_text", Static).update(self._text_with_path("Prompt", self._p_path, ""))
+            self.query_one("#prompt_header", Static).update(
+                self._header_line("Prompt", self._p_path)
+            )
 
-        # Load result text
+        # ── Result tab ──────────────────────────────────────────────────────
         if os.path.isfile(self._r_path):
             try:
                 with open(self._r_path, "r", encoding="utf-8", errors="replace") as f:
                     rt = f.read().strip()
+                self.query_one("#result_header", Static).update(
+                    self._header_line("Result", self._r_path)
+                )
                 if rt:
                     self._result_text = rt
-                    self.query_one("#result_text", Static).update(
-                        self._text_with_path("Result", self._r_path, rt)
-                    )
+                    self.query_one("#result_md", Markdown).update(rt)
             except (OSError, UnicodeDecodeError):
                 pass
         else:
-            self.query_one("#result_text", Static).update(self._text_with_path("Result", self._r_path, ""))
+            self.query_one("#result_header", Static).update(
+                self._header_line("Result", self._r_path)
+            )
 
-        # Load JSONL stream.
-        self._stream_raw = self._header_line("JSONL", self._jl_path)
-        self.query_one("#stream_text", Static).update(self._stream_raw)
+        # ── Stream tab ──────────────────────────────────────────────────────
+        stream_log = self.query_one("#stream_log", RichLog)
+        stream_log.write(Text(self._header_line("JSONL", self._jl_path), style="dim"))
         if os.path.isfile(self._jl_path):
             with open(self._jl_path, "r", encoding="utf-8", errors="replace") as f:
                 f.seek(self._fpos)
@@ -156,13 +202,14 @@ class JsonlViewerScreen(Screen):
                 self._fpos = f.tell()
             self._append_events(events)
 
-        self._out_raw = self._header_line("Output", self._o_path)
-        self.query_one("#output_text", Static).update(self._out_raw)
+        # ── Output tab ──────────────────────────────────────────────────────
+        out_log = self.query_one("#output_log", RichLog)
+        out_log.write(Text(self._header_line("Output", self._o_path), style="dim"))
         self._append_output_from_file()
 
         # Scroll to bottom after initial load
-        self._scroll_to_bottom("stream")
-        self._scroll_to_bottom("output")
+        stream_log.scroll_end(animate=False)
+        out_log.scroll_end(animate=False)
 
         # Start poll worker for all modes (live updates for running runs)
         self._poll_jsonl()
@@ -181,6 +228,8 @@ class JsonlViewerScreen(Screen):
                     self._append_events(events)
                 except (OSError, UnicodeDecodeError):
                     pass
+                except Exception:
+                    pass  # screen may have been unmounted
 
             self._append_output_from_file()
 
@@ -188,24 +237,31 @@ class JsonlViewerScreen(Screen):
             self._sync_auto_follow("stream")
             self._sync_auto_follow("output")
 
-            await asyncio.sleep(self._poll_interval)
+            try:
+                await asyncio.sleep(self._poll_interval)
+            except asyncio.CancelledError:
+                break
 
     def on_unmount(self) -> None:
         """Ensure poll loop exits when screen is removed."""
         self._keep_polling = False
 
     def _sync_auto_follow(self, tab_id: str) -> None:
-        """Update _auto_follow based on current scroll position."""
+        """Update _auto_follow based on current scroll position.
+
+        Both stream and output use RichLog (a ScrollView) directly;
+        no VerticalScroll wrapper to query.
+        """
         try:
-            scroll = self.query_one(f"#{tab_id}_scroll", VerticalScroll)
-            self._auto_follow[tab_id] = scroll.is_vertical_scroll_end
+            rl = self.query_one(f"#{tab_id}_log", RichLog)
+            self._auto_follow[tab_id] = rl.is_vertical_scroll_end
         except Exception:
             pass
 
     def _scroll_to_bottom(self, tab_id: str) -> None:
-        """Scroll stream container to bottom."""
+        """Scroll the log widget to its end."""
         try:
-            self.query_one(f"#{tab_id}_scroll", VerticalScroll).scroll_end(animate=False)
+            self.query_one(f"#{tab_id}_log", RichLog).scroll_end(animate=False)
         except Exception:
             pass
 
@@ -234,31 +290,25 @@ class JsonlViewerScreen(Screen):
     def _header_line(self, label: str, path: str) -> str:
         return f"{label}: {os.path.abspath(os.path.expanduser(path))}"
 
-    def _text_with_path(self, label: str, path: str, body: str) -> str:
-        header = self._header_line(label, path)
-        return f"{header}\n\n{body}" if body else header
-
-    def _append_text_block(self, tab_id: str, text: str) -> None:
-        if not text:
-            return
-        self._sync_auto_follow(tab_id)
-        attr = "_stream_raw" if tab_id == "stream" else "_out_raw"
-        widget_id = "#stream_text" if tab_id == "stream" else "#output_text"
-        current = getattr(self, attr) or ""
-        updated = current + text if current.endswith("\n") or text.startswith("\n") else current + "\n" + text
-        setattr(self, attr, updated)
-        try:
-            self.query_one(widget_id, Static).update(updated)
-        except Exception:
-            return
-
-        new_count = text.count("\n") + (0 if text.endswith("\n") else 1)
-        if self._auto_follow[tab_id]:
-            self._scroll_to_bottom(tab_id)
-            self._pending_new_count[tab_id] = 0
+    @staticmethod
+    def _format_out_line(line: str) -> Text:
+        """Format a single .out.txt line with an optional timestamp gutter.
+
+        Lines starting with ``HH:MM:SS`` get the timestamp rendered dim;
+        lines without a timestamp prefix (e.g. ``RESULT=...``) get an empty
+        8-space gutter for alignment.
+        """
+        m = re.match(r"^(\d{2}:\d{2}:\d{2})\s+(.*)$", line)
+        t = Text()
+        if m:
+            t.append(f"{m.group(1):8}", style="dim")
+            t.append(" │ ", style="dim")
+            t.append(m.group(2))
         else:
-            self._pending_new_count[tab_id] += max(new_count, 1)
-        self._update_info_bar()
+            t.append(f"{'':8}", style="dim")
+            t.append(" │ ", style="dim")
+            t.append(line)
+        return t
 
     def _append_output_from_file(self) -> None:
         if not os.path.isfile(self._o_path):
@@ -267,57 +317,92 @@ class JsonlViewerScreen(Screen):
             size = os.path.getsize(self._o_path)
             if size < self._out_fpos:
                 self._out_fpos = 0
+                self._out_buffer = ""
             with open(self._o_path, "r", encoding="utf-8", errors="replace") as f:
                 f.seek(self._out_fpos)
                 chunk = f.read()
                 self._out_fpos = f.tell()
         except OSError:
             return
-        self._append_text_block("output", chunk)
+
+        # Prepend leftover partial line from the previous read
+        if self._out_buffer:
+            chunk = self._out_buffer + chunk
+            self._out_buffer = ""
+
+        lines = chunk.split("\n")
+        # A chunk that doesn't end with \n means the last line is partial
+        if not chunk.endswith("\n"):
+            self._out_buffer = lines.pop()
+        elif lines and lines[-1] == "":
+            lines.pop()  # trailing empty element from split
+
+        if not lines:
+            return
+
+        self._sync_auto_follow("output")
+
+        try:
+            out_log = self.query_one("#output_log", RichLog)
+            for line in lines:
+                out_log.write(self._format_out_line(line))
+
+            if self._auto_follow["output"]:
+                out_log.scroll_end(animate=False)
+                self._pending_new_count["output"] = 0
+            else:
+                self._pending_new_count["output"] += len(lines)
+        except Exception:
+            return
+
+        self._update_info_bar()
 
     def _append_events(self, events: list[ParsedEvent]) -> None:
         if not events:
             return
 
-        new_lines: list[str] = []
+        rich_lines: list[Text] = []
         for event in events:
+            # result_text / error_text → Markdown tab
             if event.kind in ("result_text", "error_text"):
                 self._result_text = event.text
                 try:
-                    self.query_one("#result_text", Static).update(
-                        self._text_with_path("Result", self._r_path, self._result_text)
+                    self.query_one("#result_header", Static).update(
+                        self._header_line("Result", self._r_path)
                     )
+                    self.query_one("#result_md", Markdown).update(event.text)
                     self.query_one(TabbedContent).active = "result"
                 except Exception:
                     pass
                 continue
 
-            line = format_event_for_viewer(event)
-            if line and line != self._last_stream_line:
-                new_lines.append(line)
-                self._last_stream_line = line
+            line = format_event_as_rich(event)
+            if line is None:
+                continue
+            # Skip line if it's identical to the last one (JSONL dedup)
+            if line.plain == self._last_stream_line:
+                continue
+            self._last_stream_line = line.plain
+            rich_lines.append(line)
 
-        if not new_lines:
+        if not rich_lines:
             return
 
-        # Check if we should auto-follow before updating content
         self._sync_auto_follow("stream")
 
         try:
-            current = self._stream_raw or ""
-            appended = "\n".join(new_lines)
-            self._stream_raw = current + "\n" + appended if current else appended
-            self.query_one("#stream_text", Static).update(self._stream_raw)
+            stream_log = self.query_one("#stream_log", RichLog)
+            for rl in rich_lines:
+                stream_log.write(rl)
+
+            if self._auto_follow["stream"]:
+                stream_log.scroll_end(animate=False)
+                self._pending_new_count["stream"] = 0
+            else:
+                self._pending_new_count["stream"] += len(rich_lines)
         except Exception:
             return
 
-        # Auto-scroll or track pending new content
-        if self._auto_follow["stream"]:
-            self._scroll_to_bottom("stream")
-            self._pending_new_count["stream"] = 0
-        else:
-            self._pending_new_count["stream"] += len(new_lines)
-
         self._update_info_bar()
 
     # ── actions ──────────────────────────────────────────────────────────
@@ -385,22 +470,34 @@ class JsonlViewerScreen(Screen):
     def action_scroll_active(self, direction: str) -> None:
         try:
             active = self.query_one(TabbedContent).active
-            scroll = self.query_one(f"#{active}_scroll", VerticalScroll)
         except Exception:
             return
 
+        if active in ("stream", "output"):
+            # Log tabs use RichLog (a ScrollView) — no VerticalScroll wrapper
+            try:
+                w = self.query_one(f"#{active}_log", RichLog)
+            except Exception:
+                return
+        else:
+            # Markdown tabs use a VerticalScroll wrapper
+            try:
+                w = self.query_one(f"#{active}_scroll", VerticalScroll)
+            except Exception:
+                return
+
         if direction == "up":
-            scroll.scroll_up(animate=False)
+            w.scroll_up(animate=False)
         elif direction == "down":
-            scroll.scroll_down(animate=False)
+            w.scroll_down(animate=False)
         elif direction == "page_up":
-            scroll.scroll_page_up(animate=False)
+            w.scroll_page_up(animate=False)
         elif direction == "page_down":
-            scroll.scroll_page_down(animate=False)
+            w.scroll_page_down(animate=False)
         elif direction == "home":
-            scroll.scroll_home(animate=False)
+            w.scroll_home(animate=False)
         elif direction == "end":
-            scroll.scroll_end(animate=False)
+            w.scroll_end(animate=False)
 
         if active in self._auto_follow:
             self._sync_auto_follow(active)
@@ -413,7 +510,7 @@ class JsonlViewerScreen(Screen):
 # Tail entry point
 # ═══════════════════════════════════════════════════════════════════════════════
 
-class JsonlTailApp(App):
+class JsonlTailApp(HandoffTuiApp):
     """Standalone Textual app for `handoff tail`."""
 
     TITLE = "handoff tail"
@@ -425,13 +522,14 @@ class JsonlTailApp(App):
         out_path: str,
         result_path: str,
         run_info: dict,
+        theme_name: str | None = None,
     ):
         self._a_jl = jsonl_path
         self._a_pp = prompt_path
         self._a_op = out_path
         self._a_rp = result_path
         self._a_ri = run_info
-        super().__init__()
+        super().__init__(theme_name=theme_name)
 
     def on_mount(self) -> None:
         self.push_screen(JsonlViewerScreen(
@@ -442,12 +540,26 @@ class JsonlTailApp(App):
             run_info=self._a_ri,
             mode="follow",
         ))
+        self.apply_initial_theme()
 
 
-def run_tail(jsonl_path: str, prompt_path: str, result_path: str, run_info: dict) -> None:
+def run_tail(
+    jsonl_path: str,
+    prompt_path: str,
+    result_path: str,
+    run_info: dict,
+    theme_name: str | None = None,
+) -> None:
     """Entry point for `handoff tail`."""
     out_path = run_info.get("out_path", "")
-    JsonlTailApp(jsonl_path, prompt_path, out_path, result_path, run_info).run(mouse=False)
+    JsonlTailApp(
+        jsonl_path,
+        prompt_path,
+        out_path,
+        result_path,
+        run_info,
+        theme_name=theme_name,
+    ).run(mouse=False)
 
 
 def make_viewer_screen(

{handoff_cli-0.3.6 → handoff_cli-0.3.7}/cli/tui.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from typing import Optional, Callable
 
-from textual.app import App, ComposeResult
+from textual.app import App, ComposeResult, InvalidThemeError
 from textual.containers import Container
 from textual.screen import Screen
 from textual.widgets import DataTable, Footer, Static
@@ -12,12 +12,50 @@ from textual.binding import Binding
 from textual.coordinate import Coordinate
 from textual.message import Message
 
+from .config import DEFAULT_DARK_THEME, DEFAULT_LIGHT_THEME, read_tui_theme, write_tui_theme
 from .core import format_run_row, task_paths
 
 # Seconds between DB polls for auto-refresh.
 POLL_INTERVAL = 5.0
 
 
+class HandoffTuiApp(App):
+    """Shared Textual app behavior for handoff TUI screens."""
+
+    BINDINGS = [
+        Binding("d", "cycle_theme", "Theme", show=True),
+    ]
+
+    def __init__(self, *args, theme_name: str | None = None, **kwargs):
+        self._initial_theme_name = theme_name or read_tui_theme()
+        super().__init__(*args, **kwargs)
+
+    def apply_initial_theme(self) -> None:
+        self._set_theme(self._initial_theme_name, quiet=False)
+
+    def _set_theme(self, theme_name: str, *, quiet: bool) -> str:
+        try:
+            self.theme = theme_name
+            return theme_name
+        except InvalidThemeError:
+            self.theme = DEFAULT_DARK_THEME
+            if not quiet:
+                self.notify(
+                    f"Unknown theme: {theme_name}. Using {DEFAULT_DARK_THEME}.",
+                    severity="warning",
+                    timeout=3,
+                )
+            return DEFAULT_DARK_THEME
+
+    def action_cycle_theme(self) -> None:
+        next_theme = (
+            DEFAULT_LIGHT_THEME if self.current_theme.dark else DEFAULT_DARK_THEME
+        )
+        applied_theme = self._set_theme(next_theme, quiet=False)
+        write_tui_theme(applied_theme)
+        self.notify(f"Theme saved: {applied_theme}", severity="information", timeout=2)
+
+
 class RunListScreen(Screen):
     """Main screen showing the run list in a DataTable.
 
@@ -30,8 +68,8 @@ class RunListScreen(Screen):
 
     BINDINGS = [
         Binding("right,space", "select_run", "Detail", show=True),
-        Binding("o", "go_resume", "Open in Claude", show=True),
-        Binding("c", "copy_session", "Copy Session", show=True),
+        Binding("o", "go_resume", "Open", show=True),
+        Binding("c", "copy_session", "Copy", show=True),
         Binding("q", "quit", "Quit", show=True),
     ]
 
@@ -273,7 +311,7 @@ class RunListScreen(Screen):
             self._rebuild_table()
 
 
-class RunListApp(App):
+class RunListApp(HandoffTuiApp):
     """Textual app wrapping the run list screen.
 
     Usage:
@@ -296,12 +334,18 @@ class RunListApp(App):
     }
     """
 
-    def __init__(self, rows: list, full_cwd: bool = False, refresh_fn: Callable[[], list] | None = None):
+    def __init__(
+        self,
+        rows: list,
+        full_cwd: bool = False,
+        refresh_fn: Callable[[], list] | None = None,
+        theme_name: str | None = None,
+    ):
         self._rows = rows
         self._full_cwd = full_cwd
         self._refresh_fn = refresh_fn
         self._action_result: Optional[str] = None
-        super().__init__()
+        super().__init__(theme_name=theme_name)
 
     @property
     def action_result(self) -> Optional[str]:
@@ -310,6 +354,7 @@ class RunListApp(App):
     def on_mount(self) -> None:
         screen = RunListScreen(self._rows, self._full_cwd, refresh_fn=self._refresh_fn)
         self.push_screen(screen)
+        self.apply_initial_theme()
 
     def on_screen_dismiss(self, event: Screen.Dismissed) -> None:
         """Capture action result when a screen is dismissed."""

{handoff_cli-0.3.6 → handoff_cli-0.3.7}/docs/configuration.zh-CN.md

@@ -146,5 +146,20 @@ system_prompt: |
 | --- | --- |
 | `system_prompt` | 覆盖内置 system_prompt |
 | `include` | 引用其他 YAML 文件 |
+| `tui.theme` | TUI 主题名；默认 `textual-dark`，可选 `textual-light` 及其他 Textual 内置主题 |
+
+## TUI 主题
+
+`handoff list` 和 `handoff tail` 共用同一份 TUI 主题配置：
+
+```yaml
+tui:
+  theme: textual-dark
+```
+
+- 默认值是 `textual-dark`
+- 常见亮色可用 `textual-light`
+- 运行时可在 TUI 底部按 `D` 在默认深色 / 亮色主题之间切换
+- 如果你填了不存在的主题名，程序会自动回退到 `textual-dark`，不会因为主题配置崩溃
 
 机制层（`cli/backend_types.yaml`）定义了 claude/codex 两种 type 的 `command`、`pty`、`session_flags`、`session_id_flags`、`continue_id_flags`、`resume_flags`。这些是程序行为，不可覆盖——想了解完整启动逻辑请直接读那个文件。

{handoff_cli-0.3.6 → handoff_cli-0.3.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "handoff-cli"
-version = "0.3.6"
+version = "0.3.7"
 description = "Multi coding-agent task dispatcher — a CLI proxy for claude that sends coding tasks to configurable AI backends"
 readme = "README.md"
 requires-python = ">=3.9"

handoff_cli-0.3.7/tests/test_markdown_parser.py

@@ -0,0 +1,158 @@
+#!/usr/bin/env python3
+"""Verify that _markdown_parser_factory suppresses link/image/autolink tokens.
+
+In Textual 2.1.2, ``Style.from_meta({"@click": link_action})`` (called when
+``link_open`` / ``image`` tokens are present) crashes Python's marshal with
+``ValueError: bad marshal data (unknown type code)`` when the href/alt string
+contains characters such as ``:`` (e.g. ``/tmp/a:1`` from ``[x](/tmp/a:1)``).
+
+This test ensures ``_markdown_parser_factory`` from ``cli.jsonl_viewer`` never
+produces those tokens, regardless of content.
+"""
+
+import sys
+import os
+
+# Ensure project root is on sys.path so imports resolve
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from markdown_it import MarkdownIt
+
+from cli.jsonl_viewer import _markdown_parser_factory
+
+
+def _collect_inline_types(md: MarkdownIt, text: str) -> list[str]:
+    """Return all inline token types produced for *text*."""
+    types: list[str] = []
+    for block in md.parse(text):
+        if block.children:
+            for child in block.children:
+                types.append(child.type)
+    return types
+
+
+def test_explicit_link_is_plain_text():
+    """[x](/tmp/a:1) must NOT produce link_open/link_close."""
+    md = _markdown_parser_factory()
+    types = _collect_inline_types(md, "[x](/tmp/a:1)")
+    assert "link_open" not in types, f"link_open present: {types}"
+    assert "link_close" not in types, f"link_close present: {types}"
+    # The entire thing should be a single text token
+    assert "text" in types, f"no text token: {types}"
+    print(f"  [x](/tmp/a:1) -> types={types}  OK")
+
+
+def test_image_is_plain_text():
+    """![alt](/tmp/a.png) must NOT produce an image token."""
+    md = _markdown_parser_factory()
+    types = _collect_inline_types(md, "![alt](/tmp/a.png)")
+    assert "image" not in types, f"image present: {types}"
+    assert "text" in types, f"no text token: {types}"
+    print(f"  ![alt](/tmp/a.png) -> types={types}  OK")
+
+
+def test_autolink_is_plain_text():
+    """<https://example.com> must NOT produce link_open."""
+    md = _markdown_parser_factory()
+    types = _collect_inline_types(md, "<https://example.com>")
+    assert "link_open" not in types, f"link_open present: {types}"
+    assert "text" in types, f"no text token: {types}"
+    print(f"  <https://example.com> -> types={types}  OK")
+
+
+def test_bold_still_works():
+    """**bold** must still produce strong_open/strong_close."""
+    md = _markdown_parser_factory()
+    types = _collect_inline_types(md, "**bold**")
+    assert "strong_open" in types, f"strong_open missing: {types}"
+    assert "strong_close" in types, f"strong_close missing: {types}"
+    print(f"  **bold** -> types={types}  OK")
+
+
+def test_italic_still_works():
+    """*italic* must still produce emphasis tokens."""
+    md = _markdown_parser_factory()
+    types = _collect_inline_types(md, "*italic*")
+    assert "text" in types, f"text missing: {types}"
+    print(f"  *italic* -> types={types}  OK")
+
+
+def test_inline_code_still_works():
+    """`code` must still produce code_inline."""
+    md = _markdown_parser_factory()
+    types = _collect_inline_types(md, "some `code`")
+    assert "code_inline" in types, f"code_inline missing: {types}"
+    print(f"  some `code` -> types={types}  OK")
+
+
+def test_heading_still_works():
+    """# Heading must still produce heading_open block."""
+    md = _markdown_parser_factory()
+    block_types = [t.type for t in md.parse("# Heading")]
+    assert "heading_open" in block_types, f"heading_open missing: {block_types}"
+    print(f"  # Heading -> types={block_types}  OK")
+
+
+def test_lists_still_work():
+    """Bullet lists must still produce list_item_open."""
+    md = _markdown_parser_factory()
+    block_types = [t.type for t in md.parse("- a\n- b")]
+    assert "list_item_open" in block_types, f"list_item_open missing: {block_types}"
+    print(f"  - a\\n- b -> types={block_types}  OK")
+
+
+def test_url_without_markdown_syntax_is_not_linkified():
+    """A bare URL without []() should not be linkified (linkify=False)."""
+    md = _markdown_parser_factory()
+    types = _collect_inline_types(md, "https://example.com/path")
+    # No linkify means bare URL stays as plain text
+    assert "link_open" not in types, f"link_open present with linkify=False: {types}"
+    assert "text" in types, f"text missing: {types}"
+    print(f"  https://example.com/path -> types={types}  OK")
+
+
+def test_link_and_image_mixed_with_other_content():
+    """A paragraph mixing links, images, and bold must handle all correctly."""
+    md = _markdown_parser_factory()
+    text = "**bold** [link](/tmp/x) `code`"
+    types = _collect_inline_types(md, text)
+    assert "link_open" not in types, f"link_open still present: {types}"
+    assert "strong_open" in types, f"strong_open missing: {types}"
+    assert "code_inline" in types, f"code_inline missing: {types}"
+    print(f"  mixed content -> types={types}  OK")
+
+
+def main():
+    print("=== markdown-it parser regression tests ===")
+    print()
+    tests = [
+        ("explicit link → plain text", test_explicit_link_is_plain_text),
+        ("image → plain text", test_image_is_plain_text),
+        ("autolink → plain text", test_autolink_is_plain_text),
+        ("bold unaffected", test_bold_still_works),
+        ("italic unaffected", test_italic_still_works),
+        ("inline code unaffected", test_inline_code_still_works),
+        ("heading unaffected", test_heading_still_works),
+        ("lists unaffected", test_lists_still_work),
+        ("bare URL not linkified", test_url_without_markdown_syntax_is_not_linkified),
+        ("mixed content", test_link_and_image_mixed_with_other_content),
+    ]
+    failures = 0
+    for label, fn in tests:
+        try:
+            fn()
+        except AssertionError as e:
+            print(f"  FAIL [{label}]: {e}")
+            failures += 1
+
+    print()
+    if failures:
+        print(f"FAILED: {failures} test(s)")
+        sys.exit(1)
+    else:
+        print(f"All {len(tests)} tests PASSED")
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()