task-harbor 0.7.0__py3-none-any.whl

opus_manager/codex.py

@@ -0,0 +1,119 @@
+"""GPT coding agents through the authenticated Codex CLI JSONL interface."""
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from pathlib import Path
+from uuid import UUID
+
+from .agent import AgentError, AgentResult
+from .config import Config
+
+
+def executable_command(binary: str) -> list[str]:
+    resolved = shutil.which(binary) or binary
+    if Path(resolved).suffix.lower() in {".cmd", ".bat", ".ps1"}:
+        # npm's Windows wrapper needs a shell. Invoke its JS entry point directly
+        # so prompts and TOML values never pass through cmd.exe quoting.
+        entry = Path(resolved).parent / "node_modules" / "@openai" / "codex" / "bin" / "codex.js"
+        node = shutil.which("node")
+        if not node or not entry.is_file():
+            raise AgentError("Set codex_bin to a native Codex executable, or install Codex with npm and Node on PATH")
+        return [node, str(entry)]
+    return [resolved]
+
+
+def parse_events(stdout: str, returncode: int, stderr: str = "", resume_session: str | None = None) -> AgentResult:
+    session = resume_session
+    final_text = None
+    complete = False
+    failures = []
+    usage = {}
+    for line in stdout.splitlines():
+        if not line.strip():
+            continue
+        try:
+            event = json.loads(line)
+        except json.JSONDecodeError as exc:
+            raise AgentError("Codex returned malformed JSONL") from exc
+        if not isinstance(event, dict):
+            raise AgentError("Codex returned a non-object event")
+        kind = event.get("type")
+        if kind == "thread.started":
+            candidate = event.get("thread_id")
+            try:
+                UUID(candidate)
+            except (ValueError, TypeError, AttributeError) as exc:
+                raise AgentError("Codex returned an invalid thread ID") from exc
+            if resume_session and candidate != resume_session:
+                raise AgentError("Codex resumed a different thread than requested")
+            session = candidate
+        elif kind == "item.completed":
+            item = event.get("item", {})
+            if isinstance(item, dict) and item.get("type") == "agent_message" and isinstance(item.get("text"), str):
+                final_text = item["text"]
+        elif kind == "turn.completed":
+            complete = True
+            reported_usage = event.get("usage") or {}
+            if not isinstance(reported_usage, dict):
+                raise AgentError("Codex returned malformed usage metadata")
+            for key, value in reported_usage.items():
+                if key.endswith("tokens") and type(value) is int and value >= 0:
+                    usage[key] = usage.get(key, 0) + value
+        elif kind == "turn.failed":
+            failures.append(str(event.get("error", "Turn failed")))
+        elif kind == "error":
+            failures.append(str(event.get("message", "Codex error")))
+    raw = {"provider": "codex", "session_id": session, "usage": usage}
+    if returncode or failures or not complete or not session or not final_text:
+        raise AgentError("Codex failed or returned an incomplete turn: " + "; ".join(failures + [stderr[-2000:]]), raw)
+    return AgentResult(final_text, session, raw, returncode)
+
+
+class CodexClient:
+    def __init__(self, config: Config, hooks_dir: Path):
+        self.config = config
+        self.hooks_dir = hooks_dir
+
+    def probe(self, cwd: Path) -> AgentResult:
+        return self.run("Reply with the single word OK and nothing else.", cwd=cwd, role="analysis", max_turns=1)
+
+    def run(self, prompt: str, *, cwd: Path, role: str, max_turns: int,
+            resume_session: str | None = None, env: dict[str, str] | None = None,
+            budget_usd: float | None = None) -> AgentResult:
+        if role not in {"analysis", "read_only", "implementer"}:
+            raise ValueError(f"Unknown agent role: {role}")
+        if budget_usd is not None:
+            raise AgentError("Codex does not support dollar caps; use call limits and agent_timeout_seconds")
+        if resume_session:
+            try:
+                UUID(resume_session)
+            except (ValueError, TypeError, AttributeError) as exc:
+                raise AgentError("Invalid Codex resume session ID") from exc
+        sandbox = "workspace-write" if role == "implementer" else "read-only"
+        cmd = executable_command(self.config.codex_bin) + ["exec"]
+        if resume_session:
+            cmd.append("resume")
+        cmd += ["--json", "--ignore-user-config", "--model", self.config.model,
+                "-c", f"model_reasoning_effort={json.dumps(self.config.effort)}",
+                "-c", 'approval_policy="never"',
+                "-c", 'model_provider="openai"',
+                "-c", f"sandbox_mode={json.dumps(sandbox)}",
+                "-c", "sandbox_workspace_write.network_access=false"]
+        if resume_session:
+            cmd.append(resume_session)
+        cmd.append("-")
+        # max_turns is a Claude-specific control. Codex's bounded call uses the
+        # process timeout; no undocumented turn-limit flag is invented here.
+        instructions = ("Work only on the assigned task. Do not commit, push, create PRs, publish, deploy, "
+                        "or modify BACKLOG.md or .manager/. The supervisor owns Git commits.\n\n")
+        try:
+            proc = subprocess.run(cmd, cwd=str(cwd), input=instructions + prompt,
+                                  text=True, encoding="utf-8", errors="replace", capture_output=True,
+                                  timeout=self.config.agent_timeout_seconds, env=env)
+        except FileNotFoundError as exc:
+            raise AgentError(f"Codex CLI not found: {self.config.codex_bin}. Install Codex and run codex login.") from exc
+        except subprocess.TimeoutExpired as exc:
+            raise AgentError(f"Codex timed out after {self.config.agent_timeout_seconds}s") from exc
+        return parse_events(proc.stdout, proc.returncode, proc.stderr, resume_session)

