examples: route every input mode through the resolved sandbox runtime

The container runtime silently downgraded file-list and worktree inputs
to the in-process path: only --diff-file and --fixture were wired to
run_review_container, while --files and --repo-path called the sync
run_review with runtime="container", which had no container branch and
fell through to in-process. Extract the input materialization into a
shared _resolve_input helper used by both entry points, extend
run_review_container to accept all three input modes, and route every
container request through it in the CLI. Sync run_review now rejects the
container runtime loudly instead of falling back. Also correct two stale
docstring and README references to a fixture that no longer exists.

Updates #92

RELEASE NOTES: NONE

Author: Acture

examples/skills_code_review_agent/README.zh_CN.md

@@ -9,17 +9,25 @@
 ```bash
 pip install -r requirements.txt
 
-# 评审内置样本（dry-run，确定性，无需模型）：
-python run_review.py --fixture 0001_insecure.diff --out-dir /tmp/cr
+# 评审内置样本（无需模型）。默认运行时是沙箱
+# （auto → 有 Docker 走容器，否则本地子进程沙箱）：
+python run_review.py --fixture security.diff --out-dir /tmp/cr
 
-# 评审你自己的 diff 或工作区：
+# 评审你自己的 diff、工作区，或指定文件列表：
 python run_review.py --diff-file my.diff
 python run_review.py --repo-path /path/to/repo --no-db
+python run_review.py --files pipeline/engine.py,pipeline/scanners.py
 
 # 在带标注的样本上打分自测（检出率 / 误报率）：
 python selftest.py
+
+# 走 LlmAgent + fake 模型（无需 API key）：
+python run_agent.py --fixture security.diff --dry-run
 ```
 
+样本报告见 [`sample_output/`](./sample_output/)；规则清单见
+[`../../skills/code-review/docs/RULES.md`](../../skills/code-review/docs/RULES.md)，设计说明见 [DESIGN.md](./DESIGN.md)。
+
 ## 工作原理
 
 findings 来自**确定性静态扫描器**而非 LLM，因此结果可复现、验收阈值可调：

examples/skills_code_review_agent/pipeline/engine.py

