codna 0.1.0__py3-none-any.whl

codna/cli.py

@@ -0,0 +1,921 @@
+"""The `codna` command. Codna understands and fixes your repository.
+
+Normal local topology: codna calls the local Algenta repository-intelligence SDK/core
+in-process, writes local Arrow/Parquet artifacts, and starts the sidecar-only agent
+core when verified planning needs model execution. Remote engine URLs remain supported
+only when explicitly provided through the real shell environment.
+"""
+from __future__ import annotations
+
+import argparse
+from itertools import count
+import json
+import os
+from pathlib import Path
+from pathlib import PurePosixPath
+import re
+import subprocess
+import sys
+import time
+from typing import Any
+
+import httpx
+
+from . import __version__
+from .agent_core_runtime import ensure_agent_core_running, inspect_agent_core_runtime, stop_agent_core_runtime
+from .cli_errors import format_cli_error
+from .local_mojo_pool import legacy_global_mojo_worker_diagnostics, mojo_worker_diagnostics
+from .runtime import LocalRuntimeError, ensure_running
+from .runtime.config import API_KEY_KEYS, RuntimeConfigError, parse_keys_file_values, resolve_runtime_config
+
+_CONNECTOR_NAME_COUNTER = count()
+_FOCUS_PATH_PATTERNS = (
+    re.compile(r'File\s+"([^"]+)"(?:,\s*line\s*\d+)?', re.I),
+    re.compile(r"\b(?:Target file|Path):\s*`?([^`\s]+)`?", re.I),
+)
+
+
+class CodnaError(Exception):
+    """User-facing CLI error that can be surfaced without terminating embedded callers."""
+
+
+def _die(msg: str) -> None:
+    raise CodnaError(msg)
+
+
+def _structured_error(exc: BaseException) -> dict[str, object] | None:
+    code = getattr(exc, "code", None)
+    if not code:
+        return None
+    details = getattr(exc, "details", {})
+    return {
+        "error": {
+            "code": str(code),
+            "message": str(exc),
+            "details": details if isinstance(details, dict) else {},
+        }
+    }
+
+
+def _keys_file_path() -> Path:
+    return Path(os.environ.get("CODNA_KEYS_FILE") or (Path(__file__).resolve().parents[2] / "keys.txt"))
+
+
+def _runtime_keys():
+    path = _keys_file_path().expanduser()
+    return parse_keys_file_values(path) if path.is_file() else {}
+
+
+def _api_key(keys) -> str | None:
+    for name in API_KEY_KEYS:
+        value = os.environ.get(name)
+        if value:
+            return value
+    for name in API_KEY_KEYS:
+        config_value = keys.get(name)
+        if config_value and config_value.value:
+            return config_value.value
+    return None
+
+
+class _HttpCodnaClient:
+    """Explicit remote/compatibility client for the repository-intelligence API."""
+
+    _RETRYABLE_STATUS = {429, 500, 502, 503, 504}
+    _DEFAULT_MAX_RETRIES = 2
+    _BACKOFF_BASE_S = 0.25
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str,
+        timeout: float,
+        max_retries: int | None = None,
+    ) -> None:
+        if not api_key:
+            _die("no API key — set CODNA_API_KEY (your codna key).")
+        if not base_url:
+            _die("no engine URL resolved — run `codna doctor --start-stack` for local runtime diagnostics.")
+        self._max_retries = self._resolve_max_retries(max_retries)
+        self._client = httpx.Client(
+            base_url=base_url.rstrip("/"),
+            timeout=timeout,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+                "User-Agent": f"codna-cli/{__version__}",
+            },
+        )
+
+    @classmethod
+    def _resolve_max_retries(cls, max_retries: int | None) -> int:
+        raw = str(
+            max_retries
+            if max_retries is not None
+            else os.environ.get("CODNA_HTTP_MAX_RETRIES", cls._DEFAULT_MAX_RETRIES)
+        )
+        try:
+            value = int(raw)
+        except ValueError as exc:
+            raise CodnaError("CODNA_HTTP_MAX_RETRIES must be an integer.") from exc
+        if value < 0:
+            raise CodnaError("CODNA_HTTP_MAX_RETRIES must be >= 0.")
+        return value
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_payload: dict[str, Any] | None = None,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        if json_payload is not None and json is not None:
+            raise CodnaError("internal client received both json_payload and json.")
+        body = json_payload if json_payload is not None else json
+        last_error: Exception | None = None
+        for attempt in range(self._max_retries + 1):
+            try:
+                response = self._client.request(method, path, json=body, params=params)
+            except httpx.HTTPError as exc:
+                last_error = exc
+                if attempt < self._max_retries:
+                    self._sleep_before_retry(attempt)
+                    continue
+                raise CodnaError(f"engine {method} {path} failed: {exc}") from exc
+            if response.status_code in self._RETRYABLE_STATUS and attempt < self._max_retries:
+                self._sleep_before_retry(attempt)
+                continue
+            return self._parse_response(method, path, response)
+        raise CodnaError(f"engine {method} {path} failed: {last_error}")
+
+    def _sleep_before_retry(self, attempt: int) -> None:
+        time.sleep(self._BACKOFF_BASE_S * (attempt + 1))
+
+    @staticmethod
+    def _parse_response(method: str, path: str, response: httpx.Response) -> dict[str, Any]:
+        payload: Any = {}
+        if response.content:
+            try:
+                payload = response.json()
+            except ValueError:
+                payload = {"raw": response.text[:1000]}
+        if 200 <= response.status_code < 300:
+            if isinstance(payload, dict):
+                return payload
+            raise CodnaError(f"engine {method} {path} returned non-object JSON.")
+        message, details = _extract_engine_error(payload)
+        request_id = response.headers.get("x-request-id") or response.headers.get("x-codna-request-id")
+        suffix = f" request_id={request_id}" if request_id else ""
+        detail_text = f" details={json.dumps(details, sort_keys=True)}" if details else ""
+        raise CodnaError(
+            f"engine {method} {path} failed: status={response.status_code} "
+            f"message={message}{suffix}{detail_text}"
+        )
+
+    def create_connector(
+        self,
+        *,
+        name: str,
+        connector_type: str,
+        config: dict[str, Any] | None = None,
+        description: str | None = None,
+        visibility: str | None = None,
+    ) -> dict[str, Any]:
+        payload: dict[str, Any] = {"name": name, "connector_type": connector_type, "config": config or {}}
+        if description is not None:
+            payload["description"] = description
+        if visibility is not None:
+            payload["visibility"] = visibility
+        return self._request("POST", "/v1/connectors", json_payload=payload)
+
+    def get_repository_intelligence_capabilities(self) -> dict[str, Any]:
+        return self._request("GET", "/v1/repositories/capabilities")
+
+    def create_repository_snapshot(self, repository_id: str, request: dict[str, Any]) -> dict[str, Any]:
+        return self._request("POST", f"/v1/repositories/{repository_id}/snapshots", json_payload=request)
+
+    def get_repository_snapshot(self, repository_id: str, snapshot_id: str) -> dict[str, Any]:
+        return self._request("GET", f"/v1/repositories/{repository_id}/snapshots/{snapshot_id}")
+
+    def triage_repository(self, repository_id: str, request: dict[str, Any]) -> dict[str, Any]:
+        return self._request("POST", f"/v1/repositories/{repository_id}/triage", json_payload=request)
+
+    def create_repository_decision_plan(self, repository_id: str, request: dict[str, Any]) -> dict[str, Any]:
+        return self._request("POST", f"/v1/repositories/{repository_id}/decision-plans", json_payload=request)
+
+    def query_repository_graph(self, repository_id: str, request: dict[str, Any]) -> dict[str, Any]:
+        return self._request("POST", f"/v1/repositories/{repository_id}/graph-query", json_payload=request)
+
+    def simulate_repository(self, repository_id: str, request: dict[str, Any]) -> dict[str, Any]:
+        return self._request("POST", f"/v1/repositories/{repository_id}/simulate", json_payload=request)
+
+    def apply_repository(self, repository_id: str, request: dict[str, Any]) -> dict[str, Any]:
+        return self._request("POST", f"/v1/repositories/{repository_id}/apply", json_payload=request)
+
+
+def _extract_engine_error(payload: Any) -> tuple[str, dict[str, Any]]:
+    if not isinstance(payload, dict):
+        return "engine returned a non-object error response", {}
+    error = payload.get("error")
+    if isinstance(error, dict):
+        msg = error.get("message") or error.get("code") or "engine request failed"
+        details = error.get("details") if isinstance(error.get("details"), dict) else {}
+        return str(msg), details
+    msg = payload.get("message") or payload.get("detail") or payload.get("raw") or "engine request failed"
+    return str(msg), {}
+
+
+def _engine_url_key():
+    """Resolve engine URL + API key.
+
+    Remote explicit env wins. Otherwise the owned local runtime is ensured for
+    legacy HTTP-only surfaces. Normal repository triage/fix uses _client(), which
+    defaults to the in-process local SDK path and does not call this function.
+    """
+    keys = _runtime_keys()
+    config = resolve_runtime_config(keys=keys)
+    if config.remote_engine_url:
+        return config.remote_engine_url.rstrip("/"), _api_key(keys)
+    endpoint = ensure_running(keys=keys)
+    url = endpoint.engine_url
+    return url.rstrip("/"), _api_key(keys)
+
+
+def _client():
+    keys = _runtime_keys()
+    config = resolve_runtime_config(keys=keys)
+    if not config.remote_engine_url:
+        from .local_client import LocalCodnaRuntimeClient
+
+        return LocalCodnaRuntimeClient(keys=keys)
+
+    url = config.remote_engine_url
+    key = _api_key(keys)
+    if not key:
+        _die("no API key — set CODNA_API_KEY (your codna key).")
+    timeout = float(os.environ.get("CODNA_TIMEOUT_S", "1800"))
+    return _HttpCodnaClient(api_key=key, base_url=url, timeout=timeout)
+
+
+def _dump(x):
+    return x.model_dump() if hasattr(x, "model_dump") else x
+
+
+def _connector_name(prefix: str = "codna") -> str:
+    return f"{prefix}-{time.time_ns()}-{next(_CONNECTOR_NAME_COUNTER)}"
+
+
+def _clean_git_head(local_path: str) -> str | None:
+    try:
+        head = subprocess.run(
+            ["git", "rev-parse", "--verify", "HEAD"],
+            cwd=local_path,
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=10,
+        )
+        if head.returncode != 0:
+            return None
+        revision = head.stdout.strip().lower()
+        if len(revision) != 40 or any(char not in "0123456789abcdef" for char in revision):
+            return None
+        status = subprocess.run(
+            ["git", "status", "--porcelain=v1", "-z", "--untracked-files=all"],
+            cwd=local_path,
+            capture_output=True,
+            check=False,
+            timeout=30,
+        )
+        if status.returncode != 0 or status.stdout:
+            return None
+        return revision
+    except (OSError, subprocess.SubprocessError):
+        return None
+
+
+def _local_repo_connector_config(local_path: str) -> dict[str, object]:
+    config: dict[str, object] = {"path": local_path}
+    clean_head = _clean_git_head(local_path)
+    if clean_head is not None:
+        config["assume_clean_git_clone"] = True
+        config["resolved_revision"] = clean_head
+    return config
+
+
+def _normalize_focus_path(local_path: str, raw_path: str) -> str | None:
+    repo_root = Path(local_path).expanduser().resolve()
+    candidate = raw_path.strip().strip("`'\"")
+    candidate = candidate.lstrip("<([{")
+    candidate = candidate.rstrip(">)]},:;")
+    candidate = candidate.replace("\\", "/")
+    if not candidate:
+        return None
+    candidate_path = Path(candidate)
+    if candidate_path.is_absolute():
+        try:
+            relative = candidate_path.resolve().relative_to(repo_root)
+        except ValueError:
+            return None
+    else:
+        relative = Path(PurePosixPath(candidate))
+        if ".." in relative.parts or relative.is_absolute():
+            return None
+    normalized = PurePosixPath(relative.as_posix())
+    if normalized.as_posix() in {"", "."}:
+        return None
+    if not (repo_root / normalized.as_posix()).is_file():
+        return None
+    return normalized.as_posix()
+
+
+def _issue_focus_paths(local_path: str, issue: str | None) -> list[str]:
+    if not issue:
+        return []
+    output: list[str] = []
+    seen: set[str] = set()
+    for pattern in _FOCUS_PATH_PATTERNS:
+        for match in pattern.finditer(issue):
+            normalized = _normalize_focus_path(local_path, match.group(1))
+            if normalized is None or normalized in seen:
+                continue
+            seen.add(normalized)
+            output.append(normalized)
+            if len(output) >= 8:
+                return output
+    return output
+
+
+def _register(
+    c,
+    repo: str,
+    ref: str | None,
+    github_token: str | None = None,
+    focus_paths: list[str] | None = None,
+):
+    local = os.path.abspath(os.path.expanduser(repo))
+    if os.path.isdir(local) and not github_token:
+        # the user's own repo on this machine (local SDK/core reads it directly)
+        conn = _dump(c.create_connector(name=_connector_name(),
+                                        connector_type="local_repo",
+                                        config=_local_repo_connector_config(local)))
+    elif repo.startswith(("http://", "https://")) or repo.endswith(".git"):
+        cfg = {"repository_url": repo}
+        if github_token:  # write scope, needed to push a branch + open a PR
+            cfg["access_token"] = github_token
+        conn = _dump(c.create_connector(name=_connector_name(),
+                                        connector_type="github_repo", config=cfg))
+    else:
+        _die(f"'{repo}': not a local directory or a git URL.")
+    rid = conn.get("id") or conn.get("connector_id")
+    req = {"focus_paths": list(dict.fromkeys(focus_paths or []))}
+    if ref:
+        req["ref"] = ref
+    snap = _dump(c.create_repository_snapshot(rid, req))
+    return rid, snap
+
+
+def cmd_triage(args) -> None:
+    c = _client()
+    print(f"codna: understanding {args.repo} …")
+    t = time.perf_counter()
+    local = os.path.abspath(os.path.expanduser(args.repo))
+    issue = args.issue or "Map this repository and locate its most relevant code."
+    focus_paths = _issue_focus_paths(local, issue) if os.path.isdir(local) else []
+    rid, snap = _register(c, args.repo, args.ref, focus_paths=focus_paths)
+    sig = {"issue_text": issue}
+    if focus_paths:
+        sig["changed_files"] = focus_paths
+    tri = _dump(c.triage_repository(rid, {"snapshot_id": snap["snapshot_id"], "signals": sig}))
+    dt = time.perf_counter() - t
+    files = snap.get("snapshot_file_count") or snap.get("file_count")
+    raw = tri.get("raw_repo_token_estimate") or 0
+    bundle = tri.get("evidence_bundle_token_count") or 0
+    rr = tri.get("reduction_ratio")
+    print(f"\n✓ codna understood {files} files in {dt:.1f}s")
+    print(f"  suspect files : {', '.join(tri.get('suspect_files') or []) or '(none)'}")
+    if rr:
+        print(f"  context        : {raw:,} → {bundle:,} tokens  ({rr:.0f}× smaller for the agent)")
+
+
+def _from_junit(path: str):
+    """Turn a JUnit/pytest XML report into (issue_text, [failing_test_ids])."""
+    import xml.etree.ElementTree as ET
+    try:
+        root = ET.parse(os.path.expanduser(path)).getroot()
+    except Exception as exc:  # noqa: BLE001
+        _die(f"could not read JUnit report {path}: {exc}")
+    failing = []
+    for case in root.iter("testcase"):
+        if case.find("failure") is not None or case.find("error") is not None:
+            name = case.get("name", "")
+            cls = case.get("classname", "")
+            failing.append(f"{cls}::{name}" if cls else name)
+    if not failing:
+        return None, []
+    return f"{len(failing)} failing test(s): " + "; ".join(failing[:8]), failing
+
+
+def _resolve_issue(args):
+    if args.from_junit:
+        issue, failing = _from_junit(args.from_junit)
+        if args.issue:
+            issue = args.issue
+        return issue, failing
+    return args.issue, (args.failing_test or [])
+
+
+def _sim_id(sim: dict):
+    # /simulate returns a DecisionEnvelope; the simulation id is surfaced in
+    # validated_inputs.simulation_id (see engine execution_workflow ~L499).
+    vi = sim.get("validated_inputs") or {}
+    if vi.get("simulation_id"):
+        return vi["simulation_id"]
+    for k in ("simulation_id", "id"):
+        if sim.get(k):
+            return sim[k]
+    for nest in ("envelope", "decision_plan", "result"):
+        v = (sim.get(nest) or {})
+        if isinstance(v, dict) and v.get("simulation_id"):
+            return v["simulation_id"]
+    return None
+
+
+def _pr_body(issue, ra, plan):
+    dp = plan.get("decision_plan") or {}
+    lines = ["Automated fix by **codna**.", "", f"**Issue:** {issue}"]
+    if ra.get("root_cause"):
+        lines.append(f"**Root cause:** {ra['root_cause']}")
+    if ra.get("impacted_symbols"):
+        lines.append(f"**Symbols:** {', '.join(ra['impacted_symbols'])}")
+    if dp.get("confidence") is not None:
+        lines.append(f"**Confidence:** {int(dp['confidence'] * 100)}%")
+    lines += ["", "_Review before merging._"]
+    return "\n".join(lines)
+
+
+def cmd_fix(args) -> None:
+    c = _client()
+    issue, failing = _resolve_issue(args)
+    if not issue:
+        _die("`codna fix` needs --issue (or --from-junit) describing what's broken.")
+    gh_token = (args.github_token or os.environ.get("CODNA_GITHUB_TOKEN")
+                or os.environ.get("GITHUB_TOKEN"))
+    if args.open_pr:
+        if os.path.isdir(os.path.abspath(os.path.expanduser(args.repo))):
+            _die("--open-pr needs a git URL (a local path has no remote to push to).")
+        if not gh_token:
+            _die("--open-pr needs a write token: pass --github-token or set GITHUB_TOKEN.")
+    print(f"codna: fixing {args.repo} …")
+    t = time.perf_counter()
+    local = os.path.abspath(os.path.expanduser(args.repo))
+    focus_paths = _issue_focus_paths(local, issue) if os.path.isdir(local) else []
+    rid, snap = _register(
+        c,
+        args.repo,
+        args.ref,
+        github_token=gh_token if args.open_pr else None,
+        focus_paths=focus_paths,
+    )
+    sig = {"issue_text": issue, "failing_tests": failing}
+    if focus_paths:
+        sig["changed_files"] = focus_paths
+    try:
+        tri = _dump(c.triage_repository(rid, {"snapshot_id": snap["snapshot_id"], "signals": sig}))
+        plan = _dump(c.create_repository_decision_plan(rid, {
+            "snapshot_id": snap["snapshot_id"],
+            "workspace_evidence_bundle_ref": tri.get("workspace_evidence_bundle_ref"),
+            "signals": sig,
+            "model": args.model,
+        }))
+    except CodnaError:
+        raise
+    except Exception as exc:  # noqa: BLE001
+        if exc.__class__.__module__.startswith("codna."):
+            raise
+        raise CodnaError(f"fix failed: {format_cli_error(exc)}") from exc
+    dt = time.perf_counter() - t
+    dp = plan.get("decision_plan") or {}
+    ra = dp.get("repository_analysis") or {}
+    usage = plan.get("planner_usage") or {}
+    tr = ra.get("token_reduction_metrics") or {}
+    risk = dp.get("risk") or {}
+    cost = usage.get("cost_usd")
+    print(f"\n✓ codna fixed {args.repo} in {dt:.0f}s")
+    print(f"  root cause   : {ra.get('root_cause','?')}")
+    if ra.get("impacted_symbols"):
+        print(f"  symbol       : {', '.join(ra['impacted_symbols'])}  (blast radius: {ra.get('blast_radius','?')})")
+    print(f"  confidence   : {int((dp.get('confidence') or 0)*100)}%"
+          + (f"  ·  regression risk: {int((risk.get('probability_of_loss') or 0)*100)}%" if risk else ""))
+    if tr.get("reduction_ratio"):
+        print(f"  context      : {int(tr.get('raw_repo_token_estimate',0)):,} → "
+              f"{int(tr.get('evidence_bundle_token_count',0)):,} tokens  ({tr['reduction_ratio']:.0f}× smaller)")
+    out_tok, in_tok = usage.get("output_tokens"), usage.get("input_tokens")
+    have_tokens = isinstance(out_tok, (int, float)) and isinstance(in_tok, (int, float))
+    print(f"  agent        : {plan.get('runtime_model','?')} via codna"
+          + (f"  ·  tokens: {int(in_tok):,} in / {int(out_tok):,} out" if have_tokens else "")
+          + (f"  ·  cost: ${cost:.3f}" if cost is not None else ""))
+    pref = ra.get("generated_patch_ref")
+    if not (args.open_pr or args.apply):
+        print(f"  patch        : {pref}   (--apply for a local branch · --open-pr to open a PR)")
+        return
+    # apply requires a simulation id — run the deterministic risk gate first
+    try:
+        sim = _dump(c.simulate_repository(rid, {"snapshot_id": snap["snapshot_id"],
+                                                "decision_plan_id": plan.get("decision_plan_id")}))
+        sid = _sim_id(sim)
+        if not sid:
+            _die(f"no simulation id in simulate() response (keys: {list(sim)[:8]})")
+        if args.open_pr:
+            res = _dump(c.apply_repository(rid, {
+                "mode": "remote_pr", "write_permission": True,
+                "decision_plan_id": plan.get("decision_plan_id"), "simulation_id": sid,
+                **({"base_branch": args.base_branch} if args.base_branch else {}),
+                "pull_request_title": args.pr_title or f"codna: fix {(ra.get('root_cause') or 'bug')[:60]}",
+                "pull_request_body": args.pr_body or _pr_body(issue, ra, plan),
+            }))
+            url = res.get("pull_request_url")
+            print(f"\n✓ opened pull request: {url}" if url
+                  else f"  applied (no PR url): {res.get('status', res)}")
+        else:
+            res = _dump(c.apply_repository(rid, {
+                "mode": "local_branch", "write_permission": True,
+                "decision_plan_id": plan.get("decision_plan_id"), "simulation_id": sid}))
+            print(f"  applied      : branch {res.get('branch_name')} "
+                  f"@ {res.get('local_checkout_path') or res.get('commit_sha')}")
+    except Exception as exc:  # noqa: BLE001
+        raise CodnaError(
+            f"apply failed: {format_cli_error(exc)}"
+            + (f"  (patch ref: {pref})" if pref else "")
+        ) from exc
+
+
+def cmd_secure(args) -> None:
+    """Ingest a scanner's SARIF, prove reachability via the engine, and report which findings
+    are exploitable/reachable and autofix-eligible (Tier-1: read-only, 0 LLM tokens). With
+    --fix/--open-pr, runs the sandboxed worker + PR writer to remediate eligible findings."""
+    from .engine import EngineAdapter, http_post_factory
+    from .policy import Policy
+    from .sarif import ingest_sarif
+
+    if not args.from_sarif:
+        _die("`codna secure` needs --from-sarif <results.sarif>.")
+    if args.open_pr and not args.verification:
+        _die("--open-pr needs --verification <codna-security.yaml> (pinned scanner + build/test commands).")
+    if args.fix and args.engine != "local" and not args.verification:
+        _die("--fix needs --verification <codna-security.yaml> (scanner + build/test commands); "
+             "or use --engine local for a scanner-less local fix.")
+
+    policy = Policy()
+    config_digest = None
+    manifest = None
+    if args.verification:
+        from .manifest import load_manifest, ManifestError
+        manifest = load_manifest(args.verification)
+        policy, config_digest = manifest.policy, manifest.scanner.configuration_digest
+        if args.open_pr:
+            try:
+                manifest.require_resolved_for_pr()
+            except ManifestError as exc:
+                _die(str(exc))
+
+    ingest = ingest_sarif(args.from_sarif)
+    if not ingest.provenance_valid:
+        _die("SARIF provenance incomplete: " + "; ".join(ingest.provenance_errors))
+
+    rid = snap = url = key = None
+    if args.engine == "local":
+        # Bounded, self-hostable reference engine — never claims 'exploitable'.
+        from .refengine import LocalReferenceEngine
+        engine = LocalReferenceEngine()
+    else:
+        c = _client()
+        print(f"codna: understanding {args.repo} for security analysis …")
+        rid, snap = _register(c, args.repo, args.ref)
+        url, key = _engine_url_key()
+        model_pack = os.environ.get("CODNA_MODEL_PACK_DIGEST", "sha256:" + "0" * 64)
+        engine = EngineAdapter(
+            http_post_factory(url, key),
+            repository_id=rid, snapshot_id=snap["snapshot_id"],
+            policy_digest=policy.digest, model_pack_digest=model_pack,
+            configuration_digest=config_digest,
+        )
+
+    from .secure import classify_only
+    report = classify_only(ingest, engine=engine, policy=policy)
+    print(f"\n✓ analyzed {len(report.rows)} finding(s) from {args.from_sarif}")
+    for r in report.rows:
+        mark = "→" if r.eligible else "·"
+        note = "autofix-eligible" if r.eligible else r.reason
+        print(f"  {mark} [{r.classification}] {r.rule_id} ({r.finding_kind})  {note}")
+    counts = ", ".join(f"{k}={v}" for k, v in sorted(report.counts().items()))
+    print(f"  summary: {counts}  ·  autofix-eligible: {report.eligible}")
+
+    if not (args.open_pr or args.fix):
+        return
+    if args.engine == "local":
+        # Self-hosted detect→fix→verify→close via the agentic Cline SDK; report-only.
+        if args.open_pr:
+            _die("--open-pr needs the privilege-separated writer + a scoped token; "
+                 "`--engine local --fix` is report-only (it proves the fix but opens no PR).")
+        _run_local_fix(args, ingest=ingest, engine=engine, policy=policy, manifest=manifest)
+    else:
+        _run_remediation(args, ingest=ingest, rid=rid, snapshot_id=snap["snapshot_id"],
+                         url=url, key=key, policy=policy, manifest=manifest)
+
+
+def _repo_slug(repo_dir: str, override: str | None) -> str:
+    if override:
+        return override
+    import re
+    import subprocess
+    out = subprocess.run(["git", "-C", repo_dir, "remote", "get-url", "origin"],
+                         capture_output=True, text=True).stdout.strip()
+    m = re.search(r"github\.com[:/]([^/]+/[^/.]+)", out)
+    if not m:
+        _die("could not derive owner/repo from the git remote; pass --repo-slug owner/repo.")
+    return m.group(1)
+
+
+class _NoWriter:
+    """Report-only writer for `--fix` (no PR): local tree, never opens anything."""
+
+    def base_unchanged(self, ingest) -> bool:
+        return True
+
+    def open_draft_pr(self, finding, patch, attestation):  # pragma: no cover - never called
+        raise RuntimeError("report-only mode does not open PRs")
+
+
+def _run_local_fix(args, *, ingest, engine, policy, manifest) -> None:
+    """`--engine local --fix`: detect (refengine) → fix (Cline SDK) → verify (manifest
+    build/tests) → re-prove closure (refengine). Report-only; opens no PR."""
+    import os
+
+    from .localfix import run_local_fix
+    from .patchgen import ClinePatchGenerator
+    from .sarif import validate_commit_binding
+
+    repo_dir = os.path.abspath(os.path.expanduser(args.repo))
+    if not os.path.isdir(repo_dir):
+        _die("--fix needs a local repo checkout (pass a local path, not a URL).")
+    commit = validate_commit_binding(ingest)
+    test_cmds = (manifest.build + manifest.tests) if manifest else []
+    model = os.environ.get("CODNA_FIX_MODEL")
+
+    print("\ncodna: remediating eligible findings with the agentic Cline SDK (local engine) …")
+    report = run_local_fix(
+        ingest, engine=engine, patch_generator=ClinePatchGenerator(model=model),
+        repo_dir=repo_dir, commit=commit, policy=policy, test_cmds=test_cmds,
+    )
+
+    print(f"\n✓ local fix: {report.eligible} eligible finding(s) processed")
+    for o in report.outcomes:
+        if not o.eligible:
+            continue
+        if o.remediated:
+            tag = ("tests pass" if o.tests_passed else
+                   "no tests configured" if o.tests_passed is None else "")
+            status = f"REMEDIATED — closure={o.closure}" + (f", {tag}" if tag else "")
+        elif not o.integrity_ok:
+            status = f"blocked: patch integrity ({o.integrity_reason})"
+        elif o.tests_passed is False:
+            status = f"blocked: tests failed (closure={o.closure})"
+        else:
+            status = f"blocked: obligation not closed (closure={o.closure})"
+        print(f"  [{o.classification}] {o.rule_id}  {status}")
+    print(f"  remediated: {len(report.remediated)}/{report.eligible}")
+
+
+def _run_remediation(args, *, ingest, rid, snapshot_id, url, key, policy, manifest) -> None:
+    import os
+
+    from .engine import EngineAdapter, http_post_factory
+    from .evidence import HmacSigner
+    from .patchgen import EnginePatchGenerator
+    from .sarif import validate_commit_binding
+    from .secure import run_secure
+    from .worker import LocalWorker
+    from .writer import GitHubWriter, gh_head_resolver_factory, git_push_create_pr_factory
+
+    repo_dir = os.path.abspath(os.path.expanduser(args.repo))
+    if not os.path.isdir(repo_dir):
+        _die("remediation needs a local repo checkout (pass a local path, not a URL).")
+    commit = validate_commit_binding(ingest)
+    post = http_post_factory(url, key)
+    signer = HmacSigner((os.environ.get("CODNA_ATTESTATION_KEY") or "").encode() or os.urandom(32),
+                        key_id="codna-worker")
+    worker = LocalWorker(
+        repo_dir=repo_dir, commit=commit, manifest=manifest, signer=signer,
+        patch_generator=EnginePatchGenerator(post, repository_id=rid, snapshot_id=snapshot_id),
+        base_env=dict(os.environ),
+    )
+    engine = EngineAdapter(post, repository_id=rid, snapshot_id=snapshot_id,
+                           policy_digest=policy.digest,
+                           model_pack_digest=os.environ.get("CODNA_MODEL_PACK_DIGEST", "sha256:" + "0" * 64),
+                           configuration_digest=manifest.scanner.configuration_digest)
+    if args.open_pr:
+        gh = args.github_token or os.environ.get("CODNA_GITHUB_TOKEN") or os.environ.get("GITHUB_TOKEN")
+        if not gh:
+            _die("--open-pr needs a write token: --github-token or $GITHUB_TOKEN.")
+        slug = _repo_slug(repo_dir, getattr(args, "repo_slug", None))
+        writer = GitHubWriter(trusted_signers={signer.key_id: signer},
+                              create_pr=git_push_create_pr_factory(repo_dir, slug, gh),
+                              head_resolver=gh_head_resolver_factory(slug, gh),
+                              base_branch=args.base_branch or "main")
+    else:
+        writer = _NoWriter()
+
+    try:
+        report = run_secure(ingest, engine=engine, worker=worker, writer=writer,
+                            policy=policy, open_pr=args.open_pr)
+    finally:
+        worker.close()
+
+    print(f"\n✓ remediation: {report.eligible} eligible finding(s) processed")
+    for d in report.decisions:
+        if d.gate is None:
+            continue
+        if d.opened:
+            status = f"opened {d.pr_url}"
+        elif d.gate.should_open_pr:
+            status = "would open (report-only)"
+        else:
+            status = "blocked: " + ",".join(d.gate.failed)
+        print(f"  [{d.classification.value}] {d.canonical_id[:20]}…  {status}")
+
+
+def cmd_secure_open_pr(args) -> None:
+    """Writer domain: verify a worker's signed evidence bundle and open the draft PR. Runs no
+    repository code. Used by the two-job Action so the write token lives only in this step."""
+    import os
+
+    from .evidence import HmacSigner, read_evidence
+    from .findings import NormalizedFinding
+    from .secure import Patch
+    from .writer import GitHubWriter, gh_create_pr_factory, gh_head_resolver_factory
+
+    att, diff, desc = read_evidence(args.evidence)
+    if not desc:
+        _die("evidence is missing finding.json (cannot derive the branch).")
+    key_bytes = (os.environ.get("CODNA_ATTESTATION_KEY") or "").encode()
+    if not key_bytes:
+        _die("set CODNA_ATTESTATION_KEY (shared with the worker) to verify the attestation.")
+    gh = args.github_token or os.environ.get("GITHUB_TOKEN")
+    if not gh:
+        _die("secure-open-pr needs a write token: --github-token or $GITHUB_TOKEN.")
+    if not args.repo_slug:
+        _die("secure-open-pr needs --repo-slug owner/repo.")
+
+    signer = HmacSigner(key_bytes, key_id=att.signer_id)
+    finding = NormalizedFinding.minimal(canonical_id=desc["canonical_id"], rule_id=desc["rule_id"],
+                                        finding_kind=desc["finding_kind"])
+    writer = GitHubWriter(trusted_signers={signer.key_id: signer},
+                          create_pr=gh_create_pr_factory(args.repo_slug, gh),
+                          head_resolver=gh_head_resolver_factory(args.repo_slug, gh),
+                          base_branch=args.base_branch or "main")
+    try:
+        url = writer.open_draft_pr(finding, Patch(att.payload["patch_digest"], diff=diff), att)
+    except Exception as exc:  # noqa: BLE001
+        _die(f"writer refused to open the PR: {exc}")
+    print(f"✓ opened draft PR: {url}")
+
+
+def cmd_mcp(args) -> None:
+    from .mcp_server import main as mcp_main
+    mcp_main()
+
+
+def cmd_doctor(args) -> int:
+    keys = _runtime_keys()
+    try:
+        start_stack = bool(getattr(args, "start_stack", False))
+        stop_stack = bool(getattr(args, "stop_stack", False))
+        if start_stack and stop_stack:
+            _die("--start-stack and --stop-stack are mutually exclusive")
+        if stop_stack:
+            payload = stop_agent_core_runtime(keys=keys)
+            payload["mojo_workers"] = _doctor_mojo_worker_diagnostics(keys)
+            print(json.dumps(payload, indent=2))
+            return 0
+        if start_stack:
+            endpoint = ensure_agent_core_running(keys=keys)
+            payload = inspect_agent_core_runtime(keys=keys)
+            payload["started"] = {
+                "url": endpoint.url,
+                "port": endpoint.port,
+                "runtime_id": endpoint.runtime_id,
+                "pid": endpoint.pid,
+            }
+        else:
+            payload = inspect_agent_core_runtime(keys=keys)
+    except LocalRuntimeError as exc:
+        print(json.dumps(exc.to_dict(), indent=2))
+        return 1
+    payload["mojo_workers"] = _doctor_mojo_worker_diagnostics(keys)
+    print(json.dumps(payload, indent=2))
+    return 0
+
+
+def _doctor_mojo_worker_diagnostics(keys) -> dict[str, object]:
+    try:
+        config = resolve_runtime_config(keys=keys)
+    except RuntimeConfigError as exc:
+        owned_local = {
+            "status": "unavailable",
+            "owned_by_current_runtime": True,
+            "reason": str(exc),
+            "error_code": exc.code,
+            "details": exc.details,
+        }
+    else:
+        return mojo_worker_diagnostics(config)
+    return {
+        "owned_local": owned_local,
+        "legacy_global": legacy_global_mojo_worker_diagnostics(),
+    }
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="codna", description="Codna — understand, fix & secure your repo.")
+    p.add_argument("--version", action="version", version=f"codna {__version__}")
+    sub = p.add_subparsers(dest="cmd")
+
+    pt = sub.add_parser("triage", help="Understand a repo + locate relevant code (fast, deterministic).")
+    pt.add_argument("repo", nargs="?", default=".", help="local path or git URL (default: current dir)")
+    pt.add_argument("--ref", help="branch/tag/commit")
+    pt.add_argument("--issue", help="optional: what you're looking for")
+    pt.set_defaults(func=cmd_triage)
+
+    pf = sub.add_parser("fix", help="Find and fix a bug in a repo.")
+    pf.add_argument("repo", nargs="?", default=".", help="local path or git URL (default: current dir)")
+    pf.add_argument("--issue", required=False, help="what's broken (e.g. the failing test)")
+    pf.add_argument("--failing-test", action="append", help="failing test id (repeatable)")
+    pf.add_argument("--from-junit", help="read failing tests from a JUnit/pytest XML report")
+    pf.add_argument("--ref", help="branch/tag/commit")
+    pf.add_argument("--model", default="repository.verified_agentic_v1",
+                    help="planner model (default: the codna agent planner)")
+    pf.add_argument("--apply", action="store_true", help="apply the patch to a local branch")
+    pf.add_argument("--open-pr", dest="open_pr", action="store_true",
+                    help="push a branch and open a pull request (git URL + write token)")
+    pf.add_argument("--github-token", help="write token for --open-pr (or env GITHUB_TOKEN)")
+    pf.add_argument("--base-branch", help="PR base branch (default: repo default)")
+    pf.add_argument("--pr-title", help="pull request title")
+    pf.add_argument("--pr-body", help="pull request body")
+    pf.set_defaults(func=cmd_fix)
+
+    pd = sub.add_parser("doctor", help="Inspect the owned local Codna runtime and optionally start agent-core.")
+    pd.add_argument("--start-stack", action="store_true", help="Ensure the fixed local agent-core runtime is running.")
+    pd.add_argument("--stop-stack", action="store_true", help="Stop the fixed local agent-core runtime.")
+    pd.set_defaults(func=cmd_doctor)
+
+    ps = sub.add_parser("secure", help="Prove which scanner findings are reachable (ingest SARIF, 0 LLM tokens).")
+    ps.add_argument("repo", nargs="?", default=".", help="local path or git URL (default: current dir)")
+    ps.add_argument("--from-sarif", dest="from_sarif", required=True,
+                    help="path to the scanner's SARIF output (CodeQL/Semgrep/Snyk/Trivy)")
+    ps.add_argument("--ref", help="branch/tag/commit")
+    ps.add_argument("--engine", choices=["remote", "local"], default="remote",
+                    help="reachability engine: 'remote' (decision-engine) or 'local' (bounded self-host reference)")
+    ps.add_argument("--verification", help="codna-security.yaml manifest (required for --open-pr)")
+    ps.add_argument("--open-pr", dest="open_pr", action="store_true",
+                    help="open a fix PR per reachable finding (requires a resolved manifest)")
+    ps.add_argument("--fix", action="store_true", help="remediate eligible findings (report-only, no PR)")
+    ps.add_argument("--github-token", help="write token for --open-pr (or env GITHUB_TOKEN)")
+    ps.add_argument("--base-branch", help="PR base branch (default: repo default)")
+    ps.add_argument("--repo-slug", dest="repo_slug", help="owner/repo for --open-pr (else derived from the git remote)")
+    ps.set_defaults(func=cmd_secure)
+
+    po = sub.add_parser("secure-open-pr", help="Writer domain: verify a signed evidence bundle and open the draft PR.")
+    po.add_argument("--evidence", required=True, help="evidence dir (attestation.json + patch.diff + finding.json)")
+    po.add_argument("--repo-slug", dest="repo_slug", required=True, help="owner/repo")
+    po.add_argument("--github-token", help="write token (or env GITHUB_TOKEN)")
+    po.add_argument("--base-branch", help="PR base branch (default: main)")
+    po.set_defaults(func=cmd_secure_open_pr)
+
+    pm = sub.add_parser("mcp", help="Run codna as an MCP server (Cursor / Claude Desktop).")
+    pm.set_defaults(func=cmd_mcp)
+    return p
+
+
+def main(argv=None) -> int:
+    p = build_parser()
+    args = p.parse_args(argv)
+    if not getattr(args, "func", None):
+        p.print_help()
+        return 0
+    try:
+        result = args.func(args)
+    except Exception as exc:  # noqa: BLE001
+        payload = _structured_error(exc)
+        if payload is None:
+            raise
+        print(json.dumps(payload, indent=2), file=sys.stderr)
+        return 1
+    return int(result) if isinstance(result, int) else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())