@tt-a1i/mco 0.1.2 → 0.2.0

package/README.md

@@ -1,190 +1,173 @@
-# MCO Docs Index
+# MCO
 
-## Read First
-1. [multi-cli-orchestrator-proposal.md](./multi-cli-orchestrator-proposal.md)
-2. [capability-research.md](./capability-research.md)
-3. [notes.md](./notes.md)
+**MCO — One Prompt. Five AI Agents. One Result.**
 
-## Gate Artifacts
-1. [capability-probe-spec.md](./capability-probe-spec.md)
-2. [adapter-contract-tests.md](./adapter-contract-tests.md)
-3. [dry-run-plan.md](./dry-run-plan.md)
-4. [implementation-gate-checklist.md](./implementation-gate-checklist.md)
+English | [简体中文](./README.zh-CN.md)
 
-## Implementation Freeze
-1. [docs/implementation/step0-interface-freeze.md](./docs/implementation/step0-interface-freeze.md)
-2. [docs/contracts/cli-json-v0.1.x.md](./docs/contracts/cli-json-v0.1.x.md)
-3. [docs/contracts/provider-permissions-v0.1.x.md](./docs/contracts/provider-permissions-v0.1.x.md)
+## What is MCO
 
-## Planning and Tracking
-1. [task_plan.md](./task_plan.md)
+MCO (Multi-CLI Orchestrator) is a neutral orchestration layer that dispatches a single prompt to multiple AI coding agents in parallel and aggregates their results. No vendor lock-in. No workflow rewrite. Just fan-out, wait-all, and collect.
 
-## Release Notes
-1. [docs/releases/v0.1.2.md](./docs/releases/v0.1.2.md)
-2. [docs/releases/v0.1.2.zh-CN.md](./docs/releases/v0.1.2.zh-CN.md)
-3. [docs/releases/v0.1.1.md](./docs/releases/v0.1.1.md)
-4. [docs/releases/v0.1.1.zh-CN.md](./docs/releases/v0.1.1.zh-CN.md)
-5. [docs/releases/v0.1.0.md](./docs/releases/v0.1.0.md)
-6. [docs/releases/v0.1.0.zh-CN.md](./docs/releases/v0.1.0.zh-CN.md)
+You keep using Claude Code, Codex CLI, Gemini CLI, OpenCode, and Qwen Code as they are. MCO wires them into a unified execution pipeline with structured output, progress-driven timeouts, and reproducible artifacts.
 
-## Unified CLI (Step 2)
-`mco review` is the unified entrypoint for running a review task.
+## Key Highlights
 
-`mco run` is the generalized execution entrypoint for agent-style task orchestration (no forced findings schema).
+- **Parallel fan-out** — dispatch to all providers simultaneously, wait-all semantics
+- **Progress-driven timeouts** — agents run freely until completion; cancel only when output goes idle
+- **Dual mode** — `mco review` for structured code review findings, `mco run` for general task execution
+- **Provider-neutral** — uniform adapter contract across 5 CLI tools, no favoring any vendor
+- **Machine-readable output** — JSON result payloads and per-provider artifact trees for downstream automation
 
-## Installation
+## Supported Providers
 
-Python package (recommended):
+| Provider | CLI | Status |
+|----------|-----|--------|
+| Claude Code | `claude` | Supported |
+| Codex CLI | `codex` | Supported |
+| Gemini CLI | `gemini` | Supported |
+| OpenCode | `opencode` | Supported |
+| Qwen Code | `qwen` | Supported |
+
+No project migration. No command relearning. No single-tool lock-in.
+
+## Quick Start
+
+Install via npm (Python 3 required on PATH):
 
 ```bash
-pipx install mco
-mco --help
+npm i -g @tt-a1i/mco
 ```
 
-Install from source (editable):
+Or install from source:
 
 ```bash
 git clone https://github.com/tt-a1i/mco.git
 cd mco
 python3 -m pip install -e .
-mco --help
 ```
 
-NPM wrapper (Python 3 required on PATH):
-
-```bash
-npm i -g @tt-a1i/mco
-mco --help
-```
+Run your first multi-agent review:
 
-Quick start:
 ```bash
-./mco review \
+mco review \
   --repo . \
   --prompt "Review this repository for high-risk bugs and security issues." \
-  --providers claude,codex
+  --providers claude,codex,qwen
 ```
 
