task-harbor 0.7.0__py3-none-any.whl

opus_manager/gitops.py

@@ -0,0 +1,218 @@
+from __future__ import annotations
+
+import fnmatch
+import os
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable
+
+
+class GitError(RuntimeError):
+    pass
+
+
+@dataclass
+class CmdResult:
+    code: int
+    stdout: str
+    stderr: str
+
+
+def run(cmd: list[str], cwd: Path, *, check: bool = True, timeout: int = 120, env: dict[str, str] | None = None) -> CmdResult:
+    proc = subprocess.run(
+        cmd,
+        cwd=str(cwd),
+        text=True,
+        capture_output=True,
+        timeout=timeout,
+        env=env,
+    )
+    result = CmdResult(proc.returncode, proc.stdout.rstrip(), proc.stderr.rstrip())
+    if check and proc.returncode != 0:
+        raise GitError(f"Command failed ({proc.returncode}): {' '.join(cmd)}\n{result.stderr or result.stdout}")
+    return result
+
+
+def git(repo: Path, *args: str, check: bool = True, timeout: int = 120) -> CmdResult:
+    return run(["git", *args], repo, check=check, timeout=timeout)
+
+
+def ensure_repo(repo: Path) -> None:
+    if git(repo, "rev-parse", "--is-inside-work-tree", check=False).stdout != "true":
+        raise GitError(f"Not a Git worktree: {repo}")
+
+
+def current_branch(repo: Path) -> str:
+    branch = git(repo, "branch", "--show-current").stdout
+    if not branch:
+        raise GitError("Detached HEAD is not supported for manager initialization. Check out a base branch first.")
+    return branch
+
+
+def head(repo: Path) -> str:
+    return git(repo, "rev-parse", "HEAD").stdout
+
+
+def status_paths(repo: Path) -> list[str]:
+    out = git(repo, "status", "--porcelain=v1", "--untracked-files=all").stdout
+    paths: list[str] = []
+    for line in out.splitlines():
+        if len(line) < 4:
+            continue
+        raw = line[3:]
+        if " -> " in raw:
+            raw = raw.split(" -> ", 1)[1]
+        paths.append(raw.strip('"'))
+    return paths
+
+
+def meaningful_dirty(repo: Path, manager_dir: str, backlog_file: str | None = None) -> list[str]:
+    prefix = manager_dir.rstrip("/") + "/"
+    ignored = {manager_dir}
+    if backlog_file:
+        ignored.add(backlog_file.replace("\\", "/"))
+    return [
+        p for p in status_paths(repo)
+        if p.replace("\\", "/") not in ignored and not p.replace("\\", "/").startswith(prefix)
+    ]
+
+
+def ensure_local_exclude(repo: Path, manager_dir: str) -> None:
+    git_dir = Path(git(repo, "rev-parse", "--git-path", "info/exclude").stdout)
+    if not git_dir.is_absolute():
+        git_dir = repo / git_dir
+    git_dir.parent.mkdir(parents=True, exist_ok=True)
+    existing = git_dir.read_text(encoding="utf-8") if git_dir.exists() else ""
+    entry = f"/{manager_dir.strip('/')}/"
+    if entry not in existing.splitlines():
+        with git_dir.open("a", encoding="utf-8") as f:
+            if existing and not existing.endswith("\n"):
+                f.write("\n")
+            f.write(entry + "\n")
+
+
+def branch_exists(repo: Path, branch: str) -> bool:
+    return git(repo, "show-ref", "--verify", f"refs/heads/{branch}", check=False).code == 0
+
+
+def worktree_add(repo: Path, path: Path, branch: str, start_point: str, *, create_branch: bool = True) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if path.exists():
+        if any(path.iterdir()):
+            raise GitError(f"Worktree path already exists and is not empty: {path}")
+        path.rmdir()
+    if create_branch:
+        git(repo, "worktree", "add", "-b", branch, str(path), start_point, timeout=300)
+    else:
+        git(repo, "worktree", "add", str(path), branch, timeout=300)
+
+
+def detached_worktree_add(repo: Path, path: Path, commit: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if path.exists():
+        shutil.rmtree(path)
+    git(repo, "worktree", "add", "--detach", str(path), commit, timeout=300)
+
+
+def worktree_remove(repo: Path, path: Path, *, force: bool = True) -> None:
+    if not path.exists():
+        return
+    args = ["worktree", "remove"]
+    if force:
+        args.append("--force")
+    args.append(str(path))
+    git(repo, *args, check=False, timeout=300)
+    if path.exists():
+        shutil.rmtree(path, ignore_errors=True)
+
+
+def changed_paths(repo: Path) -> list[str]:
+    return status_paths(repo)
+
+
+def matches_protected(path: str, protected: Iterable[str], backlog_file: str) -> bool:
+    normalized = path.replace("\\", "/")
+    if normalized == backlog_file.replace("\\", "/"):
+        return True
+    for pat in protected:
+        p = pat.replace("\\", "/")
+        if fnmatch.fnmatch(normalized, p) or normalized == p.rstrip("/") or normalized.startswith(p.rstrip("/") + "/"):
+            return True
+    return False
+
+
+def restore_paths(repo: Path, paths: Iterable[str]) -> None:
+    tracked: list[str] = []
+    untracked: list[str] = []
+    for p in paths:
+        if git(repo, "ls-files", "--error-unmatch", "--", p, check=False).code == 0:
+            tracked.append(p)
+        else:
+            untracked.append(p)
+    if tracked:
+        git(repo, "restore", "--staged", "--worktree", "--", *tracked, check=False)
+    for p in untracked:
+        target = repo / p
+        if target.is_dir():
+            shutil.rmtree(target, ignore_errors=True)
+        elif target.exists():
+            target.unlink(missing_ok=True)
+
+
+def checkpoint(repo: Path, message: str) -> str:
+    if not changed_paths(repo):
+        return head(repo)
+    git(repo, "add", "-A")
+    # Local checkpoint commits are infrastructure, not final delivery commits.
+    result = git(repo, "commit", "-m", message, check=False, timeout=300)
+    if result.code != 0:
+        text = (result.stderr + "\n" + result.stdout).lower()
+        if "nothing to commit" not in text:
+            raise GitError(f"Could not create local checkpoint commit: {result.stderr or result.stdout}")
+    return head(repo)
+
+
+def merge_branch(integration_repo: Path, branch: str, task_id: str) -> tuple[bool, str]:
+    result = git(
+        integration_repo,
+        "merge", "--no-ff", "--no-edit", branch,
+        check=False,
+        timeout=300,
+    )
+    if result.code == 0:
+        return True, head(integration_repo)
+    conflict = git(integration_repo, "diff", "--name-only", "--diff-filter=U", check=False).stdout
+    git(integration_repo, "merge", "--abort", check=False)
+    return False, conflict or result.stderr or result.stdout
+
+
+def diff_range(repo: Path, base: str, tip: str = "HEAD") -> str:
+    return git(repo, "diff", "--stat", f"{base}..{tip}", check=False).stdout + "\n\n" + git(
+        repo, "diff", "--find-renames", f"{base}..{tip}", check=False, timeout=300
+    ).stdout
+
+
+def repo_snapshot(repo: Path) -> str:
+    branch = git(repo, "branch", "--show-current", check=False).stdout or "DETACHED"
+    h = head(repo)
+    status = git(repo, "status", "--short", check=False).stdout or "clean"
+    recent = git(repo, "log", "-5", "--oneline", check=False).stdout
+    return f"branch: {branch}\nhead: {h}\nstatus:\n{status}\nrecent commits:\n{recent}"
+
+
+def remote_block_env(hooks_dir: Path) -> dict[str, str]:
+    hooks_dir.mkdir(parents=True, exist_ok=True)
+    hook = hooks_dir / "pre-push"
+    hook.write_text("#!/bin/sh\necho 'Remote git push blocked by Task Harbor' >&2\nexit 1\n", encoding="utf-8")
+    try:
+        hook.chmod(0o755)
+    except OSError:
+        pass
+    env = os.environ.copy()
+    # Environment-scoped Git config: inherited by git processes spawned by Claude.
+    env["GIT_CONFIG_COUNT"] = "1"
+    env["GIT_CONFIG_KEY_0"] = "core.hooksPath"
+    env["GIT_CONFIG_VALUE_0"] = str(hooks_dir)
+    return env

opus_manager/help.py

@@ -0,0 +1,59 @@
+GUIDE = """TASK HARBOR — GETTING STARTED
+
+1. Open a terminal in your Git repository (with at least one commit).
+   task-harbor init
+2. Edit BACKLOG.md: give each task an ID and acceptance criteria.
+3. Edit .manager/config.json. Choose provider claude or codex and a model
+   available to your account. Sign in with that provider's CLI first.
+   For Codex, use a gpt-* model and leave both dollar caps null.
+4. Set verification_commands to your test/build commands. Set max_agent_calls
+   to limit usage; by default calls are unlimited.
+5. Check and run:
+   task-harbor check        (read-only readiness; no model calls or project commands)
+   task-harbor preflight    (suggests checks; no model calls)
+   task-harbor preflight --run-checks
+   task-harbor validate
+   task-harbor doctor       (makes a model call)
+   task-harbor manage       (starts paid/subscription agent work)
+6. Open another terminal in the same repository:
+   task-harbor
+
+MONITOR AND CONTROL
+List saved runs with task-harbor runs (or runs --status paused).
+Use check --json and runs --json for machine-readable results.
+Saved run status is a snapshot, not proof that a process is running.
+The dashboard refreshes every two seconds. Viewing does not call models.
+Set up creates config/backlog; Validate checks them without model calls.
+New run and Resume show settings before you confirm agent work.
+Stop pauses after in-flight calls. Launch output: .manager/launch-logs/.
+Tab / Shift+Tab: change pane. Arrows: select task or run. F1: help. q: exit.
+Closing the dashboard does not stop a run. Use:
+   task-harbor stop --run-id RUN_ID
+   task-harbor resume --run-id RUN_ID
+Stop waits for in-flight calls to finish. Resume keeps existing usage counts.
+Review results on manager/integration/RUN_ID. Nothing is automatically pushed.
+
+EVIDENCE AND QUESTIONS
+Press E in the dashboard to inspect a task, P for suggested checks.
+   task-harbor review --run-id RUN_ID --html review.html
+   task-harbor questions --run-id RUN_ID
+   task-harbor answer --run-id RUN_ID --task TASK_ID --question Q-1 --text "Your answer"
+   task-harbor resume --run-id RUN_ID
+Record your review outcome separately from model QA:
+   task-harbor feedback --run-id RUN_ID --task TASK_ID --outcome accepted --minutes 5
+Compare against a direct agent with an operator-written task manifest:
+   task-harbor compare --manifest comparison.json --output prepared
+Preparation calls no models. Add --live with a new output folder to run both arms.
+
+TROUBLESHOOTING
+Command not found? Use python -m task_harbor with the same arguments.
+No runs? Use Set up, edit the files, Validate, then New run.
+A run is one execution of a backlog; the picker only appears when runs exist.
+Different directory? Put --repo "path/to/app" BEFORE the command.
+Unknown cost? The provider did not report it; it is not a zero-cost call.
+Blocked task? Inspect task details and saved logs, fix the cause, then use
+retry --run-id RUN_ID --task TASK_ID followed by resume --run-id RUN_ID.
+
+Run task-harbor COMMAND --help for command options.
+Documentation: https://github.com/rhit-nayeems/task-harbor
+"""

opus_manager/models.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from enum import StrEnum
+from typing import Any
+
+
+class TaskStatus(StrEnum):
+    UNPLANNED = "UNPLANNED"
+    PLANNING = "PLANNING"
+    PLAN_REVIEW = "PLAN_REVIEW"
+    READY = "READY"
+    IMPLEMENTING = "IMPLEMENTING"
+    QA = "QA"
+    QA_FAIL = "QA_FAIL"
+    QA_PASSED = "QA_PASSED"
+    CODE_REVIEW = "CODE_REVIEW"
+    COMPLETE = "COMPLETE"
+
+
+class Priority(StrEnum):
+    BLOCKER = "blocker"
+    CRITICAL_BUG = "critical_bug"
+    HIGH_RISK = "high_risk"
+    CORE = "core"
+    LOW_RISK = "low_risk"
+    POLISH = "polish"
+
+
+PRIORITY_ORDER = {
+    Priority.BLOCKER: 0,
+    Priority.CRITICAL_BUG: 1,
+    Priority.HIGH_RISK: 2,
+    Priority.CORE: 3,
+    Priority.LOW_RISK: 4,
+    Priority.POLISH: 5,
+}
+
+
+@dataclass
+class BacklogTask:
+    task_id: str
+    title: str
+    priority: Priority = Priority.CORE
+    status: TaskStatus = TaskStatus.UNPLANNED
+    owner: str | None = None
+    dependencies: list[str] = field(default_factory=list)
+    acceptance_criteria: list[str] = field(default_factory=list)
+    next_action: str = ""
+    blocked_reason: str | None = None
+    plan_path: str | None = None
+    plan_base_commit: str | None = None
+    plan_reworks: int = 0
+    implementer_session_id: str | None = None
+    worktree_path: str | None = None
+    branch_name: str | None = None
+    checkpoint_commit: str | None = None
+    last_qa_path: str | None = None
+    qa_failures: int = 0
+    generation: int = 0
+    last_error: str | None = None
+    completed_commit: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def blocked(self) -> bool:
+        return bool(self.blocked_reason)
+
+    def to_dict(self) -> dict[str, Any]:
+        d = asdict(self)
+        d["priority"] = self.priority.value
+        d["status"] = self.status.value
+        return d
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> "BacklogTask":
+        x = dict(d)
+        x["priority"] = Priority(x.get("priority", Priority.CORE))
+        x["status"] = TaskStatus(x.get("status", TaskStatus.UNPLANNED))
+        return cls(**x)
+
+
+@dataclass
+class ManagerState:
+    run_id: str
+    repo: str
+    integration_branch: str
+    integration_worktree: str
+    base_branch: str
+    base_commit: str
+    tasks: dict[str, BacklogTask] = field(default_factory=dict)
+    qa_passes_since_review: int = 0
+    last_review_commit: str | None = None
+    active_planners: list[str] = field(default_factory=list)
+    event_seq: int = 0
+    paused: bool = False
+    stop_reason: str | None = None
+    schema_version: int = 3
+    provider: str = "claude"
+
+    def to_dict(self) -> dict[str, Any]:
+        d = asdict(self)
+        d["tasks"] = {k: v.to_dict() for k, v in self.tasks.items()}
+        return d
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> "ManagerState":
+        x = dict(d)
+        x["tasks"] = {k: BacklogTask.from_dict(v) for k, v in x.get("tasks", {}).items()}
+        return cls(**x)

opus_manager/offline.py

@@ -0,0 +1,142 @@
+"""Read-only local readiness and saved-run discovery."""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+from dataclasses import fields
+from pathlib import Path
+
+from .backlog import parse_backlog
+from .config import Config
+from .contracts import load_contracts, unanswered, validate_contract
+from .gitops import git
+from .models import TaskStatus
+from .orchestrator import ManagerError, validate_tasks
+from .state import load_state
+
+
+def read_config(repo: Path) -> Config:
+    path = repo / ".manager" / "config.json"
+    if not path.exists():
+        return Config()
+    raw = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(raw, dict):
+        raise ValueError("Configuration must be a JSON object")
+    names = {f.name for f in fields(Config)}
+    return Config(**{k: v for k, v in raw.items() if k in names})
+
+
+def readiness(repo: Path) -> dict:
+    checks = []
+
+    def add(name, status, detail):
+        checks.append({"name": name, "status": status, "detail": detail})
+
+    try:
+        cfg = read_config(repo)
+    except (ValueError, TypeError, OSError) as exc:
+        return {"ready": False, "checks": [{"name": "Configuration", "status": "error",
+                                           "detail": str(exc)}], "model_calls": 0}
+    configured = (repo / ".manager" / "config.json").is_file()
+    add("Configuration", "pass" if configured else "warning",
+        "Configuration loaded." if configured else "Run task-harbor init to create a configuration.")
+    if not shutil.which("git"):
+        add("Git", "error", "Install Git and put it on PATH.")
+    elif git(repo, "rev-parse", "--verify", "HEAD", check=False).code:
+        add("Git", "error", "Use a Git repository with at least one commit.")
+    else:
+        add("Git", "pass", "Repository has a committed starting point.")
+        dirty = bool(git(repo, "status", "--porcelain", check=False).stdout.strip())
+        add("Working tree", "warning" if dirty and cfg.allow_dirty_repo else "error" if dirty else "pass",
+            "Uncommitted changes exist; commit or stash them before a run." if dirty else "Working tree is clean.")
+        identity = all(git(repo, "config", key, check=False).stdout.strip()
+                       for key in ("user.name", "user.email"))
+        add("Git author", "pass" if identity else "error",
+            "Git author is configured." if identity else "Configure git user.name and user.email.")
+    binary = cfg.codex_bin if cfg.provider == "codex" else cfg.claude_bin
+    add("Agent executable", "pass" if shutil.which(binary) else "error",
+        f"{cfg.provider}: executable found; authentication not tested." if shutil.which(binary)
+        else f"Install {cfg.provider} or correct its configured executable.")
+    for name in cfg.required_executables:
+        add(f"Executable: {name}", "pass" if shutil.which(name) else "error",
+            "Found on PATH." if shutil.which(name) else "Required executable is missing.")
+    for name in cfg.required_env:
+        add(f"Environment: {name}", "pass" if os.environ.get(name) else "error",
+            "Present (value hidden)." if os.environ.get(name) else "Required variable is missing.")
+    add("Verification", "pass" if cfg.verification_commands else "error" if cfg.require_verification else "warning",
+        f"{len(cfg.verification_commands)} configured command(s); not executed."
+        if cfg.verification_commands else "No checks configured. Add verification_commands before relying on QA.")
+    add("Verification policy", "pass" if cfg.require_verification else "warning",
+        "Checks are required." if cfg.require_verification else "require_verification is false; missing checks do not stop runs.")
+    add("Usage limit", "pass" if cfg.max_agent_calls else "warning",
+        f"Run limited to {cfg.max_agent_calls} agent calls." if cfg.max_agent_calls else "No run-wide call limit is configured.")
+    try:
+        tasks = parse_backlog(repo / cfg.backlog_file)
+        validate_tasks(tasks)
+        add("Backlog", "pass" if tasks else "error",
+            f"{len(tasks)} task(s) validated." if tasks else "Backlog contains no tasks.")
+        for task in tasks.values():
+            if not task.acceptance_criteria:
+                add(f"Acceptance: {task.task_id}", "error", "Add acceptance criteria before starting this task.")
+        contracts = load_contracts(repo, cfg.manager_dir)
+        for task_id, contract in contracts.items():
+            if task_id not in tasks:
+                add(f"Agreement: {task_id}", "warning", "No matching backlog task.")
+                continue
+            validate_contract(contract, len(tasks[task_id].acceptance_criteria))
+            pending = unanswered(contract)
+            if pending:
+                add(f"Agreement: {task_id}", "warning",
+                    f"{len(pending)} unanswered question(s); this task will wait for clarification.")
+    except (ValueError, TypeError, OSError, ManagerError) as exc:
+        add("Backlog / agreements", "error", str(exc))
+    return {"ready": not any(c["status"] == "error" for c in checks), "checks": checks,
+            "model_calls": 0, "note": "Readiness only: authentication and command outcomes were not tested."}
+
+
+def saved_runs(repo: Path, status: str | None = None) -> dict:
+    cfg = read_config(repo)
+    root = repo / cfg.manager_dir / "runs"
+    runs, errors = [], []
+    for directory in sorted(root.iterdir(), reverse=True) if root.exists() else []:
+        if not directory.is_dir() or directory.is_symlink():
+            continue
+        try:
+            state = load_state(directory / "state.json")
+            tasks = list(state.tasks.values())
+            complete = sum(t.status == TaskStatus.COMPLETE for t in tasks)
+            kind = "complete" if tasks and complete == len(tasks) else "paused" if state.paused else "unfinished"
+            item = {"id": directory.name, "status": kind, "provider": state.provider,
+                    "completed": complete, "total": len(tasks),
+                    "blocked": sum(t.blocked for t in tasks), "stop_reason": state.stop_reason,
+                    "branch": state.integration_branch}
+            if status is None or status == kind:
+                runs.append(item)
+        except (ValueError, TypeError, KeyError, AttributeError, OSError) as exc:
+            errors.append({"id": directory.name, "error": str(exc)})
+    return {"runs": runs, "errors": errors,
+            "note": "Saved snapshots; unfinished does not mean a process is currently running."}
+
+
+def run_offline(args, repo: Path) -> int:
+    result = readiness(repo) if args.command == "check" else saved_runs(repo, args.status)
+    if args.json:
+        print(json.dumps(result, indent=2))
+    elif args.command == "check":
+        for item in result["checks"]:
+            print(f"{item['status'].upper():7} {item['name']}: {item['detail']}")
+        print("Ready for a run." if result["ready"] else "Resolve the errors above before starting.")
+        print("No model calls or project commands executed. Authentication is not tested.")
+    else:
+        for run in result["runs"]:
+            print(f"{run['id']}  {run['status']}  {run['completed']}/{run['total']} complete  "
+                  f"{run['blocked']} blocked  {run['provider']}")
+            if run["stop_reason"]:
+                print(f"  {run['stop_reason']}")
+        if not result["runs"]:
+            print("No saved runs match. Start one with task-harbor manage.")
+        for error in result["errors"]:
+            print(f"Unreadable run {error['id']}: {error['error']}")
+        print(result["note"])
+    return 2 if (args.command == "check" and not result["ready"]) or result.get("errors") else 0

opus_manager/operator_commands.py

@@ -0,0 +1,86 @@
+"""Local operator actions; no model calls."""
+import json
+import math
+from datetime import datetime, timezone
+
+from .backlog import parse_backlog
+from .contracts import load_contracts, validate_contract, unanswered
+from .gitops import head, ensure_repo
+from .orchestrator import Orchestrator
+from .preflight import baseline, suggestions
+from .reporting import run_report, write_html, review_text
+from .state import atomic_write_json, load_state
+
+
+def run_operator_command(args, repo, cfg):
+    root = repo / cfg.manager_dir
+    if args.command == "preflight":
+        ensure_repo(repo)
+        if not args.run_checks:
+            print(json.dumps({"suggestions_not_executed": suggestions(repo), "approved_commands": cfg.verification_commands,
+                              "setup_commands": cfg.setup_commands,
+                              "next": "Edit .manager/config.json, then preflight --run-checks"}, indent=2))
+            return 0
+        result = baseline(repo, cfg, head(repo))
+        atomic_write_json(root / "preflight.json", result)
+        print(json.dumps(result, indent=2))
+        return 0 if result["status"] == "PASS" else 2
+    if args.command == "contract":
+        tasks = parse_backlog(repo / cfg.backlog_file)
+        if args.task not in tasks:
+            raise ValueError("Task not found in backlog")
+        contract = validate_contract(json.loads(args.file.read_text(encoding="utf-8")), len(tasks[args.task].acceptance_criteria))
+        contracts = load_contracts(repo, cfg.manager_dir)
+        contracts[args.task] = contract
+        atomic_write_json(root / "contracts.json", contracts)
+        print("Agreement saved for future runs. Existing runs keep their saved agreement.")
+        return 0
+    run_dir = root / "runs" / args.run_id
+    if args.command == "review":
+        report = run_report(run_dir)
+        if args.html:
+            if args.task:
+                report["tasks"] = [t for t in report["tasks"] if t["id"] == args.task]
+                if not report["tasks"]:
+                    raise ValueError("Task not found")
+            write_html(report, args.html)
+            print(f"Review: {args.html.resolve()}")
+        else:
+            print(review_text(report, args.task))
+        return 0
+    if args.command == "questions":
+        state = load_state(run_dir / "state.json")
+        print(json.dumps({t.task_id: unanswered(t.metadata.get("contract", {})) for t in state.tasks.values()
+                          if unanswered(t.metadata.get("contract", {}))}, indent=2))
+        return 0
+    manager = Orchestrator.resume(repo, cfg, args.run_id)
+    manager._acquire_run_lock()
+    try:
+        manager.state = load_state(run_dir / "state.json")
+        task = manager.state.tasks.get(args.task)
+        if task is None:
+            raise ValueError("Task not found")
+        if args.command == "answer":
+            contract = task.metadata.get("contract", {})
+            if args.question not in contract.get("questions", {}) or not args.text.strip():
+                raise ValueError("Supply a known question ID and a nonempty answer")
+            contract.setdefault("answers", {})[args.question] = args.text
+            if not unanswered(contract) and task.metadata.get("blocked_kind") == "clarification":
+                task.blocked_reason = None
+                task.metadata.pop("blocked_kind", None)
+            manager._event("OPERATOR_ANSWER", task_id=args.task, question_id=args.question)
+            manager._sync_backlog()
+            print("Answer saved. Resume the run to continue.")
+        else:
+            if not math.isfinite(args.minutes) or args.minutes < 0:
+                raise ValueError("Review minutes must be finite and nonnegative")
+            path = run_dir / "feedback.json"
+            entries = json.loads(path.read_text(encoding="utf-8")) if path.exists() else []
+            entries.append({"task": args.task, "outcome": args.outcome, "active_review_minutes": args.minutes,
+                            "note": args.note, "checkpoint": task.checkpoint_commit,
+                            "time": datetime.now(timezone.utc).isoformat()})
+            atomic_write_json(path, entries)
+            print("Review feedback saved; task status was not changed.")
+    finally:
+        manager._release_run_lock()
+    return 0