fix(tokenless): fail compare on missing sessions

docs/user-guide/en/token-saving/tokenless/cli-reference.md

@@ -255,6 +255,7 @@ tokenless env-check --tool Shell --fix
 ```bash
 tokenless stats summary
 tokenless stats summary --json
+tokenless stats summary --limit 1000
 tokenless stats list --limit 20
 tokenless stats show <record-id>
 tokenless stats diff <record-id>
@@ -271,6 +272,8 @@ Dual-run comparison:
 tokenless stats summary --compare <baseline-session> <active-session>
 ```
 
+A missing session ID fails with a non-zero exit instead of a 0% comparison, matching `stats diff --session`. `stats summary --limit` must be a positive integer; `--limit 0` is rejected at parse time, matching `stats diff --limit`.
+
 Inspect one record or the verified stages of one tool call:
 
 ```bash

docs/user-guide/en/token-saving/tokenless/measuring-savings.md

@@ -69,6 +69,8 @@ The summary reads at most the latest 10,000 records by default. Limit the query
 tokenless stats summary --limit 1000
 ```
 
+`--limit` must be a positive integer. `--limit 0` is rejected at parse time with a non-zero exit, matching `stats diff --limit`.
+
 ## Inspect individual records
 
 List recent records:
@@ -194,6 +196,8 @@ tokenless stats summary \
 Notes:
 
 - `--compare` requires exactly two session IDs in baseline, active order.
+- If either session has no records, the command exits with an error instead of reporting 0% savings.
+- `--limit` must be a positive integer. `--limit 0` is rejected at parse time instead of looking like a missing session.
 - The baseline should be a dry-run and the active session should apply compression. The CLI warns on a mode mismatch.
 - For real agent tasks, keep inputs, tool versions, and the environment as similar as possible.
 - Dry-run still writes the complete before/after text to the local statistics database.

docs/user-guide/zh/token-saving/tokenless/cli-reference.md

@@ -249,6 +249,7 @@ tokenless env-check --tool Shell --fix
 ```bash
 tokenless stats summary
 tokenless stats summary --json
+tokenless stats summary --limit 1000
 tokenless stats list --limit 20
 tokenless stats show <record-id>
 tokenless stats diff <record-id>
@@ -265,6 +266,8 @@ tokenless stats clear --yes
 tokenless stats summary --compare <baseline-session> <active-session>
 ```
 
+Session ID 不存在时以非零退出码失败，而不是输出 0% 对比，行为与 `stats diff --session` 一致。`stats summary --limit` 必须为正整数；`--limit 0` 会在解析阶段被拒绝，行为与 `stats diff --limit` 一致。
+
 查看单条记录，或一次工具调用中可确认衔接的阶段：
 
 ```bash

docs/user-guide/zh/token-saving/tokenless/measuring-savings.md

@@ -69,6 +69,8 @@ tokenless stats summary --json
 tokenless stats summary --limit 1000
 ```
 
+`--limit` 必须为正整数。`--limit 0` 会在解析阶段以非零退出码被拒绝，行为与 `stats diff --limit` 一致。
+
 ## 查看单条记录
 
 列出最近记录：
@@ -188,6 +190,8 @@ tokenless stats summary \
 注意：
 
 - `--compare` 必须提供恰好两个 Session ID，顺序为 baseline、active。
+- 任一 Session 没有记录时，命令以错误退出，而不是报告 0% 节省。
+- `--limit` 必须为正整数。`--limit 0` 会在解析阶段被拒绝，而不会被误报为 Session 缺失。
 - baseline 应为 dry-run，active 应为真实压缩；模式不匹配时 CLI 会告警。
 - 对真实 Agent 任务做对比时，应尽量使用相同输入、工具版本和环境。
 - dry-run 仍会把压缩前后文本写入本地统计数据库。

src/tokenless/README.md

@@ -323,21 +323,27 @@ echo 'name: Alice\nage: 30' | tokenless decompress-toon
 
 ### Inspect token savings
 
-Use `show` to print the complete stored before/after payload, or `diff` to
-explain the estimated token saving and highlight only changed lines:
+Use `stats summary` for totals, `show` for the stored before/after payload, or
+`diff` to explain the estimated token saving and highlight only changed lines:
 
 ```bash
+tokenless stats summary
+tokenless stats summary --limit 1000
+tokenless stats summary --compare <baseline-session> <active-session>
 tokenless stats show 42
 tokenless stats diff 42
 tokenless stats diff --session <session-id>
 tokenless stats diff --session <session-id> --tool-use-id <tool-use-id>
 tokenless stats diff 42 --json
 ```
 