@@ -99,20 +99,10 @@ def run_review(
     # fast-path that must be requested explicitly.
     if runtime == "auto":
         runtime = "local"
+    elif runtime == "container":
+        raise ValueError("container runtime is async — call run_review_container() instead of run_review()")
 
-    if diff_text is not None:
-        summary, scan_dir = _materialize(diff_text)
-        source_type, source_ref = "diff_file", "<diff>"
-    elif files is not None:
-        summary = diff_parser.parse_file_list(files, repo_root)
-        scan_dir = _materialize_files(files, repo_root)
-        source_type, source_ref = "file_list", ",".join(files)[:200]
-    elif repo_path is not None:
-        summary = diff_parser.parse_git_worktree(repo_path)
-        scan_dir = repo_path
-        source_type, source_ref = "repo_path", repo_path
-    else:
-        raise ValueError("run_review requires diff_text, files, or repo_path")
+    summary, scan_dir, source_type, source_ref = _resolve_input(diff_text, files, repo_path, repo_root)
 
     sandbox_runs: list = []
     if runtime == "local":
@@ -185,18 +175,42 @@ def _assemble(task_id, summary, raw, sandbox_runs, source_type, source_ref, star
                         monitoring=monitoring)
 
 
+def _resolve_input(diff_text: Optional[str], files: Optional[list[str]], repo_path: Optional[str],
+                   repo_root: str) -> tuple[DiffSummary, str, str, str]:
+    """Materialize any of the three input modes into (summary, scan_dir, source_type, source_ref).
+
+    Shared by run_review and run_review_container so every input mode reaches the same sandbox path.
+    """
+    if diff_text is not None:
+        summary, scan_dir = _materialize(diff_text)
+        return summary, scan_dir, "diff_file", "<diff>"
+    if files is not None:
+        return diff_parser.parse_file_list(files, repo_root), _materialize_files(files, repo_root), \
+            "file_list", ",".join(files)[:200]
+    if repo_path is not None:
+        return diff_parser.parse_git_worktree(repo_path), repo_path, "repo_path", repo_path
+    raise ValueError("a review requires diff_text, files, or repo_path")
+
+
 async def run_review_container(
     *,
     task_id: Optional[str] = None,
-    diff_text: str,
+    diff_text: Optional[str] = None,
+    files: Optional[list[str]] = None,
+    repo_path: Optional[str] = None,
+    repo_root: str = ".",
     sandbox_timeout: float | None = None,
     max_output_bytes: int | None = None,
 ) -> ReviewResult:
-    """Run a review with scanners inside a Container workspace (production isolation; needs Docker)."""
+    """Run a review with scanners inside a Container workspace (production isolation; needs Docker).
+
+    Accepts the same three input modes as run_review so file-list and worktree inputs also reach the
+    container sandbox instead of silently falling back to the in-process path.
+    """
     from . import sandbox as sandbox_mod
     task_id = task_id or f"cr-{uuid.uuid4().hex[:12]}"
     started = time.monotonic()
-    summary, scan_dir = _materialize(diff_text)
+    summary, scan_dir, source_type, source_ref = _resolve_input(diff_text, files, repo_path, repo_root)
     raw, run = await sandbox_mod.run_container(
         scan_dir,
         timeout=sandbox_timeout if sandbox_timeout is not None else sandbox_mod.DEFAULT_TIMEOUT_SEC,
@@ -205,7 +219,7 @@ async def run_review_container(
     if run.timed_out or run.exit_code not in (0, 1):
         exception_dist["sandbox_failure"] = 1
     raw = list(raw) + scanners.detect_missing_tests(summary)
-    return _assemble(task_id, summary, raw, [run], "diff_file", "<diff>", started, exception_dist, None, None)
+    return _assemble(task_id, summary, raw, [run], source_type, source_ref, started, exception_dist, None, None)
 
 
 def dedup_thresholds() -> tuple[float, float]:

examples/skills_code_review_agent/run_agent.py

@@ -10,7 +10,8 @@
 Dry-run by default: with no API key, FakeReviewModel drives one call to the review_code tool and
 summarizes the result — no LLM, no secrets. Set TRPC_AGENT_API_KEY to use a real model instead.
 
-    python run_agent.py --fixture 0001_insecure.diff
+    python run_agent.py --fixture security.diff
+    python run_agent.py --fixture security.diff --dry-run   # force fake model even with a key
 """
 from __future__ import annotations
 

examples/skills_code_review_agent/run_review.py

@@ -68,16 +68,17 @@ def _parse_args() -> argparse.Namespace:
 def _run(args: argparse.Namespace) -> ReviewResult:
     runtime = _resolve_runtime(args.runtime)
     if args.repo_path:
-        return run_review(repo_path=args.repo_path, runtime=runtime, sandbox_timeout=args.sandbox_timeout)
-    if args.files:
-        return run_review(files=[p.strip() for p in args.files.split(",") if p.strip()],
-                          runtime=runtime,
-                          sandbox_timeout=args.sandbox_timeout)
-    path = Path(args.diff_file) if args.diff_file else HERE / "fixtures" / "diffs" / args.fixture
-    diff_text = path.read_text(encoding="utf-8")
+        src = {"repo_path": args.repo_path}
+    elif args.files:
+        src = {"files": [p.strip() for p in args.files.split(",") if p.strip()]}
+    else:
+        path = Path(args.diff_file) if args.diff_file else HERE / "fixtures" / "diffs" / args.fixture
+        src = {"diff_text": path.read_text(encoding="utf-8")}
+    # Every input mode reaches the resolved runtime — container goes to the async container path so
+    # --files / --repo-path are not silently downgraded to in-process.
     if runtime == "container":
-        return asyncio.run(run_review_container(diff_text=diff_text, sandbox_timeout=args.sandbox_timeout))
-    return run_review(diff_text=diff_text, runtime=runtime, sandbox_timeout=args.sandbox_timeout)
+        return asyncio.run(run_review_container(sandbox_timeout=args.sandbox_timeout, **src))
+    return run_review(runtime=runtime, sandbox_timeout=args.sandbox_timeout, **src)
 
 
 async def _persist(result: ReviewResult, db_url: str) -> None:

tests/examples/test_skills_code_review_agent.py

@@ -439,3 +439,21 @@ async def test_status_reflects_blocked(tmp_path) -> None:
         assert got["task"].status == "blocked"  # not hardcoded "completed"
     finally:
         await store.close()
+
+
+def test_run_review_rejects_container_runtime() -> None:
+    # Sync run_review must reject container (async) loudly, not silently fall back to in-process.
+    with pytest.raises(ValueError, match="container"):
+        run_review(diff_text=(_FIXTURES / "security.diff").read_text(), runtime="container")
+
+
+def test_resolve_input_covers_all_modes(tmp_path) -> None:
+    # The shared resolver (used by run_review AND run_review_container) handles every input mode,
+    # so --files / --repo-path reach the container sandbox instead of downgrading to in-process.
+    from pipeline.engine import _resolve_input
+
+    (tmp_path / "m.py").write_text("import os\n")
+    _, _, st_diff, _ = _resolve_input((_FIXTURES / "security.diff").read_text(), None, None, ".")
+    _, _, st_files, ref = _resolve_input(None, ["m.py"], None, str(tmp_path))
+    assert st_diff == "diff_file"
+    assert st_files == "file_list" and "m.py" in ref