opus_manager/comparison.py

@@ -0,0 +1,162 @@
+"""Opt-in unattended comparisons. Preparation never starts providers or graders."""
+from __future__ import annotations
+
+import json
+import platform
+import random
+import shutil
+import subprocess
+import time
+from dataclasses import asdict
+from pathlib import Path
+
+from .backlog import render_backlog
+from .config import Config
+from .contracts import validate_contract, unanswered
+from .gitops import git, remote_block_env, ensure_local_exclude
+from .models import BacklogTask
+from .orchestrator import Orchestrator
+from .preflight import baseline, execute_checks
+from .providers import create_client
+from .state import atomic_write_json
+from .usage import UsageLedger, summarize
+from .verification import run_checks
+
+
+def validate_manifest(raw: dict, manifest: Path) -> dict:
+    if not isinstance(raw, dict):
+        raise ValueError("Comparison manifest must be an object")
+    if not isinstance(raw.get("repo"), str) or not isinstance(raw.get("commit"), str):
+        raise ValueError("Comparison needs repo and commit strings")
+    repo = (manifest.parent / raw["repo"]).resolve()
+    commit = git(repo, "rev-parse", "--verify", str(raw["commit"]) + "^{commit}").stdout
+    cfg = Config(**raw.get("config", {}))
+    tasks = raw.get("tasks", [])
+    if not isinstance(tasks, list) or not tasks:
+        raise ValueError("Comparison needs at least one task")
+    seen = set()
+    for task in tasks:
+        if not isinstance(task, dict):
+            raise ValueError("Each task must be an object")
+        tid = task.get("id", "")
+        if not isinstance(tid, str) or not tid or any(c not in "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-" for c in tid) or tid in seen:
+            raise ValueError("Task IDs must be unique path-safe identifiers")
+        seen.add(tid)
+        if not isinstance(task.get("title"), str) or not task["title"].strip():
+            raise ValueError("Each task needs a title")
+        for key in ("acceptance_criteria", "grader_commands"):
+            values = task.get(key)
+            if not isinstance(values, list) or not values or any(not isinstance(v, str) or not v.strip() for v in values):
+                raise ValueError(f"Each task needs nonempty {key}")
+        contract = validate_contract(task.get("contract", {}), len(task["acceptance_criteria"]))
+        if unanswered(contract):
+            raise ValueError("Resolve all contract questions before comparing implementations")
+    return {"repo": str(repo), "commit": commit, "config": asdict(cfg), "tasks": tasks}
+
+
+def compare(manifest: Path, output: Path, *, live=False, repetitions=1) -> dict:
+    if repetitions < 1:
+        raise ValueError("repetitions must be positive")
+    spec = validate_manifest(json.loads(manifest.read_text(encoding="utf-8")), manifest)
+    output.mkdir(parents=True, exist_ok=False)
+    schedule = [(task["id"], repetition, arm) for task in spec["tasks"]
+                for repetition in range(repetitions) for arm in ("direct", "harbor")]
+    random.Random(0).shuffle(schedule)
+    atomic_write_json(output / "manifest.json", spec)
+    atomic_write_json(output / "schedule.json", schedule)
+    if not live:
+        return {"status": "prepared", "output": str(output), "trials": len(schedule),
+                "model_calls": 0, "note": "Use --live with a new output directory to execute. Graders are operator-trusted shell commands."}
+    cfg = Config(**spec["config"])
+    results = []
+    source = Path(spec["repo"])
+    binary = cfg.codex_bin if cfg.provider == "codex" else cfg.claude_bin
+    from .codex import executable_command
+    try:
+        command = executable_command(binary) if cfg.provider == "codex" else [shutil.which(binary) or binary]
+        version_result = subprocess.run(command + ["--version"], capture_output=True, text=True, timeout=15)
+        provider_version = version_result.stdout.strip() if version_result.returncode == 0 else "unavailable"
+    except (OSError, RuntimeError, subprocess.TimeoutExpired):
+        provider_version = "unavailable"
+    for task_id, repetition, arm in schedule:
+        task_spec = next(t for t in spec["tasks"] if t["id"] == task_id)
+        trial = output / f"{task_id}-{repetition}-{arm}"
+        trial.mkdir()
+        repo = trial / "repo"
+        row = {"task": task_id, "repetition": repetition, "arm": arm,
+               "provider": cfg.provider, "model": cfg.model, "base_commit": spec["commit"],
+               "platform": platform.platform(), "python": platform.python_version(),
+               "provider_cli_version": provider_version,
+               "human_active_minutes": None, "human_outcome": None,
+               "accepted": False, "error": None}
+        started = time.monotonic()
+        try:
+            git(source, "clone", "--no-local", "--no-hardlinks", str(source), str(repo), timeout=300)
+            git(repo, "checkout", "-b", "harbor-comparison", spec["commit"])
+            for key in ("user.name", "user.email"):
+                value = git(source, "config", "--get", key).stdout
+                git(repo, "config", key, value)
+            task = BacklogTask(task_id, task_spec["title"], acceptance_criteria=task_spec["acceptance_criteria"])
+            task.metadata["contract"] = task_spec.get("contract", {})
+            render_backlog(repo / cfg.backlog_file, {task_id: task})
+            git(repo, "add", "--", cfg.backlog_file)
+            git(repo, "commit", "--allow-empty", "-m", "Prepare comparison task")
+            ensure_local_exclude(repo, cfg.manager_dir)
+            atomic_write_json(repo / cfg.manager_dir / "contracts.json", {task_id: task.metadata["contract"]})
+            row["baseline"] = baseline(repo, cfg, spec["commit"])
+            env = remote_block_env(trial / "hooks")
+            if row["baseline"]["status"] == "ENVIRONMENT_BLOCKED":
+                raise RuntimeError("Baseline environment blocked")
+            if cfg.require_verification and row["baseline"]["status"] != "PASS":
+                raise RuntimeError("Required baseline verification did not pass")
+            agent_started = time.monotonic()
+            if arm == "harbor":
+                manager = Orchestrator.start(repo, cfg)
+                manager.run()
+                candidate = Path(manager.state.integration_worktree)
+                row["manager_stop_reason"] = manager.state.stop_reason
+                row["usage"] = summarize(manager.usage.read())
+            else:
+                environment = execute_checks(cfg, repo, env)
+                if environment["status"] == "ENVIRONMENT_BLOCKED":
+                    raise RuntimeError("Direct environment blocked")
+                client = create_client(cfg, trial / "hooks")
+                ledger = UsageLedger(trial / "usage.json", cfg)
+                call_id, cap = ledger.reserve("implementer", task_id)
+                # A single direct invocation contains the provider's normal tool loop.
+                # It receives the task and approved checks, not the independent grader.
+                prompt = "Implement this task, inspect the repository, run the approved checks, and repair failures. Do not push or publish.\n" + json.dumps({
+                    "title": task.title, "acceptance_criteria": task.acceptance_criteria,
+                    "contract": task.metadata["contract"], "verification_commands": cfg.verification_commands}, indent=2)
+                kwargs = {"cwd": repo, "role": "implementer", "max_turns": cfg.max_turns_implementer, "env": env}
+                if cfg.provider == "claude" and cap is not None:
+                    kwargs["budget_usd"] = cap
+                try:
+                    response = client.run(prompt, **kwargs)
+                    ledger.finish(call_id, response.raw)
+                    (trial / "direct-response.txt").write_text(response.text, encoding="utf-8")
+                except Exception as exc:
+                    ledger.finish(call_id, getattr(exc, "raw", None), str(exc))
+                    raise
+                row["usage"] = summarize(ledger.read())
+                candidate = repo
+            row["agent_elapsed_seconds"] = round(time.monotonic() - agent_started, 3)
+            row["independent_checks"] = run_checks(task_spec["grader_commands"], candidate,
+                timeout=cfg.verification_timeout_seconds, limit=cfg.evidence_max_chars, env=env)
+            row["accepted"] = (len(row["independent_checks"]) == len(task_spec["grader_commands"])
+                               and all(c["exit_code"] == 0 and not c["timed_out"] for c in row["independent_checks"]))
+        except Exception as exc:
+            row["error"] = str(exc)
+        row["elapsed_seconds"] = round(time.monotonic() - started, 3)
+        # Persist every failed or successful trial, not just the winners.
+        for ledger_path in [trial / "usage.json", *repo.glob(f"{cfg.manager_dir}/runs/*/usage.json")]:
+            if "usage" not in row and ledger_path.exists():
+                row["usage"] = summarize(json.loads(ledger_path.read_text(encoding="utf-8")))
+        atomic_write_json(trial / "result.json", row)
+        results.append(row)
+        atomic_write_json(output / "results.json", results)
+    summary = {arm: {"attempts": sum(r["arm"] == arm for r in results),
+                     "independently_passing": sum(r["arm"] == arm and r["accepted"] for r in results),
+                     "errors": sum(r["arm"] == arm and r["error"] is not None for r in results)} for arm in ("direct", "harbor")}
+    atomic_write_json(output / "summary.json", summary)
+    return summary