-Machine-readable output:
-```bash
-./mco review --repo . --prompt "Review for bugs." --providers claude,codex --json
-```
+## Usage
+
+### Review Mode
+
+Structured code review with findings schema. Each provider returns normalized findings with severity, category, evidence, and recommendations.
 
-Stdout-only result mode (for caller rendering, no `summary.md/decision.md/findings.json/run.json` write):
 ```bash
-./mco review --repo . --prompt "Review for bugs." --providers claude,codex --result-mode stdout --json
+mco review \
+  --repo . \
+  --prompt "Review for security vulnerabilities and performance issues." \
+  --providers claude,codex,gemini,opencode,qwen \
+  --json
 ```
 
-General run mode:
+### Run Mode
+
+General-purpose multi-agent execution. No forced output schema — providers complete the task freely.
+
 ```bash
-./mco run --repo . --prompt "Summarize the current repo architecture." --providers claude,codex --json
+mco run \
+  --repo . \
+  --prompt "Summarize the architecture of this project." \
+  --providers claude,codex \
+  --json
 ```
 
-Config file (JSON):
-```json
-{
-  "providers": ["claude", "codex"],
-  "artifact_base": "reports/review",
-  "state_file": ".mco/state.json",
-  "policy": {
-    "timeout_seconds": 180,
-    "stall_timeout_seconds": 900,
-    "poll_interval_seconds": 1.0,
-    "review_hard_timeout_seconds": 1800,
-    "enforce_findings_contract": false,
-    "max_retries": 1,
-    "high_escalation_threshold": 1,
-    "require_non_empty_findings": true,
-    "max_provider_parallelism": 0,
-    "allow_paths": [".", "runtime", "scripts"],
-    "enforcement_mode": "strict",
-    "provider_permissions": {
-      "claude": {
-        "permission_mode": "plan"
-      },
-      "codex": {
-        "sandbox": "workspace-write"
-      }
-    },
-    "provider_timeouts": {
-      "claude": 300,
-      "codex": 240,
-      "qwen": 240
-    }
-  }
-}
-```
+### Result Modes
+
+| Mode | Behavior |
+|------|----------|
+| `--result-mode artifact` | Write artifact files, print summary (default) |
+| `--result-mode stdout` | Print full result to stdout, skip artifact files |
+| `--result-mode both` | Write artifacts and print full result |
+
+### Path Constraints
+
+Restrict which files agents can access:
 
-Run with config:
 ```bash
-./mco review --config ./mco.example.json --repo . --prompt "Review for bugs and security issues."
+mco run \
+  --repo . \
+  --prompt "Analyze the adapter layer." \
+  --providers claude,codex \
+  --allow-paths runtime,scripts \
+  --target-paths runtime/adapters \
+  --enforcement-mode strict
 ```
 
-Override fan-out and per-provider timeout from CLI:
+## Defaults and Overrides
+
+MCO is zero-config by default. You can run it directly with built-in defaults and override behavior with CLI flags only.
+
+### Key Runtime Flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--providers` | `claude,codex` | Comma-separated provider list |
+| `--stall-timeout` | `900` | Cancel when no output progress for this duration |
+| `--review-hard-timeout` | `1800` | Hard deadline for review mode (`0` = disabled) |
+| `--max-provider-parallelism` | `0` | `0` = full parallelism across selected providers |
+| `--enforcement-mode` | `strict` | `strict` fails closed on unmet permissions |
+| `--provider-timeouts` | unset | Per-provider stall-timeout overrides (`provider=seconds`) |
+| `--provider-permissions-json` | unset | Provider permission mapping JSON |
+
+Example:
+
 ```bash
-./mco review \
+mco review \
   --repo . \
-  --prompt "Review for bugs and security issues." \
-  --providers claude,codex,gemini,opencode,qwen \
-  --strict-contract \
-  --max-provider-parallelism 2 \
+  --prompt "Review for bugs." \
+  --providers claude,codex,qwen \
   --stall-timeout 900 \
   --review-hard-timeout 1800 \
+  --max-provider-parallelism 0 \
   --provider-timeouts qwen=900,codex=900
 ```
 
