mortis-engine 0.1.0__py3-none-any.whl

mortis_engine/__init__.py

@@ -0,0 +1,3 @@
+"""Mortis Engine's local CLI and shared provider transports."""
+
+__version__ = "0.1.0"

mortis_engine/__main__.py

@@ -0,0 +1,3 @@
+from mortis_engine.cli import main
+
+raise SystemExit(main())

mortis_engine/admission.py

@@ -0,0 +1,117 @@
+"""Eight OS-locked request slots per local connection, shared across repositories."""
+
+import asyncio
+import errno
+import hashlib
+import os
+import stat
+import time
+from contextlib import asynccontextmanager
+from pathlib import Path
+from urllib.parse import urlsplit, urlunsplit
+
+from .history import encode, private_directory
+from .llm_http import InferenceError
+
+CAPACITY = 8
+
+
+def connection_key(connection, references=None):
+    """Hash only the destination and nonsecret references, never credential values."""
+    options = connection.get("options", {})
+    parsed = urlsplit(connection.get("base_url", ""))
+    if parsed.username or parsed.password or parsed.query or parsed.fragment:
+        raise ValueError("Provider URLs cannot contain credentials, query parameters, or fragments")
+    host = (parsed.hostname or "").lower()
+    if ":" in host:
+        host = f"[{host}]"
+    port = parsed.port
+    if port and port != {"https": 443, "http": 80}.get(parsed.scheme.lower()):
+        host += f":{port}"
+    destination = urlunsplit((parsed.scheme.lower(), host, parsed.path.rstrip("/"), "", ""))
+    protocol = connection.get("protocol", "").lower()
+    if protocol == "anthropic" and not destination.endswith("/v1"):
+        destination += "/v1"
+    auth_header = options.get("auth_header") or ("x-api-key" if protocol == "anthropic" else "authorization")
+    region, profile = "", ""
+    if protocol == "anthropic-bedrock":
+        region = options.get("aws_region") or os.environ.get("AWS_REGION", "")
+        profile = options.get("aws_profile") or os.environ.get("AWS_PROFILE") or os.environ.get("AWS_DEFAULT_PROFILE", "")
+    value = {"provider": connection.get("provider", "").lower(), "protocol": protocol,
+             "destination": destination, "auth_header": auth_header.lower(),
+             "aws_region": region, "aws_profile": profile,
+             "references": references or {}}
+    return hashlib.sha256(encode(value).encode()).hexdigest()
+
+
+def state_directory(connection):
+    root = Path(os.environ.get("XDG_STATE_HOME") or Path.home() / ".local/state")
+    if not root.is_absolute():
+        raise ValueError("XDG_STATE_HOME must be an absolute path.")
+    key = connection.get("_admission_key") or connection_key(connection)
+    if not isinstance(key, str) or len(key) != 64 or any(char not in "0123456789abcdef" for char in key):
+        raise ValueError("Invalid internal connection admission key.")
+    return private_directory(private_directory(private_directory(root / "mortis") / "admission") / key)
+
+
+def try_slot(directory):
+    for number in range(CAPACITY):
+        path = directory / f"{number}.lock"
+        if path.is_symlink():
+            raise ValueError("Mortis admission requires private regular slot files.")
+        fd = os.open(path, os.O_RDWR | os.O_CREAT | getattr(os, "O_NOFOLLOW", 0), 0o600)
+        try:
+            info = os.fstat(fd)
+            if (not stat.S_ISREG(info.st_mode) or info.st_mode & 0o077 or info.st_nlink != 1
+                    or hasattr(os, "getuid") and info.st_uid != os.getuid()):
+                raise ValueError("Mortis admission requires private regular slot files.")
+            if os.name == "nt":
+                import msvcrt
+
+                if not info.st_size:
+                    os.write(fd, b"0")
+                os.lseek(fd, 0, os.SEEK_SET)
+                msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)
+            else:
+                import fcntl
+
+                fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except OSError as exc:
+            os.close(fd)
+            if exc.errno not in {errno.EACCES, errno.EAGAIN, errno.EDEADLK}:
+                raise
+        except BaseException:
+            os.close(fd)
+            raise
+        else:
+            return fd
+    return None
+
+
+@asynccontextmanager
+async def slot(connection, *, stopped, until, waiting=lambda: None):
+    directory = None
+    notified = False
+    descriptor = None
+    try:
+        while True:
+            if stopped():
+                raise InferenceError("cancelled", "Inference was cancelled while waiting for connection capacity.", consumption_unknown=False)
+            remaining = until - time.monotonic()
+            if remaining <= 0:
+                raise InferenceError("deadline", "The stage deadline expired while waiting for connection capacity.", consumption_unknown=False)
+            directory = directory or state_directory(connection)
+            descriptor = try_slot(directory)
+            if descriptor is not None:
+                break
+            if not notified:
+                notified = True
+                waiting()
+            await asyncio.sleep(min(0.05, remaining))
+        # Recheck after the filesystem operation and before any reservation or dispatch.
+        if stopped() or time.monotonic() >= until:
+            raise InferenceError("cancelled" if stopped() else "deadline", "Inference stopped before dispatch.", consumption_unknown=False)
+        yield
+    finally:
+        if descriptor is not None:
+            os.close(descriptor)

