agent-log-verifier 0.3.0__py3-none-any.whl

agent_log_verifier/__init__.py

@@ -0,0 +1,3 @@
+"""agent-log-verifier: post-hoc, read-only verification for AI agent transcript logs."""
+
+__version__ = "0.3.0"

agent_log_verifier/cli.py

@@ -0,0 +1,600 @@
+"""CLI entrypoint: scan / watch / report subcommands.
+
+Design doc reference: 2026-07-11_agent-log-verifier_spec_desktop.md
+section 5 (CLI spec) and section 3-2 (registration/execution flow):
+
+  cli.py
+    -> parser.parse_jsonl(path) -> list[NormalizedEvent]
+    -> registry.run_all(events, order_prompt=extracted_prompt)
+    -> report.render(findings_dict, format=cli_output|json|markdown)
+
+argparse is used per design doc 7-1 ("標準ライブラリの argparse で
+scan/watch/report のサブコマンドを賄えるため、追加依存を避けたい場合は
+argparse を優先してよい") -- chosen here to avoid an extra dependency.
+
+Review-fix note (python-reviewer HIGH, 2026-07-11): liveness previously
+only ran ComplianceDetector-style single-transcript staleness checks via
+DetectorRegistry, never the richer parent-session-correlated
+infer_completion_status() path -- despite liveness.py's own docstring
+claiming "cli.py orchestrates that richer check directly". This module
+now actually does that orchestration: for each discovered subagent
+JSONL, it (a) reads the sibling .meta.json into a SubagentMeta, (b)
+locates the corresponding parent session JSONL by walking up past the
+subagents/ directory component to find <project-dir>/<session-id>.jsonl,
+(c) calls build_liveness_finding() (which calls infer_completion_status())
+to get a Finding whose `judgement` carries the exact
+running/completed/stopped_suspected/unknown 4-value status, and (d)
+surfaces that in the same findings["liveness"] list the CLI/JSON/markdown
+renderers already read from. Because this liveness path needs additional
+context (parent_events, subagent_meta) DetectorRegistry's Detector
+interface does not carry, liveness is intentionally NOT registered
+through DetectorRegistry at all in run_scan(); it is computed directly
+alongside registry.run_all() for the other (compliance) detectors, then
+merged into the same findings dict. --detector liveness/compliance
+filtering is preserved by simply skipping the liveness computation (or
+the registry-based detectors) when excluded.
+"""
+
+from __future__ import annotations
+
+import argparse
+import contextlib
+import sys
+import time
+from datetime import datetime, UTC
+from pathlib import Path
+from typing import Any
+
+from agent_log_verifier.detectors.base import DetectorRegistry, Finding
+from agent_log_verifier.detectors.compliance import ComplianceDetector, segment_main_session_into_turns
+from agent_log_verifier.detectors.completeness import CompletenessDetector
+from agent_log_verifier.detectors.incident import IncidentDetector
+from agent_log_verifier.detectors.loops import LoopDetector
+from agent_log_verifier.detectors.scope import ScopeDetector
+from agent_log_verifier.detectors.liveness import (
+    STALE_THRESHOLD_MINUTES_DEFAULT,
+    STOPPED_THRESHOLD_MINUTES_DEFAULT,
+    build_liveness_finding,
+)
+from agent_log_verifier.models.events import NormalizedEvent, SubagentMeta
+from agent_log_verifier.parser.claude_code import extract_order_prompt, parse_jsonl
+from agent_log_verifier.report.cli_output import render_cli
+from agent_log_verifier.report.breakdown import ErrorBreakdown, tally_error_breakdown
+from agent_log_verifier.report.html_output import render_html
+from agent_log_verifier.report.json_output import render_json
+from agent_log_verifier.report.markdown_output import render_markdown
+
+_DEFAULT_POLL_INTERVAL_SECONDS = 10
+_DEFAULT_DASHBOARD_FILENAME = "alv-dashboard.html"
+
+
+def _discover_transcripts(target: Path) -> tuple[list[Path], list[Path]]:
+    """Given a Claude Code project directory (or a single .jsonl file),
+    return (main_session_paths, subagent_paths).
+
+    This directory-walking scheme is not specified at the pseudocode
+    level by the design doc (5-1/5-2 describe the CLI surface, not the
+    filesystem discovery algorithm); implemented per the real project
+    layout confirmed in design doc section 1 and section 10 (top-level
+    session JSONL files, with a `subagents/` subdirectory per session
+    containing `agent-*.jsonl` and `agent-*.meta.json`, including nested
+    `subagents/workflows/wf_<id>/agent-*.meta.json` for workflow-subagent
+    patterns).
+    """
+    if target.is_file():
+        return [target], []
+
+    main_sessions: list[Path] = []
+    subagent_sessions: list[Path] = []
+
+    for jsonl_path in sorted(target.glob("**/*.jsonl")):
+        if "subagents" in jsonl_path.parts:
+            # Workflow run directories keep an orchestration journal
+            # (subagents/workflows/wf_<id>/journal.jsonl) alongside the
+            # agent-*.jsonl transcripts. It is bookkeeping, not an agent
+            # -- counting it produced ghost "journal (unknown)" liveness
+            # rows on the dashboard (observed on the 2026-07-11 real
+            # scan: 9 such rows).
+            if jsonl_path.stem == "journal":
+                continue
+            subagent_sessions.append(jsonl_path)
+        else:
+            main_sessions.append(jsonl_path)
+
+    return main_sessions, subagent_sessions
+
+
+def _find_parent_session_jsonl(subagent_jsonl_path: Path) -> Path | None:
+    """Given a subagent transcript path (e.g.
+    <project-dir>/<session-id>/subagents/agent-foo.jsonl, or the nested
+    .../subagents/workflows/wf_<id>/agent-foo.jsonl form), locate the
+    corresponding parent/main session transcript at
+    <project-dir>/<session-id>.jsonl.
+
+    This directory-walking scheme is likewise not specified at
+    pseudocode level by the design doc; implemented per the real project
+    layout confirmed in design doc sections 1 and 10, where a session's
+    subagents live under a directory named after that session's own
+    UUID, itself a sibling of <session-id>.jsonl.
+    """
+    parts = subagent_jsonl_path.parts
+    if "subagents" not in parts:
+        return None
+
+    subagents_index = parts.index("subagents")
+    if subagents_index == 0:
+        return None
+
+    session_dir = Path(*parts[:subagents_index])
+    session_id = session_dir.name
+    candidate = session_dir.parent / f"{session_id}.jsonl"
+    if candidate.is_file():
+        return candidate
+    return None
+
+
+def _find_subagent_meta_path(subagent_jsonl_path: Path) -> Path | None:
+    """A subagent's .meta.json sibling file uses the same stem as its
+    .jsonl transcript (e.g. agent-foo.jsonl -> agent-foo.meta.json),
+    confirmed by design doc section 1-4 and section 10's real-data
+    examples (agent-<id>.jsonl alongside agent-<id>.meta.json)."""
+    candidate = subagent_jsonl_path.with_suffix("").with_suffix(".meta.json")
+    if candidate.is_file():
+        return candidate
+    return None
+
+
+def _load_subagent_meta(meta_path: Path | None) -> SubagentMeta:
+    """Read a .meta.json file into a SubagentMeta. If the file is
+    missing or unreadable, fall back to a minimal SubagentMeta with an
+    'unknown' agentType and no toolUseId -- this degrades gracefully to
+    the 'unknown' completion-status branch rather than crashing the scan
+    (consistent with the project's overall "never raise for malformed
+    input" policy, design doc 2-1/2-3)."""
+    if meta_path is None:
+        return SubagentMeta(agentType="unknown")
+
+    try:
+        import json
+
+        raw = json.loads(meta_path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return SubagentMeta(agentType="unknown")
+
+    if not isinstance(raw, dict):
+        return SubagentMeta(agentType="unknown")
+
+    try:
+        return SubagentMeta.model_validate(raw)
+    except Exception:
+        return SubagentMeta(agentType="unknown")
+
+
+def _latest_event_timestamp(events: list[NormalizedEvent]) -> datetime | None:
+    """[Coordinator addition, 2026-07-11 UI-redesign request]: compliance
+    Findings carry no timestamp of their own (Finding's schema in
+    detectors/base.py has no such field, and this module must not modify
+    detectors/ or parser/ per the request's own constraint). The
+    dashboard's "直近24時間のみ表示" default for compliance findings needs
+    *some* notion of "when did this finding happen" to filter by, so this
+    reads it off the same event list the finding was computed from
+    instead: the latest timestamp among the turn-segment (main session)
+    or subagent transcript events that _scan_compliance() was just run
+    against. This is an approximation (a finding technically corresponds
+    to one order-prompt+response exchange, not literally the transcript's
+    very last event), but it is the only signal available without
+    touching Finding's schema, and is accurate enough for "is this recent
+    or old" bucketing.
+    """
+    if not events:
+        return None
+    return max(e.timestamp for e in events)
+
+
+def _tag_findings_with_reference_timestamp(
+    findings: dict[str, list[Finding]],
+    *,
+    reference_timestamp: datetime | None,
+) -> dict[str, list[Finding]]:
+    """Stamps every Finding in `findings` with a `reference_timestamp`
+    extra field (Finding.model_config allows extra fields; see
+    detectors/base.py) via model_copy(update=...), so
+    report/html_output.py can bucket compliance findings into "直近24時間"
+    vs "過去分" without any changes to the Finding schema itself or to
+    detectors/compliance.py. A None reference_timestamp (empty event
+    list, defensively) leaves findings untagged -- html_output.py treats
+    a missing reference_timestamp as "recent" (fail open toward
+    visibility rather than silently hiding an unattributable finding;
+    see html_output.py's _CompliancRow.is_recent).
+    """
+    if reference_timestamp is None:
+        return findings
+    iso_ts = reference_timestamp.isoformat()
+    return {
+        detector_name: [f.model_copy(update={"reference_timestamp": iso_ts}) for f in detector_findings]
+        for detector_name, detector_findings in findings.items()
+    }
+
+
+def _scan_compliance(
+    events: list[NormalizedEvent],
+    *,
+    order_prompt: str | None,
+    registry: DetectorRegistry,
+) -> dict[str, list[Finding]]:
+    findings = registry.run_all(events, order_prompt=order_prompt)
+    return _tag_findings_with_reference_timestamp(findings, reference_timestamp=_latest_event_timestamp(events))
+
+
+def _merge_findings(target: dict[str, list[Finding]], source: dict[str, list[Finding]]) -> None:
+    for detector_name, detector_findings in source.items():
+        target.setdefault(detector_name, [])
+        target[detector_name].extend(detector_findings)
+
+
+def _build_registry(*, detector_filter: list[str] | None) -> DetectorRegistry:
+    """Registers only ComplianceDetector -- liveness is deliberately
+    orchestrated separately in run_scan() (see module docstring) because
+    it needs parent_events/subagent_meta context the Detector interface
+    does not carry.
+    """
+    registry = DetectorRegistry()
+    all_detectors: dict[str, Any] = {
+        "compliance": ComplianceDetector(),
+        "loop": LoopDetector(),
+        "incident": IncidentDetector(),
+        "completeness": CompletenessDetector(),
+        "scope": ScopeDetector(),
+    }
+    names_to_register = detector_filter if detector_filter else list(all_detectors.keys())
+    for name in names_to_register:
+        if name in all_detectors:
+            registry.register(all_detectors[name])
+    return registry
+
+
+def run_scan(
+    target: Path,
+    *,
+    stale_minutes: float = STALE_THRESHOLD_MINUTES_DEFAULT,
+    stopped_minutes: float = STOPPED_THRESHOLD_MINUTES_DEFAULT,
+    detector_filter: list[str] | None = None,
+    include_subagents: bool = True,
+) -> tuple[dict[str, int], dict[str, list[Finding]], ErrorBreakdown]:
+    """Design doc 5-1: scan a project directory or single .jsonl file.
+    Returns (sessions_summary, findings_by_detector, error_breakdown).
+
+    error_breakdown is the tool_result error tally used by the dashboard
+    '内訳' tab (BACKLOG B-3). It is computed inside this same walk so
+    events are not re-parsed.
+    """
+    detectors_wanted = (
+        detector_filter
+        if detector_filter
+        else ["compliance", "loop", "incident", "completeness", "scope", "liveness"]
+    )
+    registry = _build_registry(detector_filter=[d for d in detectors_wanted if d != "liveness"])
+    liveness_wanted = "liveness" in detectors_wanted
+
+    main_sessions, subagent_sessions = _discover_transcripts(target)
+    if not include_subagents:
+        subagent_sessions = []
+
+    all_findings: dict[str, list[Finding]] = {}
+    all_events: list[NormalizedEvent] = []
+    now = datetime.now(UTC)
+
+    # Pre-parse every main-session transcript once; subagent liveness
+    # correlation below re-uses these parsed events rather than
+    # re-reading a parent JSONL file per subagent.
+    #
+    # v0.2 design doc 5-3: a main-session transcript is segmented into
+    # independent user free-text turns (design doc 5-1's real-data finding
+    # that main sessions hold up to 245 such turns, not the single
+    # "1 prompt = 1 task" shape a subagent transcript has) and compliance
+    # is run independently per turn, so constraints in turn 2, 3, ... are
+    # not silently skipped by only ever looking at the first user event
+    # (which is what a single unsegmented extract_order_prompt() call
+    # would do). main_session_events[path] itself still stores the FULL,
+    # unsegmented event list (not per-turn segments) -- subagent parent-
+    # session correlation below (_find_parent_session_jsonl /
+    # infer_completion_status) needs the whole transcript to search across
+    # turn boundaries for a matching tool_result.
+    main_session_events: dict[Path, list[NormalizedEvent]] = {}
+    for path in main_sessions:
+        events, _warnings = parse_jsonl(path)
+        main_session_events[path] = events
+        all_events.extend(events)
+
+        turn_segments = segment_main_session_into_turns(events)
+        for segment in turn_segments:
+            order_prompt = extract_order_prompt(segment)
+            if not order_prompt:
+                continue
+            findings = _scan_compliance(segment, order_prompt=order_prompt, registry=registry)
+            _merge_findings(all_findings, findings)
+
+    for path in subagent_sessions:
+        subagent_events, _warnings = parse_jsonl(path)
+        all_events.extend(subagent_events)
+
+        parent_path = _find_parent_session_jsonl(path)
+        if parent_path is not None:
+            parent_events = main_session_events.get(parent_path)
+            if parent_events is None:
+                parent_events, _pw = parse_jsonl(parent_path)
+                main_session_events[parent_path] = parent_events
+        else:
+            parent_events = []
+
+        parent_tool_use_id = None
+        meta_path = _find_subagent_meta_path(path)
+        subagent_meta = _load_subagent_meta(meta_path)
+        if subagent_meta.tool_use_id is not None:
+            parent_tool_use_id = subagent_meta.tool_use_id
+
+        order_prompt = extract_order_prompt(
+            subagent_events,
+            parent_events=parent_events,
+            parent_tool_use_id=parent_tool_use_id,
+        )
+        findings = _scan_compliance(subagent_events, order_prompt=order_prompt, registry=registry)
+        _merge_findings(all_findings, findings)
+
+        if liveness_wanted:
+            liveness_finding = build_liveness_finding(
+                agent_label=path.stem,
+                subagent_events=subagent_events,
+                parent_events=parent_events,
+                subagent_meta=subagent_meta,
+                now=now,
+                stale_threshold_minutes=stale_minutes,
+            )
+            all_findings.setdefault("liveness", [])
+            all_findings["liveness"].append(liveness_finding)
+
+    # Presentation-level fold: LOOP/INCIDENT/COMPLETENESS findings ride
+    # in the same rule_id/judgement table as COMPLIANCE-00x (their
+    # judgement is 逸脱疑い, so the hero counter / amber banner /
+    # default filter all treat them as attention-worthy without any
+    # renderer changes); the rule_id column and its filter keep them
+    # distinguishable.
+    for extra_detector in ("loop", "incident", "completeness", "scope"):
+        if extra_detector in all_findings:
+            all_findings.setdefault("compliance", []).extend(all_findings.pop(extra_detector))
+
+    sessions = {"main": len(main_sessions), "subagents": len(subagent_sessions)}
+    breakdown = tally_error_breakdown(all_events)
+    return sessions, all_findings, breakdown
+
+
+def _render(
+    *,
+    fmt: str,
+    scan_target: str,
+    sessions: dict[str, int],
+    findings: dict[str, list[Finding]],
+) -> str:
+    if fmt == "json":
+        return render_json(scan_target=scan_target, sessions=sessions, findings=findings)
+    if fmt == "markdown":
+        return render_markdown(scan_target=scan_target, sessions=sessions, findings=findings)
+    return render_cli(scan_target=scan_target, sessions=sessions, findings=findings)
+
+
+def _write_output(rendered: str, output_path: str | None) -> None:
+    if output_path:
+        Path(output_path).write_text(rendered, encoding="utf-8")
+    else:
+        print(rendered)
+
+
+def _cmd_scan(args: argparse.Namespace) -> int:
+    target = Path(args.path)
+    detector_filter = args.detector.split(",") if args.detector else None
+
+    sessions, findings, _breakdown = run_scan(
+        target,
+        stale_minutes=args.stale_minutes,
+        stopped_minutes=args.stopped_minutes,
+        detector_filter=detector_filter,
+        include_subagents=args.include_subagents,
+    )
+    rendered = _render(fmt=args.format, scan_target=str(target), sessions=sessions, findings=findings)
+    _write_output(rendered, args.output)
+    return 0
+
+
+def _cmd_report(args: argparse.Namespace) -> int:
+    # Design doc 5-1: report is scan's alias, output-to-file oriented.
+    return _cmd_scan(args)
+
+
+def _cmd_watch(args: argparse.Namespace) -> int:
+    """Design doc 5-1: watch polls scan on an interval and re-renders on
+    each tick. A simple sleep-based polling loop (no inotify/watchdog),
+    per design doc 4-3/5-1 ("標準ライブラリ中心" / "time.sleepベースの
+    ポーリングに留める").
+    """
+    target = Path(args.path)
+    try:
+        while True:
+            sessions, findings, _breakdown = run_scan(
+                target,
+                stale_minutes=args.stale_minutes,
+                stopped_minutes=args.stopped_minutes,
+                detector_filter=["liveness"],
+                include_subagents=True,
+            )
+            rendered = _render(fmt="cli", scan_target=str(target), sessions=sessions, findings=findings)
+            print(f"\n--- {datetime.now(UTC).isoformat()} ---")
+            print(rendered)
+            time.sleep(args.poll_interval)
+    except KeyboardInterrupt:
+        return 0
+
+
+def _cmd_dashboard(args: argparse.Namespace) -> int:
+    """`alv dashboard <path>`: run a single scan and write a self-
+    contained, single-shot HTML report (report/html_output.py's
+    render_html()), then open it in the default browser unless
+    --no-open was passed. This is a one-shot snapshot for quick local
+    viewing/sharing -- see _cmd_serve below for the auto-refreshing live
+    view.
+    """
+    import webbrowser
+
+    target = Path(args.path)
+    detector_filter = args.detector.split(",") if args.detector else None
+
+    sessions, findings, breakdown = run_scan(
+        target,
+        stale_minutes=args.stale_minutes,
+        stopped_minutes=args.stopped_minutes,
+        detector_filter=detector_filter,
+        include_subagents=args.include_subagents,
+    )
+    rendered = render_html(
+        scan_target=str(target), sessions=sessions, findings=findings, breakdown=breakdown
+    )
+
+    output_path = Path(args.output) if args.output else Path(_DEFAULT_DASHBOARD_FILENAME)
+    output_path.write_text(rendered, encoding="utf-8")
+    print(f"wrote {output_path}")
+
+    if args.open:
+        webbrowser.open(output_path.resolve().as_uri())
+
+    return 0
+
+
+def _cmd_serve(args: argparse.Namespace) -> int:
+    """`alv serve <path>`: start the live-mode local HTTP server
+    (server.py). Imported locally (not at module top level) to avoid a
+    cli.py <-> server.py import cycle -- server.py itself imports
+    run_scan from this module, since the live server's background scan
+    loop is the same run_scan() `alv scan`/`alv dashboard` already use.
+    """
+    from agent_log_verifier.server import DEFAULT_PORT, serve_dashboard
+
+    target = Path(args.path)
+    detector_filter = args.detector.split(",") if args.detector else None
+
+    serve_dashboard(
+        target,
+        port=args.port if args.port is not None else DEFAULT_PORT,
+        poll_interval_seconds=args.interval,
+        stale_minutes=args.stale_minutes,
+        stopped_minutes=args.stopped_minutes,
+        detector_filter=detector_filter,
+        include_subagents=args.include_subagents,
+        open_browser=args.open,
+    )
+    return 0
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="alv", description="agent-log-verifier: post-hoc, read-only transcript verification")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    def add_common_scan_options(sp: argparse.ArgumentParser) -> None:
+        sp.add_argument("path", help="Claude Code project directory or a single .jsonl file")
+        sp.add_argument("--format", choices=["cli", "json", "markdown"], default="cli")
+        sp.add_argument("--output", default=None, help="Output file path (default: stdout)")
+        sp.add_argument("--detector", default=None, help="Comma-separated detector names (default: all)")
+        sp.add_argument("--stale-minutes", type=float, default=STALE_THRESHOLD_MINUTES_DEFAULT)
+        sp.add_argument("--stopped-minutes", type=float, default=STOPPED_THRESHOLD_MINUTES_DEFAULT)
+        # Review-fix note (python-reviewer [small], 2026-07-11): the
+        # previous `action="store_true", default=True` meant
+        # --include-subagents was a permanent no-op and there was no way
+        # to set it to False at all. BooleanOptionalAction provides both
+        # --include-subagents (explicit true, matching the design doc 5-2
+        # option table's flag name) and --no-include-subagents.
+        sp.add_argument("--include-subagents", action=argparse.BooleanOptionalAction, default=True)
+
+    scan_parser = subparsers.add_parser("scan", help="Analyze a project directory or JSONL file once")
+    add_common_scan_options(scan_parser)
+    scan_parser.set_defaults(func=_cmd_scan)
+
+    report_parser = subparsers.add_parser("report", help="Alias for scan, output-to-file oriented")
+    add_common_scan_options(report_parser)
+    report_parser.set_defaults(func=_cmd_report)
+
+    watch_parser = subparsers.add_parser("watch", help="Continuously poll and display liveness status")
+    watch_parser.add_argument("path", help="Claude Code project directory")
+    watch_parser.add_argument("--stale-minutes", type=float, default=STALE_THRESHOLD_MINUTES_DEFAULT)
+    watch_parser.add_argument("--stopped-minutes", type=float, default=STOPPED_THRESHOLD_MINUTES_DEFAULT)
+    watch_parser.add_argument("--poll-interval", type=float, default=_DEFAULT_POLL_INTERVAL_SECONDS)
+    watch_parser.set_defaults(func=_cmd_watch)
+
+    dashboard_parser = subparsers.add_parser(
+        "dashboard", help="Run one scan and write a self-contained HTML report"
+    )
+    dashboard_parser.add_argument("path", help="Claude Code project directory or a single .jsonl file")
+    dashboard_parser.add_argument(
+        "--output", default=None, help=f"Output HTML file path (default: ./{_DEFAULT_DASHBOARD_FILENAME})"
+    )
+    dashboard_parser.add_argument("--detector", default=None, help="Comma-separated detector names (default: all)")
+    dashboard_parser.add_argument("--stale-minutes", type=float, default=STALE_THRESHOLD_MINUTES_DEFAULT)
+    dashboard_parser.add_argument("--stopped-minutes", type=float, default=STOPPED_THRESHOLD_MINUTES_DEFAULT)
+    dashboard_parser.add_argument("--include-subagents", action=argparse.BooleanOptionalAction, default=True)
+    dashboard_parser.add_argument(
+        "--open", action=argparse.BooleanOptionalAction, default=True, help="Open the report in a browser (default: true)"
+    )
+    dashboard_parser.set_defaults(func=_cmd_dashboard)
+
+    serve_parser = subparsers.add_parser(
+        "serve", help="Start a local live-updating dashboard server (Ctrl+C to stop)"
+    )
+    serve_parser.add_argument("path", help="Claude Code project directory")
+    serve_parser.add_argument("--port", type=int, default=None, help="TCP port to bind on 127.0.0.1 (default: 8799)")
+    serve_parser.add_argument(
+        "--interval", type=float, default=_DEFAULT_POLL_INTERVAL_SECONDS, help="Re-scan interval in seconds (default: 10)"
+    )
+    serve_parser.add_argument("--detector", default=None, help="Comma-separated detector names (default: all)")
+    serve_parser.add_argument("--stale-minutes", type=float, default=STALE_THRESHOLD_MINUTES_DEFAULT)
+    serve_parser.add_argument("--stopped-minutes", type=float, default=STOPPED_THRESHOLD_MINUTES_DEFAULT)
+    serve_parser.add_argument("--include-subagents", action=argparse.BooleanOptionalAction, default=True)
+    serve_parser.add_argument(
+        "--open", action=argparse.BooleanOptionalAction, default=True, help="Open the browser on start (default: true)"
+    )
+    serve_parser.set_defaults(func=_cmd_serve)
+
+    return parser
+
+
+def _tolerate_console_encoding() -> None:
+    """Degrade unencodable output characters instead of crashing.
+
+    Windows consoles default to a legacy codepage (cp932 on Japanese
+    Windows) with strict error handling, and findings text is arbitrary
+    transcript content -- any single character outside that codepage
+    would otherwise abort the whole scan with UnicodeEncodeError (first
+    real-world hit 2026-07-14: the CLI banner's em dash under a piped
+    cp932 stdout). File output is unaffected: it is always written with
+    an explicit UTF-8 encoding.
+    """
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is None:
+            continue
+        # A pseudo-console that rejects reconfiguration keeps its
+        # original behavior; not worth failing the command over.
+        with contextlib.suppress(OSError, ValueError):
+            reconfigure(errors="replace")
+
+
+def main(argv: list[str] | None = None) -> int:
+    _tolerate_console_encoding()
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    # args.func is set dynamically via set_defaults(func=...) per
+    # subcommand (argparse.Namespace attributes are inherently untyped),
+    # so mypy sees this call as returning Any. Explicitly permitted by
+    # the review-fix instructions to silence via type: ignore rather than
+    # over-engineering a typed dispatch table for a 3-subcommand CLI.
+    return args.func(args)  # type: ignore[no-any-return]
+
+
+if __name__ == "__main__":
+    sys.exit(main())

agent_log_verifier/detectors/base.py

@@ -0,0 +1,75 @@
+"""Common detector interface (Detector / Finding / DetectorRegistry).
+
+Design doc reference: 2026-07-11_agent-log-verifier_spec_desktop.md
+section 3-1. The design doc's Finding class used an intentionally
+simplified `BaseModel := __import__("pydantic").BaseModel` sketch and
+explicitly notes (footnote after the code block) that real implementation
+should just `from pydantic import BaseModel` normally -- done below.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from enum import StrEnum
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from agent_log_verifier.models.events import NormalizedEvent
+
+
+class Severity(StrEnum):
+    INFO = "info"  # 遵守・正常（レポートのサマリー行のみに使う）
+    WARNING = "warning"  # 逸脱疑い（3値のうち「逸脱疑い」に対応）
+    CRITICAL = "critical"  # 逸脱確定に近い強い疑い（v0.1では未使用）
+
+
+class Finding(BaseModel):
+    """検出器が出力する1件の所見。全検出器で共通のフォーマット。"""
+
+    model_config = ConfigDict(extra="allow")
+
+    rule_id: str  # 例: "COMPLIANCE-001", "LIVENESS-001"
+    severity: Severity
+    message: str  # 人間可読な説明（日本語）
+    evidence_event_uuids: list[str] = Field(default_factory=list)
+    judgement: str | None = None  # "遵守"/"逸脱疑い"/"判定不能"
+
+
+class Detector(ABC):
+    """全検出器（ComplianceDetector / LoopDetector / LivenessDetector）が
+    実装する共通インターフェース。企画書4-1章「検出器プラグイン層」に対応。
+    """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """検出器の識別名（例: "compliance", "liveness"）。
+        CLI の --detector オプションに対応。
+        """
+        ...
+
+    @abstractmethod
+    def run(self, events: list[NormalizedEvent], *, order_prompt: str | None = None) -> list[Finding]:
+        """イベント列を受け取り、Finding のリストを返す。
+        order_prompt: 発注文全文（指示遵守検証で使用。他の検出器は None のまま無視してよい）。
+        副作用（ファイル書き込み等）を持たない純粋関数的な実装にする（テスト容易性のため）。
+        """
+        ...
+
+
+class DetectorRegistry:
+    """検出器の登録・実行フローを一元管理する。
+    cli.py はこのレジストリ経由で検出器を呼び出し、個別 import を持たない。
+    """
+
+    def __init__(self) -> None:
+        self._detectors: dict[str, Detector] = {}
+
+    def register(self, detector: Detector) -> None:
+        self._detectors[detector.name] = detector
+
+    def run_all(
+        self, events: list[NormalizedEvent], *, order_prompt: str | None = None
+    ) -> dict[str, list[Finding]]:
+        """登録済み全検出器を実行し、検出器名をキーにした結果辞書を返す。"""
+        return {name: d.run(events, order_prompt=order_prompt) for name, d in self._detectors.items()}