opus_manager/config.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+import json
+import math
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class Config:
+    provider: str = "claude"
+    model: str = "opus"
+    effort: str = "medium"
+    claude_bin: str = "claude"
+    codex_bin: str = "codex"
+    max_active_planners: int = 4
+    max_fix_attempts_before_restart: int = 2
+    max_fresh_implementer_generations: int = 3
+    max_plan_reworks: int = 2
+    max_code_review_fix_attempts: int = 2
+    qa_passes_per_code_review: int = 3
+    agent_timeout_seconds: int = 3600
+    max_turns_manager: int = 12
+    max_turns_planner: int = 30
+    max_turns_implementer: int = 80
+    max_turns_qa: int = 40
+    max_turns_reviewer: int = 50
+    max_turns_diagnosis: int = 50
+    max_manager_cycles: int = 1000
+    scheduler: str = "deterministic"
+    final_code_review: bool = False
+    max_agent_calls: int | None = None
+    max_task_agent_calls: int | None = None
+    max_run_cost_usd: float | None = None
+    max_call_cost_usd: float | None = None
+    verification_timeout_seconds: int = 300
+    evidence_max_chars: int = 12000
+    verification_commands: list[str] = field(default_factory=list)
+    setup_commands: list[str] = field(default_factory=list)
+    required_executables: list[str] = field(default_factory=list)
+    required_env: list[str] = field(default_factory=list)
+    verification_artifacts: list[str] = field(default_factory=list)
+    require_verification: bool = False
+    workflow: str = "standard"
+    repeated_failure_limit: int = 4
+    protected_paths: list[str] = field(default_factory=lambda: [
+        ".git", ".manager", ".env", ".env.*", "**/.env", "**/.env.*",
+        "*.pem", "*.key", "**/*.pem", "**/*.key", "secrets.*", "**/secrets.*"
+    ])
+    allow_dirty_repo: bool = False
+    keep_task_worktrees: bool = True
+    manager_dir: str = ".manager"
+    backlog_file: str = "BACKLOG.md"
+    integration_branch_prefix: str = "manager/integration"
+    task_branch_prefix: str = "manager/task"
+
+    def __post_init__(self) -> None:
+        if self.workflow not in {"standard", "adaptive"}:
+            raise ValueError("workflow must be standard or adaptive")
+        if type(self.require_verification) is not bool:
+            raise ValueError("require_verification must be a boolean")
+        if type(self.repeated_failure_limit) is not int or self.repeated_failure_limit < 2:
+            raise ValueError("repeated_failure_limit must be at least 2")
+        if self.provider not in {"claude", "codex"}:
+            raise ValueError("provider must be claude or codex")
+        if not isinstance(self.model, str) or not self.model.strip():
+            raise ValueError("model must be a nonempty model identifier")
+        if self.provider == "codex":
+            if not self.model.startswith("gpt-"):
+                raise ValueError("Set model to a GPT model available in your Codex account when provider=codex")
+            if self.max_run_cost_usd is not None or self.max_call_cost_usd is not None:
+                raise ValueError("Codex dollar budgets are unsupported; set max_run_cost_usd and max_call_cost_usd to null and use call limits")
+        nonnegative = {"max_fix_attempts_before_restart", "max_plan_reworks", "max_code_review_fix_attempts"}
+        for name, value in asdict(self).items():
+            if name.startswith("max_turns_") or name in nonnegative | {
+                "max_active_planners", "max_fresh_implementer_generations", "qa_passes_per_code_review",
+                "agent_timeout_seconds", "max_manager_cycles", "verification_timeout_seconds", "evidence_max_chars",
+            }:
+                if type(value) is not int or value < (0 if name in nonnegative else 1):
+                    raise ValueError(f"Invalid {name}: {value!r}")
+        if self.max_active_planners > 4:
+            raise ValueError("max_active_planners cannot exceed 4")
+        if self.scheduler not in {"deterministic", "model"}:
+            raise ValueError("scheduler must be deterministic or model")
+        if self.max_agent_calls is not None and (type(self.max_agent_calls) is not int or self.max_agent_calls < 1):
+            raise ValueError("max_agent_calls must be a positive integer")
+        if self.max_task_agent_calls is not None and (type(self.max_task_agent_calls) is not int or self.max_task_agent_calls < 1):
+            raise ValueError("max_task_agent_calls must be a positive integer")
+        for name in ("max_run_cost_usd", "max_call_cost_usd"):
+            value = getattr(self, name)
+            if value is not None and (type(value) not in {int, float} or not math.isfinite(value) or value <= 0):
+                raise ValueError(f"{name} must be a positive finite number")
+        for name in ("verification_commands", "setup_commands", "required_executables", "required_env", "verification_artifacts", "protected_paths"):
+            value = getattr(self, name)
+            if not isinstance(value, list) or any(not isinstance(x, str) or not x.strip() for x in value):
+                raise ValueError(f"{name} must be a list of nonempty strings")
+        for value in self.verification_artifacts:
+            path = Path(value)
+            if path.is_absolute() or ".." in path.parts:
+                raise ValueError("verification_artifacts must be paths inside the verification worktree")
+        for name in ("manager_dir", "backlog_file"):
+            value = Path(getattr(self, name))
+            if value.is_absolute() or ".." in value.parts or str(value) == ".":
+                raise ValueError(f"{name} must be a relative path inside the repository")
+        allowed_effort = {"low", "medium", "high", "xhigh", "max"} if self.provider == "claude" else {"low", "medium", "high", "xhigh", "max", "ultra"}
+        self.effort = self.effort.lower()
+        if self.effort not in allowed_effort:
+            raise ValueError(
+                f"Invalid {'Claude' if self.provider == 'claude' else 'Codex'} effort {self.effort!r}; expected one of: "
+                + ", ".join(sorted(allowed_effort))
+            )
+
+    def save(self, path: Path) -> None:
+        path.write_text(json.dumps(asdict(self), indent=2) + "\n", encoding="utf-8")
+
+    @classmethod
+    def load(cls, path: Path) -> "Config":
+        if not path.exists():
+            cfg = cls()
+            path.parent.mkdir(parents=True, exist_ok=True)
+            cfg.save(path)
+            return cfg
+        raw = json.loads(path.read_text(encoding="utf-8"))
+        known = {f.name for f in __import__("dataclasses").fields(cls)}
+        cfg = cls(**{k: v for k, v in raw.items() if k in known})
+        missing = known.difference(raw)
+        if missing:
+            # Migrate older config files when new settings gain defaults. Preserve
+            # unknown keys so forward-compatible or locally managed settings are
+            # not destroyed by an older manager version.
+            migrated = dict(raw)
+            migrated.update(asdict(cfg))
+            path.write_text(json.dumps(migrated, indent=2) + "\n", encoding="utf-8")
+        return cfg

