openclaw-diag-cli 0.2.1 → 0.2.2

package/README.md

@@ -6,7 +6,7 @@ OpenClaw 出问题时，**先跑这条命令再开 ticket**：
 npx openclaw-diag-cli all
 ```
 
-零安装、零依赖、observer-only — 只读探测，绝不改你的状态。
+零安装、零依赖、observer-only — 不改 OpenClaw 的配置 / session / cron / 服务状态；只读探测，可写诊断输出（落到工具自己的目录）。
 
 ## 这是什么
 
@@ -60,17 +60,16 @@ openclaw-diag trace <session-uuid>
 ```
 ── 模块 4：Gateway 状态 ──
 
-  • 进程 / 端口
-    PID 12847 (uptime 3d 2h)，监听 :8080，HTTP /healthz → 200
-  • 24h 重启
-    无重启事件
-  • Model API
-    amazon-bedrock 可达（DNS+HTTP+认证均通）
-  • WS 生命周期
-    最近 1h 内 134 次连接，平均存活 47s，无异常关闭
+  • Systemd: Active: active (running) since Sun 2026-05-17 20:45:02 CST; 11h ago
+  • Main PID: 142687 (node)
+  • 端口 18789 监听: 是 | HTTP 健康检查: 200
+  • 24h 启停事件: 0 次启动 — 近 24h 无重启/停止记录
+  • 模型 API [https://bedrock-runtime.us-east-1.amazonaws.com]: HTTP 200
+  • Channel WS: 最近 1h 5 次连接，平均存活 32s
+  • Gateway 错误码: 0 条
 ```
 
-加 `--json` 后输出严格结构化（同字段、同值），方便管道处理。
+加 `--json` 后输出结构化（覆盖文本里出现的核心字段，便于 jq / 监控管道）。
 
 ## 诊断列表
 
@@ -93,12 +92,12 @@ openclaw-diag list   # 看完整列表
 | `plugin_diag` | 插件状态一致性、ERROR/WARN、Hook 异常、Channel、外部依赖 DNS |
 | `shell_history` | 高危命令、openclaw 命令、最近操作 |
 
-**对象类（需要 session uuid）**
+**对象类（需要 session uuid 或 ≥ 8 位前缀；都支持 `--json`）**
 
 | 诊断 | 看什么 |
 |---|---|
 | `trace <uuid>` | 一条用户消息从进入到响应的完整时间轴 |
-| `extract <uuid>` | session.jsonl 导出为可读格式（active / reset / deleted / backup 全状态） |
+| `extract <uuid>` | session.jsonl 导出为可读格式（active / reset / deleted / backup 全状态；`--summary` 仅汇总） |
 
 **其它命令**
 

package/bin/ocdiag

@@ -1,7 +1,6 @@
 #!/usr/bin/env python3
 """ocdiag entry-point shim that runs the dispatcher from the repo root."""
 
-import os
 import sys
 from pathlib import Path
 

package/ocdiag/__init__.py

@@ -1,3 +1,3 @@
 """ocdiag — shared library for openclaw-diag-cli scripts."""
 
-__version__ = "0.2.1"
+__version__ = "0.2.2"

package/ocdiag/paths.py

@@ -29,19 +29,3 @@ SERVICE_ENV_FILE = _env_path(
     "OPENCLAW_SERVICE_ENV_FILE",
     os.path.join(HOME, ".config", "systemd", "user", "openclaw-gateway.service.d", "env.conf"),
 )
-
-
-def home() -> str:
-    return HOME
-
-
-def config_path() -> str:
-    return CONFIG
-
-
-def log_dir() -> str:
-    return LOG_DIR
-
-
-def sessions_base() -> str:
-    return SESSIONS_BASE

package/ocdiag/sessions.py

@@ -0,0 +1,161 @@
+"""Shared session-file lookup utilities for trace/extract.
+
+A "session" is identified by a UUID. On disk it can have multiple files:
+  <uuid>.jsonl              — active
+  <uuid>.jsonl.lock         — write lock (transient, filtered by default)
+  <uuid>.jsonl.deleted.<ts> — soft-deleted
+  <uuid>.jsonl.reset.<ts>   — pre-reset snapshot
+  <uuid>.jsonl.bak-<pid>    — backup snapshot
+
+Sibling artifacts (NOT session content):
+  <uuid>.trajectory.jsonl, <uuid>.acp-stream.jsonl, <uuid>.json
+
+Callers may pass a full UUID or a prefix of at least MIN_PREFIX_LEN chars.
+"""
+
+from __future__ import annotations
+
+import glob
+import os
+import re
+from typing import Dict, List, Optional, Tuple
+
+from . import paths
+
+
+MIN_PREFIX_LEN = 8
+
+_TRANSIENT_SUFFIXES = (".lock", ".tmp", ".swp")
+
+_UUID_CHAR = re.compile(r"^[0-9a-fA-F-]+$")
+
+
+def classify_state(filename: str) -> str:
+    """Tag a session-file basename with its lifecycle state."""
+    if ".jsonl.deleted." in filename:
+        return "deleted"
+    if ".jsonl.reset." in filename:
+        return "reset"
+    if ".jsonl.bak-" in filename:
+        return "backup"
+    if filename.endswith(".jsonl.lock"):
+        return "lock"
+    if filename.endswith(".jsonl"):
+        return "active"
+    return "unknown"
+
+
+def _session_uuid_of(filename: str) -> Optional[str]:
+    """Return the session UUID the file belongs to, or None for siblings."""
+    if ".trajectory" in filename or ".acp-stream" in filename:
+        return None
+    if filename.endswith(".json") and not filename.endswith(".jsonl"):
+        return None
+    idx = filename.find(".jsonl")
+    if idx <= 0:
+        return None
+    return filename[:idx]
+
+
+def _is_transient(filename: str) -> bool:
+    if ".jsonl.bak-" in filename:
+        return False
+    return any(filename.endswith(s) for s in _TRANSIENT_SUFFIXES) or filename.endswith(".bak")
+
+
+def is_valid_query(session_id: str) -> Tuple[bool, str]:
+    """Reject queries shorter than MIN_PREFIX_LEN or with non-UUID chars."""
+    if not session_id:
+        return False, "session id 不能为空"
+    if len(session_id) < MIN_PREFIX_LEN:
+        return False, (
+            f"session id 太短（'{session_id}' 只有 {len(session_id)} 字符），"
+            f"至少需要 {MIN_PREFIX_LEN} 位 UUID 前缀"
+        )
+    if not _UUID_CHAR.match(session_id):
+        return False, f"session id 含非法字符（仅允许十六进制和连字符）: '{session_id}'"
+    return True, ""
+
+
+def resolve(
+    session_id: str,
+    base_dir: str = paths.SESSIONS_BASE,
+    agent: Optional[str] = None,
+    include_transient: bool = False,
+) -> Tuple[List[Tuple[str, str]], List[str]]:
+    """Resolve a UUID or prefix to its on-disk session files.
+
+    Returns ``(files, candidates)``:
+      - ``files``: ``[(abs_path, state), ...]`` for the resolved session,
+        sorted by lifecycle priority (active first). Empty when ambiguous or
+        when there are 0 matches.
+      - ``candidates``: when multiple distinct session UUIDs share the
+        prefix, this lists their full UUIDs sorted; otherwise empty.
+    """
+    if agent:
+        agent_dirs = [os.path.join(base_dir, agent)]
+    else:
+        agent_dirs = sorted(glob.glob(os.path.join(base_dir, "*")))
+
+    by_uuid: Dict[str, List[Tuple[str, str]]] = {}
+    for ad in agent_dirs:
+        sd = os.path.join(ad, "sessions")
+        if not os.path.isdir(sd):
+            continue
+        try:
+            entries = os.listdir(sd)
+        except OSError:
+            continue
+        for entry in entries:
+            if not entry.startswith(session_id):
+                continue
+            uuid = _session_uuid_of(entry)
+            if uuid is None:
+                continue
+            if not include_transient and _is_transient(entry):
+                continue
+            full = os.path.join(sd, entry)
+            if not os.path.isfile(full):
+                continue
+            state = classify_state(entry)
+            by_uuid.setdefault(uuid, []).append((full, state))
+
+    if not by_uuid:
+        return [], []
+    if len(by_uuid) > 1:
+        return [], sorted(by_uuid.keys())
+
+    files = next(iter(by_uuid.values()))
+    prio = {"active": 0, "lock": 1, "deleted": 2, "reset": 3, "backup": 4, "unknown": 9}
+    files.sort(key=lambda x: (prio.get(x[1], 9), x[0]))
+    return files, []
+
+
+def recent_session_ids(
+    base_dir: str = paths.SESSIONS_BASE,
+    limit: int = 5,
+) -> List[str]:
+    """Return the most-recently-modified active session UUIDs."""
+    found: List[Tuple[float, str]] = []
+    for ad in glob.glob(os.path.join(base_dir, "*")):
+        sd = os.path.join(ad, "sessions")
+        if not os.path.isdir(sd):
+            continue
+        try:
+            entries = os.listdir(sd)
+        except OSError:
+            continue
+        for entry in entries:
+            if not entry.endswith(".jsonl"):
+                continue
+            uuid = _session_uuid_of(entry)
+            if uuid is None or entry != f"{uuid}.jsonl":
+                continue
+            path = os.path.join(sd, entry)
+            try:
+                mtime = os.path.getmtime(path)
+            except OSError:
+                continue
+            found.append((mtime, uuid))
+    found.sort(reverse=True)
+    return [sid for _, sid in found[:limit]]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-diag-cli",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "OpenClaw observer-only diagnostic CLI. Zero-dependency Python scripts wrapped in Node for npx-friendly install.",
   "keywords": [
     "openclaw",

package/tools/oc_session_extract.py

@@ -4,16 +4,16 @@
 from __future__ import annotations
 
 import argparse
-import glob
 import json
 import os
 import sys
+from datetime import datetime, timezone
 from pathlib import Path
-from typing import List, Optional, TextIO, Tuple
+from typing import Any, Dict, List, Optional, TextIO, Tuple
 
 sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
 
-from ocdiag import paths
+from ocdiag import paths, sessions
 from ocdiag.sensitive import sanitize_text
 
 
@@ -29,61 +29,6 @@ def human_size(n: int) -> str:
     return f"{n:.1f} PB"
 
 
-def classify_state(filename: str) -> str:
-    if filename.endswith(".jsonl"):
-        return "active"
-    if ".jsonl.deleted." in filename:
-        return "deleted"
-    if ".jsonl.reset." in filename:
-        return "reset"
-    if ".jsonl.bak-" in filename:
-        return "backup"
-    return "unknown"
-
-
-def _recent_session_ids(base_dir, limit=5):
-    """Return the most-recently-modified active session UUIDs."""
-    found: List[Tuple[float, str]] = []
-    for ad in glob.glob(os.path.join(base_dir, "*")):
-        sd = os.path.join(ad, "sessions")
-        if not os.path.isdir(sd):
-            continue
-        for entry in os.listdir(sd):
-            if not entry.endswith(".jsonl"):
-                continue
-            if ".trajectory" in entry or ".jsonl.reset." in entry:
-                continue
-            path = os.path.join(sd, entry)
-            try:
-                mtime = os.path.getmtime(path)
-            except OSError:
-                continue
-            sid = entry[:-len(".jsonl")]
-            found.append((mtime, sid))
-    found.sort(reverse=True)
-    return [sid for _, sid in found[:limit]]
-
-
-def find_session_files(session_id, base_dir=DEFAULT_BASE_DIR, agent=None):
-    if agent:
-        agent_dirs = [os.path.join(base_dir, agent)]
-    else:
-        agent_dirs = sorted(glob.glob(os.path.join(base_dir, "*")))
-    found = []
-    for agent_dir in agent_dirs:
-        sessions_dir = os.path.join(agent_dir, "sessions")
-        if not os.path.isdir(sessions_dir):
-            continue
-        pattern = os.path.join(sessions_dir, f"{session_id}.jsonl*")
-        for path in sorted(glob.glob(pattern)):
-            name = os.path.basename(path)
-            if ".trajectory" in name:
-                continue
-            state = classify_state(name)
-            found.append((path, state))
-    return found
-
-
 def stream_records(path):
     with open(path, "r", encoding="utf-8", errors="replace") as f:
         for i, line in enumerate(f, start=1):
@@ -131,7 +76,6 @@ def _sanitize_record(obj):
                         v = part.get(k)
                         if isinstance(v, str):
                             part[k] = sanitize_text(v)
-        # Also scrub any top-level text-ish fields the gateway may have set.
         for k in ("text", "summary"):
             v = msg.get(k)
             if isinstance(v, str):
@@ -157,8 +101,6 @@ def extract_file(path, state, out, pretty=True, type_filter=None, sanitize=True)
         if pretty:
             out.write(json.dumps(obj, indent=2, ensure_ascii=False))
         else:
-            # Non-pretty mode: emit the (possibly sanitized) JSON or fall back
-            # to the original raw line if we didn't touch it.
             out.write(json.dumps(obj, ensure_ascii=False) if sanitize else raw)
         out.write("\n\n")
         written += 1
@@ -167,7 +109,23 @@ def extract_file(path, state, out, pretty=True, type_filter=None, sanitize=True)
 
 def summarize_file(path, state, out):
     write_header(out, path, state)
-    counts: dict = {}
+    info = _collect_summary(path, sanitize=False)
+    out.write(f"Total records: {info['total_records']}\n")
+    if info["parse_errors"]:
+        out.write(f"Parse errors: {info['parse_errors']}\n")
+    out.write("By type:\n")
+    by_type = info["by_type"]
+    for k in sorted(by_type, key=lambda k: -by_type[k]):
+        out.write(f"  {k}: {by_type[k]}\n")
+    tr = info["time_range"]
+    if tr["start"] or tr["end"]:
+        out.write(f"Time range: {tr['start'] or '?'}  →  {tr['end'] or '?'}\n")
+    out.write("\n")
+
+
+def _collect_summary(path: str, sanitize: bool = True) -> Dict[str, Any]:
+    """Walk one file and produce a summary block (used by text + JSON mode)."""
+    by_type: Dict[str, int] = {}
     total = 0
     earliest: Optional[str] = None
     latest: Optional[str] = None
@@ -178,25 +136,40 @@ def summarize_file(path, state, out):
             parse_errors += 1
             continue
         if not isinstance(obj, dict):
-            counts["<non-object>"] = counts.get("<non-object>", 0) + 1
+            by_type["<non-object>"] = by_type.get("<non-object>", 0) + 1
             continue
         rtype = obj.get("type", "<no-type>")
-        counts[rtype] = counts.get(rtype, 0) + 1
+        by_type[rtype] = by_type.get(rtype, 0) + 1
         ts = obj.get("timestamp")
         if isinstance(ts, str):
             if earliest is None or ts < earliest:
                 earliest = ts
             if latest is None or ts > latest:
                 latest = ts
-    out.write(f"Total records: {total}\n")
-    if parse_errors:
-        out.write(f"Parse errors: {parse_errors}\n")
-    out.write("By type:\n")
-    for k in sorted(counts, key=lambda k: -counts[k]):
-        out.write(f"  {k}: {counts[k]}\n")
-    if earliest or latest:
-        out.write(f"Time range: {earliest or '?'}  →  {latest or '?'}\n")
-    out.write("\n")
+    return {
+        "total_records": total,
+        "parse_errors": parse_errors,
+        "by_type": by_type,
+        "time_range": {"start": earliest, "end": latest},
+    }
+
+
+def _collect_records(path: str, type_filter, sanitize: bool) -> List[Dict]:
+    out: List[Dict] = []
+    for line_no, obj, raw, err in stream_records(path):
+        if err is not None:
+            out.append({"line": line_no, "parse_error": err, "raw": raw})
+            continue
+        if not isinstance(obj, dict):
+            out.append({"line": line_no, "value": obj})
+            continue
+        rtype = obj.get("type", "?")
+        if type_filter is not None and rtype not in type_filter:
+            continue
+        if sanitize:
+            obj = _sanitize_record(obj)
+        out.append(obj)
+    return out
 
 
 def list_files(files, out):
@@ -234,42 +207,118 @@ def select_files(files, extract_all, _out):
     return []
 
 
+def _resolve_or_die(session_id: str, base_dir: str, agent: Optional[str],
+                    include_transient: bool) -> List[Tuple[str, str]]:
+    ok, msg = sessions.is_valid_query(session_id)
+    if not ok:
+        sys.stderr.write(f"Error: {msg}\n")
+        sys.exit(2)
+    files, candidates = sessions.resolve(
+        session_id, base_dir=base_dir, agent=agent,
+        include_transient=include_transient,
+    )
+    if candidates:
+        sys.stderr.write(
+            f"Error: 前缀 '{session_id}' 匹配多个 session（请补长前缀）：\n"
+        )
+        for sid in candidates:
+            sys.stderr.write(f"    {sid}\n")
+        sys.exit(1)
+    if not files:
+        sys.stderr.write(
+            f"Error: 找不到 session '{session_id}'（在 {base_dir} 下）"
+            + (f" agent={agent}" if agent else "")
+            + "\n"
+        )
+        suggestions = sessions.recent_session_ids(base_dir, limit=5)
+        if suggestions:
+            sys.stderr.write("  最近的 5 个 session：\n")
+            for sid in suggestions:
+                sys.stderr.write(f"    {sid}\n")
+            sys.stderr.write("  提示：完整 UUID 或前缀（至少 8 位）都可。\n")
+        sys.exit(1)
+    return files
+
+
+def _emit_json(session_id: str, selected: List[Tuple[str, str]],
+               out_fp: TextIO, summary_only: bool, type_filter,
+               sanitize: bool) -> None:
+    files_payload: List[Dict[str, Any]] = []
+    aggregate_total = 0
+    aggregate_by_type: Dict[str, int] = {}
+    aggregate_start: Optional[str] = None
+    aggregate_end: Optional[str] = None
+    for path, state in selected:
+        try:
+            size = os.path.getsize(path)
+        except OSError:
+            size = 0
+        entry: Dict[str, Any] = {
+            "path": path,
+            "state": state,
+            "size_bytes": size,
+        }
+        if summary_only:
+            s = _collect_summary(path, sanitize=sanitize)
+            entry["summary"] = s
+            aggregate_total += s["total_records"]
+            for k, v in s["by_type"].items():
+                aggregate_by_type[k] = aggregate_by_type.get(k, 0) + v
+            tr = s["time_range"]
+            if tr["start"] and (aggregate_start is None or tr["start"] < aggregate_start):
+                aggregate_start = tr["start"]
+            if tr["end"] and (aggregate_end is None or tr["end"] > aggregate_end):
+                aggregate_end = tr["end"]
+        else:
+            entry["records"] = _collect_records(path, type_filter, sanitize=sanitize)
+        files_payload.append(entry)
+
+    payload: Dict[str, Any] = {
+        "session_id": session_id,
+        "files": files_payload,
+        "generated_at": datetime.now(tz=timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "sanitized": sanitize,
+    }
+    if summary_only:
+        payload["summary"] = {
+            "total_records": aggregate_total,
+            "by_type": aggregate_by_type,
+            "time_range": {"start": aggregate_start, "end": aggregate_end},
+        }
+    out_fp.write(json.dumps(payload, ensure_ascii=False, indent=2))
+    out_fp.write("\n")
+
+
 def main() -> int:
     p = argparse.ArgumentParser(
         prog=os.environ.get("OPENCLAW_DIAG_PROG") or None,
         description="Extract OpenClaw session JSONL files into human-readable format.",
         formatter_class=argparse.ArgumentDefaultsHelpFormatter,
     )
-    p.add_argument("session_id", help="Session UUID to extract")
+    p.add_argument("session_id", help="Session UUID (full or 8+ char prefix)")
     p.add_argument("-o", "--output", help="Write output to FILE instead of stdout")
     p.add_argument("-a", "--all", action="store_true",
-                   help="Extract all versions found (active + deleted + reset + backup)")
-    p.add_argument("--list", action="store_true", help="List found files; do not extract")
+                   help="Extract all versions (active + reset + deleted + backup + lock)")
+    p.add_argument("--list", action="store_true",
+                   help="List all matching files (incl. .lock); do not extract")
     p.add_argument("--agent", help="Limit search to specific agent directory")
     p.add_argument("--base-dir", default=DEFAULT_BASE_DIR, help="Override base directory")
     p.add_argument("--no-pretty", action="store_true", help="Output raw JSON lines")
     p.add_argument("--types", help="Filter by record type (comma-separated, e.g. 'message,toolCall')")
     p.add_argument("--summary", action="store_true",
                    help="Show record-count summary instead of full extraction")
+    p.add_argument("--json", action="store_true",
+                   help="Emit structured JSON (compatible with state collectors' --json)")
     p.add_argument("--unmask", action="store_true",
                    help="Disable default sanitization of secret-shaped substrings "
                         "in message content (off = scrubbed)")
     args = p.parse_args()
 
-    files = find_session_files(args.session_id, args.base_dir, args.agent)
-    if not files:
-        sys.stderr.write(
-            f"Error: 找不到 session '{args.session_id}'（在 {args.base_dir} 下）"
-            + (f" agent={args.agent}" if args.agent else "")
-            + "\n"
-        )
-        suggestions = _recent_session_ids(args.base_dir, limit=5)
-        if suggestions:
-            sys.stderr.write("  最近的 5 个 session：\n")
-            for sid in suggestions:
-                sys.stderr.write(f"    {sid}\n")
-            sys.stderr.write("  提示：完整 UUID 或前缀（至少 8 位）都可。\n")
-        return 1
+    # --list and --all see lock files; default mode hides them so non-interactive
+    # callers (cron, jq pipes) don't trip on a transient .jsonl.lock sibling.
+    include_transient = bool(args.all or args.list)
+    files = _resolve_or_die(args.session_id, args.base_dir, args.agent,
+                            include_transient=include_transient)
 
     if args.list:
         list_files(files, sys.stdout)
@@ -294,12 +343,18 @@ def main() -> int:
         out_fp = sys.stdout
 
     try:
-        for path, state in selected:
-            if args.summary:
-                summarize_file(path, state, out_fp)
-            else:
-                extract_file(path, state, out_fp, pretty=not args.no_pretty,
-                             type_filter=type_filter, sanitize=not args.unmask)
+        if args.json:
+            _emit_json(args.session_id, selected, out_fp,
+                       summary_only=args.summary,
+                       type_filter=type_filter,
+                       sanitize=not args.unmask)
+        else:
+            for path, state in selected:
+                if args.summary:
+                    summarize_file(path, state, out_fp)
+                else:
+                    extract_file(path, state, out_fp, pretty=not args.no_pretty,
+                                 type_filter=type_filter, sanitize=not args.unmask)
     except BrokenPipeError:
         try:
             sys.stdout.flush()

package/tools/oc_session_trace.py

@@ -21,7 +21,7 @@ from typing import Any, Dict, List, Optional, Tuple
 
 sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
 
-from ocdiag import paths
+from ocdiag import paths, sessions
 
 
 DEFAULT_BASE_DIR = paths.SESSIONS_BASE
@@ -67,64 +67,25 @@ def extract_text(content: Any) -> str:
     return str(content)
 
 
-def find_session_file(
+def resolve_session_file(
     session_id: str,
     base_dir: str = DEFAULT_BASE_DIR,
     agent: Optional[str] = None,
-) -> Optional[str]:
-    if agent:
-        agent_dirs = [os.path.join(base_dir, agent)]
-    else:
-        agent_dirs = sorted(glob.glob(os.path.join(base_dir, "*")))
-
-    candidates: List[Tuple[str, str]] = []
-    for ad in agent_dirs:
-        sd = os.path.join(ad, "sessions")
-        if not os.path.isdir(sd):
-            continue
-        for entry in os.listdir(sd):
-            if not entry.startswith(session_id):
-                continue
-            if ".trajectory" in entry or entry.endswith(".json"):
-                continue
-            full = os.path.join(sd, entry)
-            if not os.path.isfile(full):
-                continue
-            if entry == f"{session_id}.jsonl":
-                candidates.append((full, "active"))
-            elif ".jsonl.deleted." in entry:
-                candidates.append((full, "deleted"))
-            elif ".jsonl.reset." in entry:
-                candidates.append((full, "reset"))
-            elif ".jsonl.bak-" in entry:
-                candidates.append((full, "backup"))
-
-    prio = {"active": 0, "deleted": 1, "reset": 2, "backup": 3}
-    candidates.sort(key=lambda x: prio.get(x[1], 9))
-    return candidates[0][0] if candidates else None
-
-
-def _recent_session_ids(base_dir: str, limit: int = 5) -> List[str]:
-    """Return the most-recently-modified active session UUIDs (no .reset/.bak/.deleted)."""
-    found: List[Tuple[float, str]] = []
-    for ad in glob.glob(os.path.join(base_dir, "*")):
-        sd = os.path.join(ad, "sessions")
-        if not os.path.isdir(sd):
-            continue
-        for entry in os.listdir(sd):
-            if not entry.endswith(".jsonl"):
-                continue
-            if ".trajectory" in entry or ".jsonl.reset." in entry:
-                continue
-            path = os.path.join(sd, entry)
-            try:
-                mtime = os.path.getmtime(path)
-            except OSError:
-                continue
-            sid = entry[:-len(".jsonl")]
-            found.append((mtime, sid))
-    found.sort(reverse=True)
-    return [sid for _, sid in found[:limit]]
+) -> Tuple[Optional[str], List[str]]:
+    """Resolve UUID-or-prefix to a single session file path.
+
+    Returns ``(path, candidates)``. ``path`` is None on miss or ambiguity;
+    ``candidates`` is non-empty only when the prefix matched multiple
+    distinct session UUIDs.
+    """
+    files, candidates = sessions.resolve(
+        session_id, base_dir=base_dir, agent=agent, include_transient=False,
+    )
+    if candidates:
+        return None, candidates
+    if not files:
+        return None, []
+    return files[0][0], []
 
 
 def find_trajectory_file(session_file: str) -> Optional[str]:
@@ -666,11 +627,25 @@ def main():
     parser.add_argument("--json", action="store_true", help="Output as structured JSON")
     args = parser.parse_args()
 
-    session_file = find_session_file(args.session_id, args.base_dir, args.agent)
+    ok, msg = sessions.is_valid_query(args.session_id)
+    if not ok:
+        print(f"Error: {msg}", file=sys.stderr)
+        sys.exit(2)
+    session_file, candidates = resolve_session_file(
+        args.session_id, args.base_dir, args.agent,
+    )
+    if candidates:
+        print(
+            f"Error: 前缀 '{args.session_id}' 匹配多个 session（请补长前缀）：",
+            file=sys.stderr,
+        )
+        for sid in candidates:
+            print(f"    {sid}", file=sys.stderr)
+        sys.exit(1)
     if not session_file:
         print(f"Error: 找不到 session '{args.session_id}'（在 {args.base_dir} 下）",
               file=sys.stderr)
-        suggestions = _recent_session_ids(args.base_dir, limit=5)
+        suggestions = sessions.recent_session_ids(args.base_dir, limit=5)
         if suggestions:
             print(f"  最近的 5 个 session：", file=sys.stderr)
             for sid in suggestions:
@@ -678,6 +653,11 @@ def main():
             print(f"  提示：UUID 完整 36 位，前缀也可（至少 8 位）。", file=sys.stderr)
         sys.exit(1)
 
+    # If the user passed a prefix, recover the full UUID from the resolved
+    # filename so log lookups and JSON output use the canonical id.
+    resolved_basename = os.path.basename(session_file)
+    full_session_id = resolved_basename.split(".jsonl", 1)[0]
+
     records = load_records(session_file)
     if not records:
         print(f"Error: session file is empty: {session_file}", file=sys.stderr)
@@ -708,13 +688,13 @@ def main():
     if not args.no_log:
         log_files = find_gateway_logs(args.log_dir)
         if log_files:
-            gw_info = load_gateway_timing(log_files, args.session_id, analysis["base_epoch_ms"])
+            gw_info = load_gateway_timing(log_files, full_session_id, analysis["base_epoch_ms"])
 
     if args.json:
-        out_str = format_json(args.session_id, session_file, user_msg_ordinal,
+        out_str = format_json(full_session_id, session_file, user_msg_ordinal,
                               user_msg_id, analysis, traj_info, gw_info)
     else:
-        out_str = format_text(args.session_id, user_msg_ordinal, user_msg_id,
+        out_str = format_text(full_session_id, user_msg_ordinal, user_msg_id,
                               analysis, traj_info, gw_info)
 
     if args.output: