Fix metrics bounds, warnings, tail reads, and rotation (#3622)

* Bound metrics summary input (#3512)

* Warn on metrics sink startup failures (#3504)

* Stream report log tail reads (#3397)

* Share replacement-aware log rotation (#3412)

* Make metrics bad-path test portable (#3504)

Author: Widthdom

USER_GUIDE.md

@@ -1395,7 +1395,7 @@ same source location.
 | `--max-results <n>` | `search` | Alias for `--limit` |
 | `--color <when>` | All commands | Control ANSI color output. Accepts `auto` (default), `always`, or `never`. Precedence: `--color` flag > `CLICOLOR_FORCE` > `NO_COLOR` > `CLICOLOR=0` > terminal capability auto-detect. Auto mode treats redirected stdout and StringWriter-style test capture as non-ANSI; on Windows it also accepts ConPTY/Windows Terminal virtual-terminal support and terminal hints such as `WT_SESSION`, `WT_PROFILE_ID`, `TERM_PROGRAM`, or non-`dumb` `TERM`. Use `--color=always` to keep colored kind labels through a pager such as `cdidx symbols Foo \| less -R`; use `--color=never` (or `NO_COLOR=1`) to suppress ANSI even on a TTY. |
 | `--palette <name>` | All commands | Choose the ANSI palette used when color output is enabled. Accepts `basic` (8-color SGR 30–37, the default fallback for minimal SSH/CI terminals), `256` (256-color `\x1b[38;5;Nm`), or `truecolor` (24-bit RGB `\x1b[38;2;R;G;Bm`). Precedence: `--palette` flag > `CDIDX_COLOR_PALETTE` env var > `COLORTERM` / `TERM` auto-detect. The basic palette avoids `\x1b[90m` (bright-black / dim), which is unreadable on many minimal terminals. |
-| `--metrics <path>` | All commands (and MCP tool calls) | Append one JSONL metrics record per CLI command / MCP tool call to `<path>`. The `CDIDX_METRICS=<path>` environment variable provides the same destination as a fallback when the flag is not passed. Best-effort: any IO failure (missing directory, read-only mount, etc.) is swallowed silently and never breaks the underlying command. |
+| `--metrics <path>` | All commands (and MCP tool calls) | Append one JSONL metrics record per CLI command / MCP tool call to `<path>`. The `CDIDX_METRICS=<path>` environment variable provides the same destination as a fallback when the flag is not passed. If the destination cannot be opened at startup, cdidx emits a bounded warning, disables metrics, and continues the underlying command. Later write or rotation failures remain best-effort and never break the command. |
 
 If a query itself begins with `-`, pass it as `--query <query>` or `-- <query>`. If an option value itself begins with `--`, pass it as `--opt=<value>` rather than a separated value, for example `--path=--json-dir` or `--db=--tmp.db`.
 
@@ -1512,7 +1512,7 @@ Currently only the `cdidx --sushi` / `--coffee` / `--ramen` / `--wine` / `--beer
 
 ### Metrics emission
 
-Pass `--metrics <path>` (or set `CDIDX_METRICS=<path>` in the environment) to make `cdidx` append one JSON-lines record per CLI command and per MCP tool call. The flag wins over the environment variable when both are present. The destination file is opened in append mode, so multiple cdidx invocations writing to the same path interleave cleanly. Emission is best-effort: any IO failure (missing directory, unwritable mount, etc.) is swallowed silently and never breaks the underlying command.
+Pass `--metrics <path>` (or set `CDIDX_METRICS=<path>` in the environment) to make `cdidx` append one JSON-lines record per CLI command and per MCP tool call. The flag wins over the environment variable when both are present. The destination file is opened in append mode, so multiple cdidx invocations writing to the same path interleave cleanly. If the destination cannot be opened at startup, cdidx emits a bounded warning to stderr, disables metrics, and continues the underlying command. Later record writes and rotation attempts remain best-effort and never break the command.
 
 Each record is a single JSON object on its own line with these fields:
 
@@ -3856,7 +3856,7 @@ raw match density を正確に測る、といった理由で全 raw chunk hit 
 | `--max-results <n>` | `search` | `--limit` のエイリアス |
 | `--color <when>` | 全コマンド | ANSI カラー出力の制御。`auto`（既定）、`always`、`never` を受け付ける。優先順位: `--color` フラグ > `CLICOLOR_FORCE` > `NO_COLOR` > `CLICOLOR=0` > 端末能力の自動判定。auto では redirected stdout と StringWriter 風のテスト capture を非 ANSI とみなし、Windows では ConPTY / Windows Terminal の virtual-terminal 対応と `WT_SESSION`、`WT_PROFILE_ID`、`TERM_PROGRAM`、非 `dumb` の `TERM` などの端末ヒントも見る。`cdidx symbols Foo \| less -R` のような pager pipe でも色を維持したい場合は `--color=always`、TTY 上でも ANSI を抑止したい場合は `--color=never`（または `NO_COLOR=1`）を指定する。 |
 | `--palette <name>` | 全コマンド | カラー出力が有効なときに用いる ANSI パレットを選択する。`basic`（標準8色 SGR 30–37、最小 SSH/CI 端末向けの既定フォールバック）、`256`（256色 `\x1b[38;5;Nm`）、`truecolor`（24ビット RGB `\x1b[38;2;R;G;Bm`）を受け付ける。優先順位: `--palette` フラグ > `CDIDX_COLOR_PALETTE` 環境変数 > `COLORTERM` / `TERM` 自動判定。`basic` パレットは最小端末で読みにくい `\x1b[90m`（暗灰 / dim）を避ける。 |
-| `--metrics <path>` | 全コマンド（および MCP ツール呼び出し） | CLI コマンド / MCP ツール呼び出し 1 回ごとに JSONL レコードを 1 行ずつ `<path>` に追記する。フラグ未指定時のフォールバックとして `CDIDX_METRICS=<path>` 環境変数でも同じ出力先を指定できる。Best-effort のため、ディレクトリが無い・read-only マウント等の IO 失敗は黙って握り潰し、本体コマンドを壊さない。 |
+| `--metrics <path>` | 全コマンド（および MCP ツール呼び出し） | CLI コマンド / MCP ツール呼び出し 1 回ごとに JSONL レコードを 1 行ずつ `<path>` に追記する。フラグ未指定時のフォールバックとして `CDIDX_METRICS=<path>` 環境変数でも同じ出力先を指定できる。起動時に出力先を開けない場合、cdidx は長さを制限した警告を出してメトリクスを無効化し、本体コマンドを続行する。その後の書き込みやローテーションの失敗はベストエフォートのまま扱われ、本体コマンドを壊さない。 |
 
 クエリ自体が `-` で始まる場合は `--query <query>` または `-- <query>` で渡してください。オプション値自体が `--` で始まる場合は、分離形式ではなく `--opt=<value>` で渡します。たとえば `--path=--json-dir` や `--db=--tmp.db` のように指定します。
 
@@ -3973,7 +3973,7 @@ MCP ツールで catch-all まで突き抜けた例外（想定外の SQLite 例
 
 ### メトリクス出力
 
-`--metrics <path>` を渡す（または環境変数 `CDIDX_METRICS=<path>` を設定する）と、`cdidx` は CLI コマンド 1 回・MCP ツール呼び出し 1 回ごとに 1 行の JSON レコードを指定パスへ追記します。両方指定されている場合はフラグが優先されます。出力先は append モードで開かれるため、複数の cdidx 実行が同じファイルへ書いてもきれいにインターリーブされます。出力は best-effort で、ディレクトリ不在・書き込み不可マウントなどの IO 失敗は黙って握り潰し、本体コマンドを壊しません。
+`--metrics <path>` を渡す（または環境変数 `CDIDX_METRICS=<path>` を設定する）と、`cdidx` は CLI コマンド 1 回・MCP ツール呼び出し 1 回ごとに 1 行の JSON レコードを指定パスへ追記します。両方指定されている場合はフラグが優先されます。出力先は append モードで開かれるため、複数の cdidx 実行が同じファイルへ書いてもきれいにインターリーブされます。起動時に出力先を開けない場合、cdidx は stderr に長さを制限した警告を出してメトリクスを無効化し、本体コマンドを続行します。その後のレコード書き込みやローテーションの失敗はベストエフォートのまま扱われ、本体コマンドを壊しません。
 
 各レコードは独立した行に 1 つの JSON オブジェクトとして書き出され、フィールドは次の通りです。
 

changelog.d/unreleased/3397.fixed.md

@@ -0,0 +1,16 @@
+---
+category: fixed
+issues:
+  - 3397
+affected:
+  - src/CodeIndex/Cli/ReportCommandRunner.cs
+  - tests/CodeIndex.Tests/ReportCommandRunnerTests.cs
+---
+
+## English
+
+- **Report log tailing now reads incrementally (#3397)** — `cdidx report` no longer materializes the bounded log tail window with `ReadToEnd`; it streams lines from the tail offset and keeps only the requested final lines.
+
+## 日本語
+
+- **report のログ末尾読み取りを逐次処理にしました (#3397)** — `cdidx report` は bounded log tail window を `ReadToEnd` でまとめて materialize せず、tail offset から行単位で読みながら要求された末尾行だけを保持するようになりました。

changelog.d/unreleased/3412.fixed.md

@@ -0,0 +1,18 @@
+---
+category: fixed
+issues:
+  - 3412
+affected:
+  - src/CodeIndex/Cli/PrivateLogFile.cs
+  - src/CodeIndex/Cli/SuggestionStore.cs
+  - src/CodeIndex/Mcp/AuditLogSink.cs
+  - tests/CodeIndex.Tests/GlobalToolLogTests.cs
+---
+
+## English
+
+- **Archive and log rotation now share replacement-aware slot rotation (#3412)** — metrics logs, MCP audit logs, and suggestion archives now use the common `PrivateLogFile.TryRotateSlots` helper, which replaces existing destination slots with overwrite move semantics where the platform supports them.
+
+## 日本語
+
+- **archive と log rotation が replacement-aware な共通 slot rotation を使うようになりました (#3412)** — metrics log、MCP audit log、suggestion archive は共通の `PrivateLogFile.TryRotateSlots` helper を使い、platform が対応する範囲で overwrite move semantics により既存 destination slot を置き換えるようになりました。

changelog.d/unreleased/3504.fixed.md

@@ -0,0 +1,16 @@
+---
+category: fixed
+issues:
+  - 3504
+affected:
+  - src/CodeIndex/Cli/MetricsSink.cs
+  - tests/CodeIndex.Tests/MetricsSinkTests.cs
+---
+
+## English
+
+- **Metrics sink failures now surface a warning for configured paths (#3504)** — `--metrics` / `CDIDX_METRICS` still keep command execution best-effort, but an unusable configured metrics path now emits a bounded stderr warning instead of silently disabling metrics.
+
+## 日本語
+
+- **設定済み metrics path の sink 失敗時に warning を出すようになりました (#3504)** — `--metrics` / `CDIDX_METRICS` は引き続きコマンド実行をベストエフォートで継続しますが、設定済み metrics path が使えない場合はメトリクスを黙って無効化せず、上限付きの stderr warning を出します。

changelog.d/unreleased/3512.fixed.md

@@ -0,0 +1,15 @@
+---
+category: fixed
+issues:
+  - 3512
+affected:
+  - scripts/metrics-summary.py
+---
+
+## English
+
+- **Bounded metrics summary input and percentile retention (#3512)** — `scripts/metrics-summary.py` now caps JSONL lines, decoded records, per-line bytes, and retained elapsed values per bucket while keeping total counts and max latency across all processed records.
+
+## 日本語
+
+- **metrics summary の入力と percentile 用保持値を上限化しました (#3512)** — `scripts/metrics-summary.py` は JSONL の行数、デコード済みレコード数、1 行あたりの byte 数、bucket ごとの elapsed 値保持数を制限しつつ、処理済み全レコードの count と最大 latency は維持するようになりました。

scripts/metrics-summary.py

@@ -15,10 +15,17 @@
 import argparse
 import json
 import math
+import random
 import sys
-from collections import defaultdict
+from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Iterable
+from typing import BinaryIO, Iterable, Iterator
+
+
+DEFAULT_MAX_LINES = 1_000_000
+DEFAULT_MAX_RECORDS = 1_000_000
+DEFAULT_MAX_LINE_BYTES = 1_048_576
+DEFAULT_MAX_VALUES_PER_BUCKET = 10_000
 
 
 def _percentile(sorted_values: list[float], pct: float) -> float:
@@ -34,37 +41,117 @@ def _percentile(sorted_values: list[float], pct: float) -> float:
     return sorted_values[lower] + (sorted_values[upper] - sorted_values[lower]) * (k - lower)
 
 
-def _iter_records(stream: Iterable[str]) -> Iterable[dict]:
-    for raw in stream:
-        line = raw.strip()
+def _positive_int(value: str) -> int:
+    try:
+        parsed = int(value, 10)
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError("must be an integer") from exc
+    if parsed <= 0:
+        raise argparse.ArgumentTypeError("must be greater than zero")
+    return parsed
+
+
+def _drain_long_line(stream: BinaryIO, max_line_bytes: int) -> None:
+    while True:
+        chunk = stream.readline(max_line_bytes)
+        if not chunk or chunk.endswith(b"\n"):
+            return
+
+
+def _iter_records(
+    stream: BinaryIO,
+    *,
+    max_lines: int,
+    max_records: int,
+    max_line_bytes: int,
+) -> Iterator[dict]:
+    line_number = 0
+    records = 0
+    while line_number < max_lines:
+        raw = stream.readline(max_line_bytes + 1)
+        if not raw:
+            return
+        line_number += 1
+
+        if len(raw) > max_line_bytes:
+            if not raw.endswith(b"\n"):
+                _drain_long_line(stream, max_line_bytes)
+            print(f"warn: skipping line {line_number}: exceeds --max-line-bytes", file=sys.stderr)
+            continue
+
+        try:
+            line = raw.decode("utf-8").strip()
+        except UnicodeDecodeError:
+            print(f"warn: skipping line {line_number}: invalid UTF-8", file=sys.stderr)
+            continue
         if not line:
             continue
         try:
-            yield json.loads(line)
-        except json.JSONDecodeError as exc:
-            print(f"warn: skipping malformed line: {exc}", file=sys.stderr)
-
-
-def summarize(records: Iterable[dict]) -> list[dict]:
-    buckets: dict[tuple[str, str], list[float]] = defaultdict(list)
+            record = json.loads(line)
+        except json.JSONDecodeError:
+            print(f"warn: skipping line {line_number}: invalid JSON", file=sys.stderr)
+            continue
+        records += 1
+        if records > max_records:
+            print(f"warn: stopped after --max-records={max_records}", file=sys.stderr)
+            return
+        yield record
+
+    print(f"warn: stopped after --max-lines={max_lines}", file=sys.stderr)
+
+
+@dataclass
+class Bucket:
+    max_samples: int
+    rng: random.Random
+    count: int = 0
+    max_value: float = -math.inf
+    samples: list[float] = field(default_factory=list)
+
+    def add(self, value: float) -> None:
+        self.count += 1
+        self.max_value = max(self.max_value, value)
+        if len(self.samples) < self.max_samples:
+            self.samples.append(value)
+            return
+
+        replacement = self.rng.randrange(self.count)
+        if replacement < self.max_samples:
+            self.samples[replacement] = value
+
+
+def summarize(
+    records: Iterable[dict],
+    *,
+    max_values_per_bucket: int = DEFAULT_MAX_VALUES_PER_BUCKET,
+    seed: int = 0,
+) -> list[dict]:
+    buckets: dict[tuple[str, str], Bucket] = {}
     for rec in records:
         elapsed = rec.get("elapsed_ms")
         if not isinstance(elapsed, (int, float)):
             continue
         key = (rec.get("source") or "?", rec.get("tool") or "?")
-        buckets[key].append(float(elapsed))
+        bucket = buckets.get(key)
+        if bucket is None:
+            bucket_seed = f"{seed}:{key[0]}:{key[1]}"
+            bucket = Bucket(max_values_per_bucket, random.Random(bucket_seed))
+            buckets[key] = bucket
+        bucket.add(float(elapsed))
 
     rows: list[dict] = []
-    for (source, tool), values in sorted(buckets.items()):
-        values.sort()
+    for (source, tool), bucket in sorted(buckets.items()):
+        values = sorted(bucket.samples)
         rows.append({
             "source": source,
             "tool": tool,
-            "count": len(values),
+            "count": bucket.count,
+            "sample_count": len(values),
+            "sampled": bucket.count > len(values),
             "p50_ms": round(_percentile(values, 50), 3),
             "p95_ms": round(_percentile(values, 95), 3),
             "p99_ms": round(_percentile(values, 99), 3),
-            "max_ms": round(values[-1], 3),
+            "max_ms": round(bucket.max_value, 3),
         })
     return rows
 
@@ -73,7 +160,7 @@ def _print_table(rows: list[dict]) -> None:
     if not rows:
         print("(no records)")
         return
-    headers = ["source", "tool", "count", "p50_ms", "p95_ms", "p99_ms", "max_ms"]
+    headers = ["source", "tool", "count", "sample_count", "sampled", "p50_ms", "p95_ms", "p99_ms", "max_ms"]
     widths = [max(len(h), *(len(str(r[h])) for r in rows)) for h in headers]
     fmt = "  ".join(f"{{:<{w}}}" for w in widths)
     print(fmt.format(*headers))
@@ -86,13 +173,34 @@ def main() -> int:
     parser = argparse.ArgumentParser(description="Summarize cdidx --metrics JSONL output")
     parser.add_argument("path", nargs="?", help="Path to JSONL file (defaults to stdin)")
     parser.add_argument("--json", action="store_true", help="Emit summary rows as JSON")
+    parser.add_argument("--max-lines", type=_positive_int, default=DEFAULT_MAX_LINES, help="Maximum physical JSONL lines to read")
+    parser.add_argument("--max-records", type=_positive_int, default=DEFAULT_MAX_RECORDS, help="Maximum decoded JSON records to process")
+    parser.add_argument("--max-line-bytes", type=_positive_int, default=DEFAULT_MAX_LINE_BYTES, help="Maximum bytes accepted for one JSONL line")
+    parser.add_argument("--max-values-per-bucket", type=_positive_int, default=DEFAULT_MAX_VALUES_PER_BUCKET, help="Maximum elapsed_ms values retained per (source, tool) bucket")
+    parser.add_argument("--sample-seed", type=int, default=0, help="Deterministic seed for bounded percentile sampling")
     args = parser.parse_args()
 
+    def records_from(stream: BinaryIO) -> Iterator[dict]:
+        return _iter_records(
+            stream,
+            max_lines=args.max_lines,
+            max_records=args.max_records,
+            max_line_bytes=args.max_line_bytes,
+        )
+
     if args.path and args.path != "-":
-        with Path(args.path).open("r", encoding="utf-8") as fh:
-            rows = summarize(_iter_records(fh))
+        with Path(args.path).open("rb") as fh:
+            rows = summarize(
+                records_from(fh),
+                max_values_per_bucket=args.max_values_per_bucket,
+                seed=args.sample_seed,
+            )
     else:
-        rows = summarize(_iter_records(sys.stdin))
+        rows = summarize(
+            records_from(sys.stdin.buffer),
+            max_values_per_bucket=args.max_values_per_bucket,
+            seed=args.sample_seed,
+        )
 
     if args.json:
         json.dump(rows, sys.stdout, indent=2)