opus_manager/contracts.py

@@ -0,0 +1,58 @@
+"""Operator-owned task intent and checks. Agents cannot authorize new shell commands."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+
+def validate_contract(value: dict, criteria_count: int | None = None) -> dict:
+    allowed = {"risk", "out_of_scope", "constraints", "allowed_paths", "questions", "answers", "acceptance_checks", "reproduction_commands"}
+    if not isinstance(value, dict) or set(value) - allowed:
+        raise ValueError("Unknown contract fields")
+    if value.get("risk", "normal") not in {"low", "normal", "high"}:
+        raise ValueError("Contract risk must be low, normal, or high")
+    for key in ("out_of_scope", "constraints", "allowed_paths", "reproduction_commands"):
+        items = value.get(key, [])
+        if not isinstance(items, list) or any(not isinstance(x, str) or not x.strip() for x in items):
+            raise ValueError(f"Contract {key} must be a list of nonempty strings")
+    for key in ("questions", "answers"):
+        items = value.get(key, {})
+        if not isinstance(items, dict) or any(not isinstance(k, str) or not k or not isinstance(v, str) or not v.strip() for k, v in items.items()):
+            raise ValueError(f"Contract {key} must map IDs to nonempty text")
+    if set(value.get("answers", {})) - set(value.get("questions", {})):
+        raise ValueError("Answers must refer to known question IDs")
+    checks = value.get("acceptance_checks", {})
+    if not isinstance(checks, dict):
+        raise ValueError("acceptance_checks must map AC IDs to command lists")
+    for key, commands in checks.items():
+        if not isinstance(key, str) or not key.startswith("AC-") or not key[3:].isdigit() or int(key[3:]) < 1:
+            raise ValueError("Invalid acceptance ID")
+        if criteria_count is not None and int(key[3:]) > criteria_count:
+            raise ValueError(f"Unknown acceptance ID: {key}")
+        if not isinstance(commands, list) or not commands or any(not isinstance(c, str) or not c.strip() for c in commands):
+            raise ValueError("Acceptance commands must be nonempty string lists")
+    return value
+
+
+def load_contracts(repo: Path, manager_dir: str) -> dict:
+    path = repo / manager_dir / "contracts.json"
+    if not path.exists():
+        return {}
+    contracts = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(contracts, dict):
+        raise ValueError("contracts.json must map task IDs to contracts")
+    return {key: validate_contract(value) for key, value in contracts.items()}
+
+
+def unanswered(contract: dict) -> dict:
+    return {key: question for key, question in contract.get("questions", {}).items()
+            if not contract.get("answers", {}).get(key)}
+
+
+def fast_path(task, cfg) -> bool:
+    contract = task.metadata.get("contract", {})
+    expected = {f"AC-{i+1}" for i in range(len(task.acceptance_criteria))}
+    return bool(cfg.workflow == "adaptive" and contract.get("risk") == "low"
+                and contract.get("allowed_paths") and expected
+                and expected == set(contract.get("acceptance_checks", {}))
+                and not unanswered(contract))

opus_manager/desktop_actions.py

@@ -0,0 +1,22 @@
+"""Launch existing CLI commands without a shell or a second terminal."""
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+def launch_run(repo: Path, runs: Path, run_id: str | None = None):
+    command = [sys.executable, "-m", "task_harbor", "--repo", str(repo)]
+    command += ["resume", "--run-id", run_id] if run_id else ["manage"]
+    logs = runs.parent / "launch-logs"
+    logs.mkdir(parents=True, exist_ok=True)
+    name = datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S-%f")
+    log = logs / f"{name}.log"
+    options = {"creationflags": subprocess.CREATE_NO_WINDOW | subprocess.CREATE_NEW_PROCESS_GROUP} if os.name == "nt" else {"start_new_session": True}
+    with log.open("wb") as output:
+        process = subprocess.Popen(command, cwd=repo, stdin=subprocess.DEVNULL,
+                                   stdout=output, stderr=subprocess.STDOUT, **options)
+    return process, log

opus_manager/evidence.py

@@ -0,0 +1,50 @@
+"""Review inputs and human-readable evidence without model-generated claims."""
+from __future__ import annotations
+
+import fnmatch
+import hashlib
+import json
+from pathlib import Path
+
+from .gitops import git
+
+
+def change_evidence(repo: Path, base: str, tip: str, cfg, contract=None) -> dict:
+    contract = contract or {}
+    names = git(repo, "diff", "--no-renames", "--name-only", "-z", base, tip).stdout.split("\0")
+    files = []
+    for name in filter(None, names):
+        if name == cfg.backlog_file or name == cfg.manager_dir or name.startswith(cfg.manager_dir + "/"):
+            continue
+        patch = git(repo, "diff", "--no-ext-diff", "--no-renames", base, tip, "--", name, timeout=300).stdout
+        warnings = []
+        allowed = contract.get("allowed_paths", [])
+        if allowed and not any(fnmatch.fnmatchcase(name, pattern) for pattern in allowed):
+            warnings.append("outside_declared_scope")
+        if any(line.startswith("-") and not line.startswith("---") and ("assert" in line or "expect(" in line) for line in patch.splitlines()):
+            warnings.append("removed_assertion_review_required")
+        if any(line.startswith("+") and any(token in line for token in (".skip(", "@pytest.mark.skip", "@unittest.skip")) for line in patch.splitlines()):
+            warnings.append("skipped_test_review_required")
+        if name.rsplit("/", 1)[-1] in {"package.json", "package-lock.json", "pyproject.toml", "requirements.txt", "Cargo.toml", "go.mod"}:
+            warnings.append("dependency_or_build_change")
+        files.append({"path": name, "diff": patch, "warnings": warnings,
+                      "sha256": hashlib.sha256(patch.encode()).hexdigest()})
+    return {"base_commit": base, "checkpoint_commit": tip, "files": files}
+
+
+def review_chunks(evidence: dict, limit: int):
+    for file in evidence["files"]:
+        patch = file["diff"]
+        count = max(1, (len(patch) + limit - 1) // limit)
+        for index in range(count):
+            yield {"path": file["path"], "part": index + 1, "parts": count,
+                   "diff": patch[index * limit:(index + 1) * limit], "sha256": file["sha256"]}
+
+
+def failure_signature(result: dict) -> str:
+    # Ignore timestamps, runtime, outputs and model prose; unchanged tree is also
+    # required by the caller, so a productive repair is not stopped by this signal.
+    payload = {"verdict": result.get("verdict"),
+               "checks": [(c.get("command"), c.get("exit_code"), c.get("timed_out")) for c in result.get("harness_checks", [])],
+               "acceptance": [(c.get("criterion_id"), c.get("status")) for c in result.get("acceptance", [])]}
+    return hashlib.sha256(json.dumps(payload, sort_keys=True).encode()).hexdigest()