-Session overviews contain metrics only. Record and tool-use reports include a
-unified content diff; consecutive active stages are linked only when their
-stored output/input content matches exactly, avoiding duplicate intermediate
-token counts. See [Measuring Tokenless Savings](../../docs/user-guide/en/token-saving/tokenless/measuring-savings.md)
+`stats summary --limit` must be a positive integer; `--limit 0` is rejected at
+parse time. `--compare` fails if either session has no records instead of
+reporting 0% savings. Session overviews contain metrics only. Record and
+tool-use reports include a unified content diff; consecutive active stages are
+linked only when their stored output/input content matches exactly, avoiding
+duplicate intermediate token counts. See
+[Measuring Tokenless Savings](../../docs/user-guide/en/token-saving/tokenless/measuring-savings.md)
 for options and measurement limits.
 
 ### Database location

src/tokenless/README_zh.md

@@ -353,20 +353,25 @@ node npm/scripts/package-npm.js --all
 
 ## 查看 Token 节省明细
 
-`show` 用于原样打印完整的压缩前后内容；`diff` 用于解释估算 Token
-节省，并只突出发生变化的行：
+`stats summary` 用于查看合计；`show` 用于原样打印完整的压缩前后内容；
+`diff` 用于解释估算 Token 节省，并只突出发生变化的行：
 
 ```bash
+tokenless stats summary
+tokenless stats summary --limit 1000
+tokenless stats summary --compare <baseline-session> <active-session>
 tokenless stats show 42
 tokenless stats diff 42
 tokenless stats diff --session <session-id>
 tokenless stats diff --session <session-id> --tool-use-id <tool-use-id>
 tokenless stats diff 42 --json
 ```
 
-Session 总览只包含指标；单记录和 tool-use 报告包含 unified content
-diff。只有相邻 active 阶段的输出与输入内容完全一致时才会串成一条链，
-从而避免重复计算中间阶段的 Token。完整选项和度量限制见
+`stats summary --limit` 必须为正整数；`--limit 0` 会在解析阶段被拒绝。
+`--compare` 在任一 Session 没有记录时失败，而不是报告 0% 节省。Session
+总览只包含指标；单记录和 tool-use 报告包含 unified content diff。只有相邻
+active 阶段的输出与输入内容完全一致时才会串成一条链，从而避免重复计算中间
+阶段的 Token。完整选项和度量限制见
 [Tokenless 效果度量](../../docs/user-guide/zh/token-saving/tokenless/measuring-savings.md)。
 
 ## 数据库位置

src/tokenless/crates/tokenless-cli/src/main.rs

@@ -181,7 +181,7 @@ impl From<DiffSortArg> for DiffSort {
 enum StatsCommands {
     /// Show summary statistics with breakdown by operation
     Summary {
-        #[arg(long)]
+        #[arg(long, value_parser = parse_positive_usize)]
         limit: Option<usize>,
         /// Output machine-readable JSON
         #[arg(long)]
@@ -699,6 +699,14 @@ fn run_command(command: Commands) -> Result<(), (String, i32)> {
                         let tokenless = recorder
                             .records_by_session(tokenless_sid, limit)
                             .map_err(|e| (format!("Failed to query tokenless: {}", e), 1))?;
+                        if let Some(message) = missing_compare_sessions(
+                            baseline_sid,
+                            tokenless_sid,
+                            &baseline,
+                            &tokenless,
+                        ) {
+                            return Err((message, 1));
+                        }
                         // Warn if a session's records do not match the expected mode,
                         // i.e. the baseline run was not recorded as dry-run.
                         warn_mode_mismatch("baseline", &baseline, CompressionMode::DryRun);
@@ -974,6 +982,27 @@ fn resolve_mode(
     }
 }
 
+/// Error text when a `--compare` side has no recorded stats.
+///
+/// An empty side used to format as a successful 0% report, which hid typos
+/// and made A/B scripts look like "no savings". Fail closed like
+/// `stats diff --session` and the Python `TokenlessStats.compare` client.
+fn missing_compare_sessions(
+    baseline_sid: &str,
+    tokenless_sid: &str,
+    baseline: &[StatsRecord],
+    tokenless: &[StatsRecord],
+) -> Option<String> {
+    let mut missing = Vec::new();
+    if baseline.is_empty() {
+        missing.push(format!("baseline session {baseline_sid:?}"));
+    }
+    if tokenless.is_empty() {
+        missing.push(format!("tokenless session {tokenless_sid:?}"));
+    }
+    (!missing.is_empty()).then(|| format!("No records found for {}", missing.join(" and ")))
+}
+
 /// Warn (to stderr) when a session's records were not recorded in the expected
 /// mode, e.g. a "baseline" session that was not run with compression disabled.
 /// A non-blocking sanity hint — comparison still proceeds.