-Run mode with hard path constraints:
-```bash
-./mco run \
-  --repo . \
-  --prompt "Compare adapter behaviors and return a short markdown summary." \
-  --providers claude,codex \
-  --allow-paths runtime,scripts \
-  --target-paths runtime/adapters,runtime/review_engine.py \
-  --enforcement-mode strict \
-  --provider-permissions-json '{"codex":{"sandbox":"workspace-write"},"claude":{"permission_mode":"plan"}}' \
-  --json
+Run `mco review --help` for the full flag list.
+
+## How It Works
+
+```
+prompt ─> MCO ─┬─> Claude Code  ─┐
+               ├─> Codex CLI     ├─> aggregate ─> artifacts + JSON
+               ├─> Gemini CLI    │
+               ├─> OpenCode      │
+               └─> Qwen Code   ──┘
 ```
 
-Artifacts are written to:
-- `<artifact_base>/<task_id>/summary.md`
-- `<artifact_base>/<task_id>/decision.md`
-- `<artifact_base>/<task_id>/findings.json`
-- `<artifact_base>/<task_id>/run.json`
-- `<artifact_base>/<task_id>/providers/*.json`
-- `<artifact_base>/<task_id>/raw/*.log`
-
-`run.json` includes audit fields for reproducibility:
-- `effective_cwd`
-- `allow_paths_hash`
-- `permissions_hash`
-
-Notes:
-- YAML config requires `pyyaml` installed; otherwise use JSON config.
-- Review prompt is wrapped with a JSON finding contract, but strict parse enforcement is optional.
-- Enable strict gate behavior with `--strict-contract` (or `policy.enforce_findings_contract=true` in config).
-- `run` mode does not force findings schema; it focuses on execution aggregation and provider success.
-- `result_mode=artifact` (default): write user-facing artifacts and print compact result.
-- `result_mode=stdout`: print provider-level result payload to stdout, skip user-facing artifact files.
-- `result_mode=both`: write artifacts and print provider-level payload.
-- Execution model is `wait-all`: one provider timeout/failure does not stop others.
-- Timeout behavior is progress-driven:
-  - `stall_timeout_seconds`: cancel only when output progress is idle beyond threshold.
-  - `review_hard_timeout_seconds`: hard deadline applied only in `review` mode.
-- `max_provider_parallelism=0` (or omitted) means full parallelism across selected providers.
-- `provider_timeouts` are provider-specific stall-timeout overrides.
-- `allow_paths` and `target_paths` are validated against `repo_root`; path escape is rejected.
-- `enforcement_mode=strict` (default) fails closed when provider permission requirements cannot be honored.
-
-## Step5 Benchmark Script
-Use this script to generate serial vs full-parallel evidence and write reports under `reports/adapter-contract/<date>/`:
+Each provider runs as an independent subprocess through a uniform adapter contract:
 
-```bash
-./scripts/run_step5_parallel_benchmark.sh
+1. **Detect** — check binary presence and auth status
+2. **Run** — spawn CLI process with prompt, capture stdout/stderr
+3. **Poll** — monitor process + output byte growth for progress detection
+4. **Cancel** — SIGTERM/SIGKILL on stall timeout or hard deadline
+5. **Normalize** — extract structured findings from raw output
+
+Execution model is **wait-all**: one provider's timeout or failure never stops others.
+
+## Artifacts
+
+Each run produces a structured artifact tree:
+
+```
+reports/review/<task_id>/
+  summary.md          # Human-readable summary
+  decision.md         # PASS / FAIL / ESCALATE / PARTIAL
+  findings.json       # Aggregated normalized findings (review mode)
+  run.json            # Machine-readable execution metadata
+  providers/          # Per-provider result JSON
+  raw/                # Raw stdout/stderr logs
 ```
 
-The generated summary JSON includes separated parse-vs-findings metrics:
-- `providers_total`
-- `parse_success_rate`
-- `effective_findings_count`
-- `zero_finding_provider_count`
+## License
+
+UNLICENSED

package/README.zh-CN.md

@@ -0,0 +1,173 @@
+# MCO
+
+**MCO — 一条提示词，五个 AI Agent，一份结果。**
+
+[English](./README.md) | 简体中文
+
+## MCO 是什么
+
+MCO（Multi-CLI Orchestrator）是一个中立的编排层，将单条提示词并行分发给多个 AI 编程 Agent，汇总执行结果。不绑定任何厂商，不改变你的工作流。Fan-out、Wait-all、Collect。
+
+你继续照常使用 Claude Code、Codex CLI、Gemini CLI、OpenCode、Qwen Code。MCO 负责把它们串联成统一的执行管线，提供结构化输出、进度驱动超时、可复现的产物。
+
+## 核心特性
+
+- **并行扇出** — 同时分发到所有 provider，wait-all 语义
+- **进度驱动超时** — agent 自由跑完，仅在长时间无输出时取消
+- **双模式** — `mco review` 结构化代码审查，`mco run` 通用任务执行
+- **厂商中立** — 5 个 CLI 工具统一适配器契约，不偏向任何厂商
+- **机器可读输出** — JSON 结果 + 每个 provider 独立产物树，便于下游自动化
+
+## 支持的 Provider
+
+| Provider | CLI | 状态 |
+|----------|-----|------|
+| Claude Code | `claude` | 已支持 |
+| Codex CLI | `codex` | 已支持 |
+| Gemini CLI | `gemini` | 已支持 |
+| OpenCode | `opencode` | 已支持 |
+| Qwen Code | `qwen` | 已支持 |
+
+无需迁移项目，无需重学命令，无需绑定单一工具。
+
+## 快速开始
+
+通过 npm 安装（需要系统有 Python 3）：
+
+```bash
+npm i -g @tt-a1i/mco
+```
+
+或从源码安装：
+
+```bash
+git clone https://github.com/tt-a1i/mco.git
+cd mco
+python3 -m pip install -e .
+```
+
+运行第一次多 Agent 审查：
+
+```bash
+mco review \
+  --repo . \
+  --prompt "Review this repository for high-risk bugs and security issues." \
+  --providers claude,codex,qwen
+```
+
+## 使用方式
+
+### Review 模式
+
+结构化代码审查，输出标准化的 findings（含严重级别、分类、证据、建议）。
+
+```bash
+mco review \
+  --repo . \
+  --prompt "Review for security vulnerabilities and performance issues." \
+  --providers claude,codex,gemini,opencode,qwen \
+  --json
+```
+
+### Run 模式
+
+通用多 Agent 任务执行，不强制输出格式，provider 自由完成任务。
+
+```bash
+mco run \
+  --repo . \
+  --prompt "Summarize the architecture of this project." \
+  --providers claude,codex \
+  --json
+```
+
+### 结果模式
+
+| 模式 | 行为 |
+|------|------|
+| `--result-mode artifact` | 写产物文件，输出摘要（默认） |
+| `--result-mode stdout` | 完整结果输出到 stdout，不写产物文件 |
+| `--result-mode both` | 既写产物又输出完整结果 |
+
+### 路径约束
+
+限制 agent 可访问的文件范围：
+
+```bash
+mco run \
+  --repo . \
+  --prompt "Analyze the adapter layer." \
+  --providers claude,codex \
+  --allow-paths runtime,scripts \
+  --target-paths runtime/adapters \
+  --enforcement-mode strict
+```
+
+## 默认值与参数覆盖
+
+MCO 默认零配置可用。直接运行即可，按需通过命令行参数覆盖行为。
+
+### 关键运行参数
+
+| 参数 | 默认值 | 说明 |
+|------|--------|------|
+| `--providers` | `claude,codex` | 逗号分隔 provider 列表 |
+| `--stall-timeout` | `900` | 无输出进展超过此时间才取消 |
+| `--review-hard-timeout` | `1800` | review 模式硬截止（`0` = 禁用） |
+| `--max-provider-parallelism` | `0` | `0` = 选中 provider 全并行 |
+| `--enforcement-mode` | `strict` | 权限不满足时 fail-closed |
+| `--provider-timeouts` | 未设置 | provider 级 stall timeout 覆盖（`provider=seconds`） |
+| `--provider-permissions-json` | 未设置 | provider 权限映射 JSON |
+
+示例：
+
+```bash
+mco review \
+  --repo . \
+  --prompt "Review for bugs." \
+  --providers claude,codex,qwen \
+  --stall-timeout 900 \
+  --review-hard-timeout 1800 \
+  --max-provider-parallelism 0 \
+  --provider-timeouts qwen=900,codex=900
+```
+
+运行 `mco review --help` 查看完整参数列表。
+
+## 工作原理
+
+```
+prompt ─> MCO ─┬─> Claude Code  ─┐
+               ├─> Codex CLI     ├─> 聚合 ─> 产物 + JSON
+               ├─> Gemini CLI    │
+               ├─> OpenCode      │
+               └─> Qwen Code   ──┘
+```
+
+每个 provider 通过统一的适配器契约作为独立子进程运行：
+
+1. **Detect** — 检测二进制文件和认证状态
+2. **Run** — 启动 CLI 进程，传入提示词，捕获 stdout/stderr
+3. **Poll** — 监控进程状态 + 输出字节增长，判断活跃度
+4. **Cancel** — stall timeout 或硬截止时 SIGTERM/SIGKILL
+5. **Normalize** — 从原始输出中提取结构化 findings
+
+执行模型是 **wait-all**：单个 provider 超时或失败不会中断其他 provider。
+
+## 产物结构
+
+每次执行生成结构化产物树：
+
+```
+reports/review/<task_id>/
+  summary.md          # 人类可读摘要
+  decision.md         # PASS / FAIL / ESCALATE / PARTIAL
+  findings.json       # 聚合后的标准化 findings（review 模式）
+  run.json            # 机器可读执行元数据
+  providers/          # 各 provider 结果 JSON
+  raw/                # 原始 stdout/stderr 日志
+```
+
+## 许可证
+
+UNLICENSED

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tt-a1i/mco",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Node wrapper for the mco CLI (Python runtime required).",
   "license": "UNLICENSED",
   "bin": {

package/runtime/adapters/shim.py

@@ -40,6 +40,19 @@ class ShimRunHandle:
     stderr_file: TextIO
 
 
+_ENV_VARS_TO_STRIP = (
+    "CLAUDECODE",
+)
+
+
+def _sanitize_env() -> Dict[str, str]:
+    """Return a copy of os.environ with known conflicting variables removed."""
+    env = os.environ.copy()
+    for key in _ENV_VARS_TO_STRIP:
+        env.pop(key, None)
+    return env
+
+
 class ShimAdapterBase:
     id: ProviderId
 
@@ -104,6 +117,7 @@ class ShimAdapterBase:
             stderr=stderr_file,
             text=True,
             start_new_session=True,
+            env=_sanitize_env(),
         )
         self._runs[run_id] = ShimRunHandle(
             process=process,
@@ -123,6 +137,17 @@ class ShimAdapterBase:
             session_id=None,
         )
 
+    @staticmethod
+    def _close_io(handle: ShimRunHandle) -> None:
+        try:
+            handle.stdout_file.close()
+        except Exception:
+            pass
+        try:
+            handle.stderr_file.close()
+        except Exception:
+            pass
+
     def poll(self, ref: TaskRunRef) -> TaskStatus:
         handle = self._runs.get(ref.run_id)
         if handle is None:
@@ -154,11 +179,7 @@ class ShimAdapterBase:
                 message="running",
             )
 
-        try:
-            handle.stdout_file.close()
-            handle.stderr_file.close()
-        except Exception:
-            pass
+        self._close_io(handle)
 
         stdout_text = handle.stdout_path.read_text(encoding="utf-8") if handle.stdout_path.exists() else ""
         stderr_text = handle.stderr_path.read_text(encoding="utf-8") if handle.stderr_path.exists() else ""
@@ -182,6 +203,7 @@ class ShimAdapterBase:
             "stderr_path": str(handle.stderr_path),
         }
         handle.provider_result_path.write_text(json.dumps(payload, ensure_ascii=True, indent=2), encoding="utf-8")
+        self._runs.pop(ref.run_id, None)
 
         return TaskStatus(
             task_id=ref.task_id,
@@ -201,17 +223,27 @@ class ShimAdapterBase:
         if handle is None:
             return
         if handle.process.poll() is not None:
+            self._close_io(handle)
+            self._runs.pop(ref.run_id, None)
             return
         try:
             os.killpg(os.getpgid(handle.process.pid), signal.SIGTERM)
         except ProcessLookupError:
+            self._close_io(handle)
+            self._runs.pop(ref.run_id, None)
             return
         time.sleep(0.2)
         if handle.process.poll() is None:
             try:
                 os.killpg(os.getpgid(handle.process.pid), signal.SIGKILL)
             except ProcessLookupError:
+                self._close_io(handle)
+                self._runs.pop(ref.run_id, None)
                 return
+            time.sleep(0.1)
+        if handle.process.poll() is not None:
+            self._close_io(handle)
+            self._runs.pop(ref.run_id, None)
 
     def normalize(self, raw: object, ctx: NormalizeContext) -> List[NormalizedFinding]:
         raise NotImplementedError

package/runtime/cli.py

@@ -6,7 +6,7 @@ import sys
 from pathlib import Path
 from typing import Dict, List
 
-from .config import ReviewConfig, ReviewPolicy, load_review_config
+from .config import ReviewConfig, ReviewPolicy
 from .review_engine import ReviewRequest, run_review
 
 
@@ -75,18 +75,20 @@ def _parse_provider_timeouts(raw: str) -> Dict[str, int]:
         return result
     for chunk in raw.split(","):
         pair = chunk.strip()
-        if not pair or "=" not in pair:
+        if not pair:
             continue
+        if "=" not in pair:
+            raise ValueError(f"invalid provider timeout entry: {pair}")
         provider, timeout_text = pair.split("=", 1)
         provider_name = provider.strip()
         if not provider_name:
-            continue
+            raise ValueError(f"invalid provider timeout entry: {pair}")
         try:
             timeout = int(timeout_text.strip())
         except Exception:
-            continue
+            raise ValueError(f"invalid timeout value for provider '{provider_name}': {timeout_text.strip()}") from None
         if timeout <= 0:
-            continue
+            raise ValueError(f"timeout must be > 0 for provider '{provider_name}'")
         result[provider_name] = timeout
     return result
 
@@ -102,23 +104,24 @@ def _parse_provider_permissions_json(raw: str) -> Dict[str, Dict[str, str]]:
     try:
         payload = json.loads(raw)
     except Exception:
-        return {}
+        raise ValueError("--provider-permissions-json must be valid JSON") from None
     if not isinstance(payload, dict):
-        return {}
+        raise ValueError("--provider-permissions-json root must be an object")
 
     result: Dict[str, Dict[str, str]] = {}
     for provider, permissions in payload.items():
         provider_name = str(provider).strip()
-        if not provider_name or not isinstance(permissions, dict):
-            continue
+        if not provider_name:
+            raise ValueError("--provider-permissions-json contains empty provider name")
+        if not isinstance(permissions, dict):
+            raise ValueError(f"permissions for provider '{provider_name}' must be an object")
         normalized: Dict[str, str] = {}
         for key, value in permissions.items():
             key_name = str(key).strip()
             if not key_name:
-                continue
+                raise ValueError(f"provider '{provider_name}' contains empty permission key")
             normalized[key_name] = str(value)
-        if normalized:
-            result[provider_name] = normalized
+        result[provider_name] = normalized
     return result
 
 
@@ -138,7 +141,6 @@ def _add_common_execution_args(parser: argparse.ArgumentParser) -> None:
     parser.add_argument("--repo", default=".", help="Repository root path")
     parser.add_argument("--prompt", required=True, help="Task prompt")
     parser.add_argument("--providers", default="", help="Comma-separated providers, e.g. claude,codex")
-    parser.add_argument("--config", default="", help="Config file path (.json or .yaml/.yml)")
     parser.add_argument("--artifact-base", default="", help="Artifact base directory override")
     parser.add_argument("--state-file", default="", help="Runtime state file override")
     parser.add_argument("--task-id", default="", help="Optional stable task id")
@@ -212,7 +214,7 @@ def build_parser() -> argparse.ArgumentParser:
 
 
 def _resolve_config(args: argparse.Namespace) -> ReviewConfig:
-    cfg = load_review_config(args.config or None)
+    cfg = ReviewConfig()
     providers = _parse_providers(args.providers) if args.providers else cfg.providers
     artifact_base = args.artifact_base or cfg.artifact_base
     state_file = args.state_file or cfg.state_file
@@ -236,7 +238,7 @@ def _resolve_config(args: argparse.Namespace) -> ReviewConfig:
     review_hard_timeout_seconds = cfg.policy.review_hard_timeout_seconds
     if args.review_hard_timeout is not None and args.review_hard_timeout >= 0:
         review_hard_timeout_seconds = args.review_hard_timeout
-    enforce_findings_contract = cfg.policy.enforce_findings_contract or bool(args.strict_contract)
+    enforce_findings_contract = bool(args.strict_contract)
 
     policy = ReviewPolicy(
         timeout_seconds=cfg.policy.timeout_seconds,
@@ -263,7 +265,11 @@ def main(argv: List[str] | None = None) -> int:
         parser.error("unsupported command")
         return 2
 
-    cfg = _resolve_config(args)
+    try:
+        cfg = _resolve_config(args)
+    except ValueError as exc:
+        print(f"Configuration error: {exc}", file=sys.stderr)
+        return 2
     repo_root = str(Path(args.repo).resolve())
     providers = [item for item in cfg.providers if item in ("claude", "codex", "gemini", "opencode", "qwen")]
     if not providers:
@@ -283,7 +289,11 @@ def main(argv: List[str] | None = None) -> int:
     )
     review_mode = args.command == "review"
     write_artifacts = args.result_mode in ("artifact", "both")
-    result = run_review(req, review_mode=review_mode, write_artifacts=write_artifacts)
+    try:
+        result = run_review(req, review_mode=review_mode, write_artifacts=write_artifacts)
+    except ValueError as exc:
+        print(f"Input error: {exc}", file=sys.stderr)
+        return 2
 
     payload = {
         "command": args.command,

package/runtime/config.py

@@ -1,9 +1,7 @@
 from __future__ import annotations
 
-import json
 from dataclasses import dataclass, field
-from pathlib import Path
-from typing import Any, Dict, List, Optional
+from typing import Dict, List
 
 DEFAULT_PROVIDER_TIMEOUTS: Dict[str, int] = {
 }
@@ -32,158 +30,3 @@ class ReviewConfig:
     artifact_base: str = "reports/review"
     state_file: str = ".mco/state.json"
     policy: ReviewPolicy = field(default_factory=ReviewPolicy)
-
-
-def _as_bool(value: Any, default: bool) -> bool:
-    if isinstance(value, bool):
-        return value
-    if isinstance(value, str):
-        lowered = value.strip().lower()
-        if lowered in ("true", "1", "yes", "y", "on"):
-            return True
-        if lowered in ("false", "0", "no", "n", "off"):
-            return False
-    return default
-
-
-def _to_policy(payload: Dict[str, Any]) -> ReviewPolicy:
-    raw_provider_timeouts = payload.get("provider_timeouts", {})
-    provider_timeouts: Dict[str, int] = dict(DEFAULT_PROVIDER_TIMEOUTS)
-    if isinstance(raw_provider_timeouts, dict):
-        for key, value in raw_provider_timeouts.items():
-            provider = str(key).strip()
-            if not provider:
-                continue
-            try:
-                timeout = int(value)
-            except Exception:
-                continue
-            if timeout <= 0:
-                continue
-            provider_timeouts[provider] = timeout
-
-    try:
-        max_parallel = int(payload.get("max_provider_parallelism", 0))
-    except Exception:
-        max_parallel = 0
-    if max_parallel < 0:
-        max_parallel = 0
-
-    raw_allow_paths = payload.get("allow_paths", ["."])
-    allow_paths: List[str]
-    if isinstance(raw_allow_paths, str):
-        allow_paths = [item.strip() for item in raw_allow_paths.split(",") if item.strip()]
-    elif isinstance(raw_allow_paths, list):
-        allow_paths = [str(item).strip() for item in raw_allow_paths if str(item).strip()]
-    else:
-        allow_paths = ["."]
-    if not allow_paths:
-        allow_paths = ["."]
-
-    raw_provider_permissions = payload.get("provider_permissions", {})
-    provider_permissions: Dict[str, Dict[str, str]] = {}
-    if isinstance(raw_provider_permissions, dict):
-        for provider, permissions in raw_provider_permissions.items():
-            provider_name = str(provider).strip()
-            if not provider_name or not isinstance(permissions, dict):
-                continue
-            normalized: Dict[str, str] = {}
-            for key, value in permissions.items():
-                key_name = str(key).strip()
-                if not key_name:
-                    continue
-                normalized[key_name] = str(value)
-            if normalized:
-                provider_permissions[provider_name] = normalized
-
-    enforcement_mode = str(payload.get("enforcement_mode", "strict")).strip().lower()
-    if enforcement_mode not in ("strict", "best_effort"):
-        enforcement_mode = "strict"
-
-    try:
-        stall_timeout_seconds = int(payload.get("stall_timeout_seconds", 900))
-    except Exception:
-        stall_timeout_seconds = 900
-    if stall_timeout_seconds <= 0:
-        stall_timeout_seconds = 900
-
-    try:
-        poll_interval_seconds = float(payload.get("poll_interval_seconds", 1.0))
-    except Exception:
-        poll_interval_seconds = 1.0
-    if poll_interval_seconds <= 0:
-        poll_interval_seconds = 1.0
-
-    try:
-        review_hard_timeout_seconds = int(payload.get("review_hard_timeout_seconds", 1800))
-    except Exception:
-        review_hard_timeout_seconds = 1800
-    if review_hard_timeout_seconds < 0:
-        review_hard_timeout_seconds = 1800
-
-    return ReviewPolicy(
-        timeout_seconds=int(payload.get("timeout_seconds", 180)),
-        stall_timeout_seconds=stall_timeout_seconds,
-        poll_interval_seconds=poll_interval_seconds,
-        review_hard_timeout_seconds=review_hard_timeout_seconds,
-        enforce_findings_contract=_as_bool(payload.get("enforce_findings_contract", False), False),
-        max_retries=int(payload.get("max_retries", 1)),
-        high_escalation_threshold=int(payload.get("high_escalation_threshold", 1)),
-        require_non_empty_findings=_as_bool(payload.get("require_non_empty_findings", True), True),
-        max_provider_parallelism=max_parallel,
-        provider_timeouts=provider_timeouts,
-        allow_paths=allow_paths,
-        provider_permissions=provider_permissions,
-        enforcement_mode=enforcement_mode,
-    )
-
-
-def _normalize_payload(payload: Dict[str, Any]) -> ReviewConfig:
-    policy_payload = payload.get("policy", {})
-    if not isinstance(policy_payload, dict):
-        policy_payload = {}
-    providers = payload.get("providers", ["claude", "codex"])
-    if isinstance(providers, str):
-        providers = [item.strip() for item in providers.split(",") if item.strip()]
-    if not isinstance(providers, list):
-        providers = ["claude", "codex"]
-    providers = [str(item).strip() for item in providers if str(item).strip()]
-    if not providers:
-        providers = ["claude", "codex"]
-
-    return ReviewConfig(
-        providers=providers,
-        artifact_base=str(payload.get("artifact_base", "reports/review")),
-        state_file=str(payload.get("state_file", ".mco/state.json")),
-        policy=_to_policy(policy_payload),
-    )
-
-
-def load_review_config(config_path: Optional[str]) -> ReviewConfig:
-    if not config_path:
-        return ReviewConfig()
-    path = Path(config_path)
-    if not path.exists():
-        raise FileNotFoundError(f"config file not found: {config_path}")
-
-    suffix = path.suffix.lower()
-    raw_text = path.read_text(encoding="utf-8")
-    if suffix == ".json":
-        payload = json.loads(raw_text)
-        if not isinstance(payload, dict):
-            raise ValueError("config root must be an object")
-        return _normalize_payload(payload)
-
-    if suffix in (".yaml", ".yml"):
-        try:
-            import yaml  # type: ignore
-        except Exception as exc:
-            raise RuntimeError(
-                "YAML config requires pyyaml. Install with: pip install pyyaml, or use a .json config."
-            ) from exc
-        payload = yaml.safe_load(raw_text)
-        if not isinstance(payload, dict):
-            raise ValueError("config root must be a map")
-        return _normalize_payload(payload)
-
-    raise ValueError(f"unsupported config format: {config_path}")

package/runtime/orchestrator.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import json
 import threading
+import time
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Callable, Dict, List, Optional, Set, Tuple
@@ -50,8 +51,14 @@ class TaskStateMachine:
 
 
 class OrchestratorRuntime:
-    def __init__(self, retry_policy: Optional[RetryPolicy] = None, state_file: Optional[str] = None) -> None:
+    def __init__(
+        self,
+        retry_policy: Optional[RetryPolicy] = None,
+        state_file: Optional[str] = None,
+        sleep_fn: Optional[Callable[[float], None]] = None,
+    ) -> None:
         self.retry_policy = retry_policy or RetryPolicy()
+        self.sleep_fn = sleep_fn or time.sleep
         self.dispatch_cache: Dict[str, RunResult] = {}
         self.idempotency_index: Dict[str, str] = {}
         self.sent_notifications: Set[Tuple[str, str, str]] = set()
@@ -205,7 +212,9 @@ class OrchestratorRuntime:
                 return final
 
             retry_index = attempts
-            delays.append(self.retry_policy.compute_delay(retry_index))
+            delay_seconds = self.retry_policy.compute_delay(retry_index)
+            delays.append(delay_seconds)
+            self.sleep_fn(delay_seconds)
 
     def send_terminal_notification(self, task_id: str, state: TaskState, channel: str) -> bool:
         with self._lock:

package/runtime/schemas/review_findings.schema.json

@@ -53,8 +53,6 @@
             "additionalProperties": true,
             "required": [
               "file",
-              "line",
-              "symbol",
               "snippet"
             ],
             "properties": {