mortis_engine/assessments.py

@@ -0,0 +1,346 @@
+"""Exact-input, candidate-scoped assessment retries without rewriting their origin."""
+
+import asyncio
+import copy
+import hashlib
+import json
+import tempfile
+import time
+from pathlib import Path
+
+from .history import History, encode, private_directory
+from .llm_http import InferenceError
+from .review import context as review_context
+from .review import planning, source, workflows
+from .review.service import credentials_for_history, effective_connection
+from .workflow import Session
+
+INPUT_VERSION = "mortis.assessment-input/v1"
+
+
+def connection_identity(connection):
+    return planning.fingerprint({key: value for key, value in connection.items() if key != "_admission_key"})
+
+
+def _revisions(value):
+    if isinstance(value, dict):
+        for key, child in value.items():
+            if key in {"base_sha", "head_sha", "source_sha", "original_sha", "_settings_sha", "settings_sha", "sha"}:
+                if isinstance(child, str) and len(child) == 40 and all(c in "0123456789abcdef" for c in child):
+                    yield child
+            elif key not in {"inventory", "_graph"}:
+                yield from _revisions(child)
+    elif isinstance(value, list):
+        for child in value:
+            yield from _revisions(child)
+
+
+def _retain(session, repo, env, revisions, value):
+    from .review import file_policy
+
+    cached = getattr(session, "_assessment_objects", {})
+    objects = set()
+    options = value["options"]
+    for sha in revisions:
+        if sha in cached:
+            objects.update(cached[sha])
+            continue
+        retained = set(source.git(repo, env, "rev-list", sha).splitlines())
+        retained.add(source.git(repo, env, "rev-parse", sha + "^{tree}").strip())
+        entries = source.git(repo, env, "ls-tree", "-r", "-t", "-l", "-z", sha).rstrip("\0").split("\0")
+        blobs = {}
+        for entry in filter(None, entries):
+            metadata, path = entry.split("\t", 1)
+            mode, kind, identity, size = metadata.split()
+            if kind == "tree":
+                retained.add(identity)
+            elif mode in {"100644", "100755"} and int(size) <= 1_500_000:
+                blobs[path] = (identity, int(size))
+        allowed = {path for path in blobs if not file_policy.excluded(path, file_policy.policy(options))}
+        if value["workflow_kind"] == "review":
+            allowed &= planning.allowed_context(repo, env, value["base_sha"], value["head_sha"],
+                                                allowed, options, lambda: False)
+        else:
+            allowed &= set(value["context"]["available_paths"])
+        total = 0
+        for path in sorted(allowed):
+            try:
+                source.read_source(repo, env, sha, path)
+            except ValueError:
+                continue
+            total += blobs[path][1]
+            if total > 32_000_000:
+                raise ValueError("Original supporting source exceeds the 32 MB retry retention limit.")
+            retained.add(blobs[path][0])
+        objects.update(retained)
+        cached[sha] = retained
+    directory = private_directory(source._object_cache(session.history.objects) / "pack")
+    source.git(repo, env, "pack-objects", str(directory / "pack"),
+               input_bytes=("\n".join(sorted(objects)) + "\n").encode())
+    session._assessment_objects = cached
+    return sorted(objects)
+
+
+def pin_input(session, candidate_id, kind, candidate, context, options, task_key, repo, env, **evidence):
+    """Persist sanitized input before dispatch; existing records can never be replaced."""
+    from .findings import snapshot
+
+    if kind == "review":
+        options = {**options, "_evidence_policy": options.get("_evidence_policy", planning.EVIDENCE_POLICY)}
+    row = session.history.row(session.run_id)
+    plan = json.loads(row["plan"])
+    value = review_context.sanitize({"schema_version": INPUT_VERSION, "validator_version": 1,
+        "workflow_kind": kind, "candidate": candidate, "context": context, "options": options,
+        "task_key": task_key, "connection": connection_identity(session.connection),
+        "admission_key": session.connection.get("_admission_key"),
+        "triage_versions": plan.get("triage_versions", snapshot(session.history, kind, row["scope"])),
+        **evidence}, session.credentials)
+    revisions = sorted(set(_revisions(value)))
+    try:
+        value["retained_objects"] = _retain(session, repo, env, revisions, value)
+    except (ValueError, TimeoutError, OSError) as exc:
+        value["retry_blocked_reason"] = review_context.sanitize(str(exc), session.credentials)
+    value["revisions"] = revisions
+    session.history.save_assessment_input(session.run_id, candidate_id, value)
+
+
+def _children(history, parent, candidate):
+    result = []
+    for row in history.db.execute("SELECT * FROM runs WHERE kind='assessment' ORDER BY started, id"):
+        plan = json.loads(row["plan"])
+        if plan.get("parent_run_id") == parent and plan.get("candidate_id") == candidate:
+            result.append(row)
+    return result
+
+
+def _unknown(history, parent, value, children):
+    kind = value["workflow_kind"]
+    stage = "assessment" if kind == "review" else "security_assessment"
+    for (record_stage, key), (_, row, _) in history.attempts(parent).items():
+        relevant = (record_stage.startswith("security_") if kind == "scan" else
+                    record_stage == stage and (key == value["task_key"] or key.startswith(value["task_key"] + ":")))
+        if relevant and row.get("consumption_unknown"):
+            return True
+    return any(record.get("consumption_unknown") for child in children
+               for _, record, _ in history.attempts(child["id"]).values())
+
+
+def _eligibility(history, origin, candidate, value, children):
+    if candidate.get("status") != "failed":
+        return "Only failed assessments can be retried."
+    if value is None:
+        return "This run predates retry support or has no exact saved assessment evidence."
+    if value.get("schema_version") != INPUT_VERSION or value.get("validator_version") != 1:
+        return "The saved assessment input or validator version is incompatible."
+    if value.get("retry_blocked_reason"):
+        return value["retry_blocked_reason"]
+    if origin["report"] is None:
+        return "Resume the original run before retrying its failed assessment."
+    if _unknown(history, origin["id"], value, children):
+        return "Unknown token consumption in this assessment lineage blocks retry."
+    if any(child["report"] is None for child in children):
+        return "An unfinished assessment retry exists; resume it using its run ID."
+    from .findings import snapshot
+    if snapshot(history, origin["kind"], origin["scope"]) != value["triage_versions"]:
+        return "Finding decisions changed since the assessment was pinned; its history is stale."
+    return None
+
+
+def _candidates(history, run_id):
+    origin = history.row(run_id)
+    if origin["kind"] not in {"review", "scan"}:
+        raise ValueError("Choose a review or security scan run.")
+    report = json.loads(origin["report"]) if origin["report"] else {}
+    return origin, report.get("candidates", [])
+
+
+def _validate_evidence(repo, env, value):
+    try:
+        for sha in value["revisions"]:
+            source.resolve_commit(repo, env, sha)
+            source.git(repo, env, "cat-file", "-e", sha + "^{tree}")
+        checked = source.git(repo, env, "cat-file", "--batch-check",
+                             input_bytes=("\n".join(value["retained_objects"]) + "\n").encode())
+        if any(line.endswith(" missing") for line in checked.splitlines()):
+            raise ValueError("Missing retained object")
+    except (KeyError, ValueError) as exc:
+        raise ValueError("Exact original assessment evidence is unavailable; retry was withheld.") from exc
+
+
+def list_assessments(repository, *, run_id):
+    """List candidates and retry blockers without loading connection credentials."""
+    with History(repository) as history:
+        origin, candidates = _candidates(history, run_id)
+        inputs = history.assessment_inputs(run_id)
+        rows = []
+        for candidate in candidates:
+            children = _children(history, run_id, candidate["id"])
+            success = next((json.loads(row["report"]) for row in children if row["report"]
+                            and json.loads(row["report"]).get("status") == "completed"), None)
+            reason = _eligibility(history, origin, candidate, inputs.get(candidate["id"]), children)
+            if success:
+                reason = "A successful retry is already saved; assess returns it without dispatch."
+            elif reason is None:
+                try:
+                    with source.local_repository(repository, object_cache=history.objects) as (repo, env):
+                        _validate_evidence(repo, env, inputs[candidate["id"]])
+                except (ValueError, OSError) as exc:
+                    reason = str(exc)
+            rows.append({"candidate_id": candidate["id"], "path": candidate["snapshot"].get("path"),
+                "status": candidate["status"], "error": candidate.get("error"),
+                "retry_eligible": reason is None, "blocked_reason": reason,
+                "retry_run_id": success["run_id"] if success else children[-1]["id"] if children else None})
+        if origin["kind"] == "scan" and not candidates and report_has_legacy_failures(origin):
+            return {"schema_version": "mortis.assessments/v1", "run_id": run_id, "candidates": [],
+                    "blocked_reason": "This scan predates durable assessment candidates and retry support."}
+        return {"schema_version": "mortis.assessments/v1", "run_id": run_id, "candidates": rows}
+
+
+def report_has_legacy_failures(origin):
+    report = json.loads(origin["report"]) if origin["report"] else {}
+    return any(unit.get("task", "").startswith("assessment:") and unit.get("status") == "failed"
+               for unit in report.get("coverage", {}).get("units", []))
+
+
+def _lineage_usage(history, parent, value, children):
+    records = []
+    for run_id in [parent, *(child["id"] for child in children)]:
+        for (stage, key), (_, record, _) in history.attempts(run_id).items():
+            if run_id == parent and not (stage == ("assessment" if value["workflow_kind"] == "review" else "security_assessment")
+                                         and (key == value["task_key"] or key.startswith(value["task_key"] + ":"))):
+                continue
+            records.append({"run_id": run_id, **record})
+    charge = sum(Session.charge(record) for record in records)
+    return {"requests": records, "reserved_tokens": charge,
+            "total_tokens": None if any(row["consumption_unknown"] for row in records) else charge}
+
+
+def _finding(value, candidate_id, result):
+    if result["verdict"] != "confirmed":
+        return None
+    candidate = copy.deepcopy(value["candidate"])
+    if value["workflow_kind"] == "review":
+        identity = result["finding_id"] or "finding-" + candidate_id.removeprefix("candidate-")
+        old = next((old for old in value["context"].get("history", []) if old["id"] == identity), None)
+        if not result["suggestion_supported"]:
+            candidate["suggestion_code"] = ""
+        return {**candidate, "id": identity, "assessment": result, "status": old["status"] if old else "open"}
+    from .security import digest
+    from .security_scans.service import observe
+    fingerprint = digest(json.dumps(["code", candidate["path"], candidate["category"],
+                                     candidate["evidence"][0]["quote"], candidate["title"]]))
+    identity = result["finding_id"] or fingerprint[:32]
+    old = next((old for old in value["context"].get("history", []) if old["id"] == identity), None)
+    evidence = {**candidate, "kind": "code", "source_sha": value["head_sha"],
+                "source_hash": value["redaction"]["inventory"][candidate["path"]]["hash"],
+                "fingerprint": fingerprint, "assessment": result, "sources": ["mortis"]}
+    return observe(evidence, old)
+
+
+async def _execute(repository, repo, env, value, session):
+    options = value["options"]
+    if value["workflow_kind"] == "review":
+        options = {**options, "_evidence_policy": planning.saved_evidence_policy(options)}
+        report = {"base_sha": value["base_sha"], "head_sha": value["head_sha"]}
+        return await workflows._assess(repo, env, workflows._run(report, options, session),
+                                       value["candidate"], {}, session, pinned_context=value["context"])
+    from .review import file_policy
+    from .security_scans import engine, inference
+    from .security_scans.scanner import identity_key
+    with tempfile.TemporaryDirectory(prefix="mortis-assessment-") as temporary:
+        item = engine.Snapshot(Path(temporary), value["head_sha"], env, lambda: False,
+                               git=repo, key=identity_key(create=False))
+        item.repository = Path(repository).resolve()
+        item.policy = file_policy.policy(options)
+        item.inventory = value["redaction"]["inventory"]
+        item.secret_rules = value["redaction"]["secret_rules"]
+        item.secret_lines = value["redaction"]["secret_lines"]
+        item.deadline = session.deadline
+        result, _ = await inference.ask(item, session, "assessment", value["context"], value["task_key"],
+                                        options, prepared=True)
+        return result
+
+
+def retry_assessment(repository, *, run_id=None, candidate_id=None, resume=None,
+                     connection, get_credentials, profile=None, progress=lambda value: None):
+    """Retry one failed candidate against pinned inputs, under a durable candidate claim."""
+    if resume and (run_id or candidate_id):
+        raise ValueError("--resume uses the parent and candidate of the saved retry.")
+    with History(repository) as history:
+        if resume:
+            retry = history.row(resume, "assessment")
+            saved = json.loads(retry["plan"])
+            run_id, candidate_id = saved["parent_run_id"], saved["candidate_id"]
+        elif not run_id or not candidate_id:
+            raise ValueError("Assessment retry requires a run ID and candidate ID.")
+        claim = hashlib.sha256(encode([run_id, candidate_id]).encode()).hexdigest()[:32]
+        with history.claim(claim):
+            origin, candidates = _candidates(history, run_id)
+            candidate = next((item for item in candidates if item["id"] == candidate_id), None)
+            if candidate is None:
+                raise ValueError("No saved assessment candidate with that ID; this run may predate retry support.")
+            children = _children(history, run_id, candidate_id)
+            success = next((json.loads(row["report"]) for row in children if row["report"]
+                            and json.loads(row["report"]).get("status") == "completed"), None)
+            if success:
+                return success
+            if resume and retry["report"]:
+                return json.loads(retry["report"])
+            value = history.assessment_input(run_id, candidate_id)
+            reason = _eligibility(history, origin, candidate, value,
+                                  [child for child in children if child["id"] != resume])
+            if reason:
+                raise ValueError(reason)
+            if _unknown(history, run_id, value, children):
+                raise ValueError("Unknown token consumption in this assessment lineage blocks retry.")
+            connection = effective_connection(connection, value["options"])
+            if (connection_identity(connection) != value["connection"]
+                    or connection.get("_admission_key") != value.get("admission_key")):
+                raise ValueError("The selected connection changed since the original assessment.")
+            if resume and saved["input"] != planning.fingerprint(value):
+                raise ValueError("The retry's saved assessment input changed.")
+            # Validate retained revisions before credentials or provider-client initialization.
+            with source.local_repository(repository, object_cache=history.objects) as (repo, env):
+                _validate_evidence(repo, env, value)
+                if value["workflow_kind"] == "scan":
+                    from .security_scans import engine
+                    from .security_scans.scanner import identity_key
+                    if engine.secure_digest("assessment-redaction-key", identity_key(create=False)) != value["redaction"]["key_check"]:
+                        raise ValueError("The original security redaction key changed; retry was withheld.")
+                credentials = credentials_for_history(history, get_credentials)
+                if review_context.sanitize(value["context"], credentials) != value["context"]:
+                    raise ValueError("The original evidence no longer matches safe redaction; retry was withheld.")
+                child_id = resume or history.begin("assessment", origin["scope"], {
+                    "parent_run_id": run_id, "candidate_id": candidate_id, "profile": profile,
+                    "input": planning.fingerprint(value)})
+                timeout = value["options"].get("timeout_seconds")
+                deadline = time.monotonic() + timeout if timeout else None
+                session = Session(connection, credentials, history=history, run_id=child_id,
+                                  deadline=deadline, progress=progress)
+                progress({"phase": "assessment"})
+
+                async def execute():
+                    async with session:
+                        return await _execute(repository, repo, env, value, session)
+
+                try:
+                    result = asyncio.run(execute())
+                    status, error = "completed", None
+                except (ValueError, OSError, InferenceError) as exc:
+                    result, status = None, "failed"
+                    error = review_context.sanitize(str(exc), credentials)
+                from .findings import snapshot
+                if snapshot(history, origin["kind"], origin["scope"]) != value["triage_versions"]:
+                    status = "failed"
+                    error = "Finding decisions changed while retrying; the saved result cannot update newer history."
+                children = _children(history, run_id, candidate_id)
+                report = {"schema_version": "mortis.assessment/v1", "run_id": child_id,
+                    "parent_run_id": run_id, "candidate_id": candidate_id, "workflow_kind": origin["kind"],
+                    "status": status, "result": result,
+                    "finding": _finding(value, candidate_id, result) if result and status == "completed" else None,
+                    "head_sha": value["head_sha"], "model": connection["model"], "provider": connection["provider"],
+                    "usage": session.usage(), "lineage_usage": _lineage_usage(history, run_id, value, children)}
+                if error:
+                    report["error"] = error
+                history.finish(child_id, report)
+                return report

