feat: enforce debug/host guard and document API versioning

Author: clean6378-max-it

app.py

@@ -29,6 +29,18 @@ def is_loopback_host(host: str) -> bool:
     return False
 
 
+def format_listen_url(host: str, port: int) -> str:
+    """Return a valid ``http://`` URL for the startup banner (IPv6 hosts bracketed)."""
+    h = (host or "").strip()
+    if h.startswith("[") and h.endswith("]"):
+        display_host = h
+    elif ":" in h:
+        display_host = f"[{h}]"
+    else:
+        display_host = h
+    return f"http://{display_host}:{port}"
+
+
 def validate_startup_cli(args: argparse.Namespace) -> None:
     """Refuse ``--debug`` when ``--host`` is reachable off loopback."""
     if args.debug and not is_loopback_host(args.host):
@@ -92,7 +104,7 @@ def build_cli_parser() -> argparse.ArgumentParser:
     validate_startup_cli(args)
 
     app = create_app(base_dir=args.base_dir, exclusion_rules_path=args.exclude_rules)
-    print(f"Claude Code Chat Browser running at http://{args.host}:{args.port}")
+    print(f"Claude Code Chat Browser running at {format_listen_url(args.host, args.port)}")
     # Reloader follows --debug on Unix only (Werkzeug file watcher, not the interactive debugger).
     app.run(
         host=args.host,

docs/api-reference.md

@@ -244,21 +244,21 @@ Same as session detail.
 
 `application/json` — stats object from [`utils/session_stats.py`](../utils/session_stats.py) `compute_stats()`:
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `files_touched` | object | `read`, `written`, `created`, `total_unique` file lists |
-| `commands_run` | array | Bash commands with exit metadata |
-| `urls_accessed` | string[] | Web fetch URLs |
-| `conversation_turns` | integer | Human/assistant turn count |
-| `wall_clock_seconds` | number \| null | Session duration |
-| `wall_clock_display` | string \| null | Human-readable duration |
-| `cost_estimate_usd` | number | Best-effort USD estimate from token usage |
-| `tool_result_summary` | object | Aggregated tool result stats |
-| `stop_reason_summary` | object | Stop reason counts |
-| `entry_type_counts` | object | JSONL entry type counts |
-| `sidechain_message_count` | integer | Sidechain entries |
-| `api_error_count` | integer | API errors in session |
-| `compaction_events` | array | Context compaction markers |
+| Field | Type | Stability | Description |
+|-------|------|-----------|-------------|
+| `files_touched` | object | stable | `read`, `written`, `created`, `total_unique` file lists |
+| `commands_run` | array | stable | Bash commands with exit metadata |
+| `urls_accessed` | string[] | stable | Web fetch URLs |
+| `conversation_turns` | integer | stable | Human/assistant turn count |
+| `wall_clock_seconds` | number \| null | stable | Session duration |
+| `wall_clock_display` | string \| null | stable | Human-readable duration |
+| `cost_estimate_usd` | number | stable | Best-effort USD estimate from token usage |
+| `tool_result_summary` | object | stable | Aggregated tool result stats |
+| `stop_reason_summary` | object | stable | Stop reason counts |
+| `entry_type_counts` | object | stable | JSONL entry type counts |
+| `sidechain_message_count` | integer | stable | Sidechain entries |
+| `api_error_count` | integer | stable | API errors in session |
+| `compaction_events` | array | stable | Context compaction markers |
 
 #### Errors
 

tests/test_cli_args.py

@@ -21,7 +21,7 @@
 REPO_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
 sys.path.insert(0, REPO_ROOT)
 
-from app import build_cli_parser, is_loopback_host, validate_startup_cli
+from app import build_cli_parser, format_listen_url, is_loopback_host, validate_startup_cli
 from scripts.export import build_parser
 
 
@@ -334,12 +334,28 @@ def test_validate_startup_cli_allows_loopback_debug(self) -> None:
         args = parser.parse_args(["--host", "127.0.0.1", "--debug"])
         validate_startup_cli(args)
 
-    def test_validate_startup_cli_rejects_non_loopback_debug(self) -> None:
+    def test_validate_startup_cli_rejects_non_loopback_debug(
+        self, capsys: pytest.CaptureFixture[str]
+    ) -> None:
         parser = build_cli_parser()
         args = parser.parse_args(["--host", "0.0.0.0", "--debug"])
         with pytest.raises(SystemExit) as exc_info:
             validate_startup_cli(args)
         assert exc_info.value.code == 1
+        err = capsys.readouterr().err
+        assert "debug" in err.lower()
+        assert "loopback" in err.lower()
+
+    @pytest.mark.parametrize(
+        ("host", "port", "expected"),
+        [
+            ("127.0.0.1", 5000, "http://127.0.0.1:5000"),
+            ("::1", 8080, "http://[::1]:8080"),
+            ("[::1]", 8080, "http://[::1]:8080"),
+        ],
+    )
+    def test_format_listen_url(self, host: str, port: int, expected: str) -> None:
+        assert format_listen_url(host, port) == expected
 
     def test_validate_startup_cli_allows_non_loopback_without_debug(self) -> None:
         parser = build_cli_parser()