mortis_engine/cli/__init__.py

@@ -0,0 +1,39 @@
+"""Command-line entry point for Mortis Engine."""
+
+import argparse
+import sys
+
+from keyring.errors import KeyringError
+from pydantic import ValidationError
+
+from mortis_engine import __version__
+from mortis_engine.llm_http import InferenceError
+
+from . import analysis, config, connect, findings, followups, reports, review
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog="mortis", description="Review local Git changes with your AI connection.")
+    parser.add_argument("--version", action="version", version=f"mortis {__version__}")
+    commands = parser.add_subparsers(dest="command", required=True)
+    connect.add_parser(commands)
+    review.add_parser(commands)
+    config.add_parser(commands)
+    analysis.add_parser(commands)
+    findings.add_parser(commands)
+    followups.add_parser(commands)
+    reports.add_parser(commands)
+    args = parser.parse_args(argv)
+    try:
+        return args.run(args) or 0
+    except ValidationError as exc:
+        errors = [".".join(map(str, error["loc"])) + ": " + error["msg"] for error in exc.errors(include_input=False)]
+        print("Invalid configuration. " + "; ".join(errors), file=sys.stderr)
+    except KeyringError:
+        print("The OS credential vault could not be accessed. Use environment variable references or unlock the vault.", file=sys.stderr)
+    except (ValueError, OSError, InferenceError) as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+    except (KeyboardInterrupt, EOFError):
+        print("Command cancelled.", file=sys.stderr)
+        return 130
+    return 1

mortis_engine/cli/analysis.py

@@ -0,0 +1,113 @@
+"""Terminal commands for saved runs and local repository workflows."""
+
+import json
+import sys
+import time
+
+from mortis_engine import config, operations
+from mortis_engine.history import History
+from mortis_engine.review import settings
+
+from .reports import destinations, output_options, write_outputs
+from .review import execution_options, limit_overrides, options, progress_display, selected, terminal
+
+
+def run(args):
+    if args.command != "scan":
+        return _run(args)
+    started = time.monotonic()
+    try:
+        return _run(args)
+    finally:
+        print(f"Elapsed: {time.monotonic() - started:.1f}s", file=sys.stderr, flush=True)
+
+
+def _run(args):
+    outputs = destinations(args.output) if args.command == "scan" else []
+    overrides = limit_overrides(args)
+    settings.apply_overrides({}, overrides, scan=args.command == "scan")
+    if args.resume and (getattr(args, "ref", None) or args.effort or getattr(args, "run_id", None)
+                        or getattr(args, "rotations", None) or getattr(args, "concurrency", None) is not None or overrides):
+        raise ValueError("--resume uses the inputs and options of the saved run.")
+    if args.command in {"verify", "summary"} and not (args.run_id or args.resume):
+        raise ValueError(f"mortis {args.command} requires --run RUN_ID. Use mortis runs to see the available IDs.")
+    name, profile = selected(args)
+    with progress_display(getattr(args, "progress", False), scan=True) as progress:
+        result = operations.run(args.repo, kind=args.command, connection=config.connection(name, profile),
+            get_credentials=lambda: config.credentials(profile), profile=name, ref=getattr(args, "ref", None) or "HEAD",
+            finding_run=getattr(args, "run_id", None), resume=args.resume, effort=args.effort,
+            rotations=getattr(args, "rotations", ()), concurrency=getattr(args, "concurrency", None), progress=progress,
+            overrides=overrides)
+    write_outputs(result, outputs)
+    if args.format == "json":
+        print(json.dumps(result, indent=2))
+    else:
+        lines = [f"{args.command.capitalize()} {result['status']}  {result['head_sha'][:12]}", f"Run: {result['run_id']}"]
+        if args.command == "scan":
+            coverage = result["coverage"]
+            lines.append(f"Coverage: {coverage['completed_files']}/{coverage['selected_files']} files. Grade: {result['grade'] or 'unavailable'}")
+            lines.extend(f"[{r['severity']}] {r['path']} — {r['title']} ({r['outcome']}, {r['id']})" for r in result["findings"])
+            lines.extend(result["problems"])
+            if error := result["stages"]["trivy"].get("error"):
+                lines.append(error)
+        elif args.command == "verify":
+            lines.extend(f"{r['finding_id']} — {r['verdict']}: " + ((r.get("result") or {}).get("explanation") or r.get("error", ""))
+                         for r in result["verifications"])
+        elif args.command == "summary":
+            lines.append(result["result"]["narrative"])
+            lines.extend(f"{g['title']} — {g['description']} ({', '.join(g['paths'])})" for g in result["result"]["groups"])
+            if result["result"].get("diagram"):
+                from mortis_engine.review.summary import diagram_section
+                lines.append(diagram_section(result["result"]["diagram"]))
+        else:
+            lines.append(result["background"])
+        print(terminal("\n".join(lines)))
+    return 0 if result["status"] == "completed" else 2 if result["status"] == "partial" else 1
+
+
+def runs(args):
+    with History(args.repo) as history:
+        if args.id:
+            row = history.row(args.id)
+            if row["report"] is None:
+                records = [record for _, record, _ in history.attempts(args.id).values()]
+                value = {"run_id": args.id, "status": "unfinished", "attempts": records}
+            else:
+                value = history.report(args.id)
+            print(json.dumps(value, indent=2))
+        else:
+            rows = history.list()
+            print(terminal("\n".join(f"{r['id']}  {r['kind']}  {r['scope']}  " +
+                ("finished" if r["finished"] else "unfinished") for r in rows)) or "No saved runs.")
+
+
+def build_graph(args):
+    from mortis_engine.code_graph.build import main
+
+    return main([])
+
+
+def add_parser(commands):
+    graph = commands.add_parser("graph", help="Manage the isolated local source parser")
+    build = graph.add_subparsers(dest="action", required=True).add_parser("build", help="Build the local Docker parser image")
+    build.set_defaults(run=build_graph)
+    for command, description in (("scan", "Scan a local revision with Trivy and your AI connection"),
+                                 ("verify", "Check saved findings against a local revision"),
+                                 ("summary", "Generate a summary for a saved review"),
+                                 ("background", "Generate repository background from a pinned revision")):
+        parser = commands.add_parser(command, help=description)
+        options(parser, kind=command)
+        if command == "scan":
+            execution_options(parser)
+            output_options(parser)
+            parser.add_argument("--acknowledge-rotation", metavar="FINDING_ID", dest="rotations", action="append",
+                                default=[], help="Record that this retained secret has been rotated or revoked")
+        if command != "summary":
+            parser.add_argument("--ref", help="Local branch, tag or commit (default: HEAD)")
+        if command in {"summary", "verify"}:
+            parser.add_argument("--run", dest="run_id", help="Saved review ID from mortis runs")
+        parser.set_defaults(run=run)
+    parser = commands.add_parser("runs", help="List saved local runs or print a saved report")
+    parser.add_argument("id", nargs="?", help="Print the report or progress for this run")
+    parser.add_argument("--repo", default=".")
+    parser.set_defaults(run=runs)