gitpro 0.3.1__py3-none-any.whl

gitpro/operation_contract.py

@@ -0,0 +1,178 @@
+"""Version 1 of the agent operation contract; no shell commands or arbitrary environment input."""
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+VERSION = 1
+MAX_REQUEST = 131072
+DECISIONS = ("ready", "blocked", "needs_input", "needs_approval", "indeterminate")
+FIELDS = {
+    "commit": ("message", "author_name", "author_email"),
+    "push": ("remote", "branch"),
+    "pr-create": ("remote", "base", "head", "title", "body", "draft"),
+}
+REQUIRED = {
+    "commit": ("message",),
+    "push": ("remote", "branch"),
+    "pr-create": ("remote", "base", "head", "title", "body"),
+}
+TEXT = {"type": "string", "minLength": 1, "maxLength": 65536}
+REQUEST_SCHEMA = {
+    "type": "object", "additionalProperties": False,
+    "required": ["version", "operation", "repo"],
+    "properties": {
+        "version": {"type": "integer", "enum": [VERSION]},
+        "operation": {"type": "string", "enum": list(FIELDS)},
+        "repo": {**TEXT, "description": "Absolute path to a worktree; never inferred from the server cwd."},
+        **{key: dict(TEXT) for key in sorted(set(sum(FIELDS.values(), ()))) if key not in ("draft", "body")},
+        "body": {"type": "string", "maxLength": 65536}, "draft": {"type": "boolean"},
+    },
+    "oneOf": [
+        {"properties": {"operation": {"const": op}},
+         "required": list(REQUIRED[op]),
+         "not": {"anyOf": [{"required": [key]} for key in sorted(set(sum(FIELDS.values(), ())) - set(fields))]}}
+        for op, fields in FIELDS.items()
+    ],
+    "dependentRequired": {"author_name": ["author_email"], "author_email": ["author_name"]},
+}
+RESULT_SCHEMA = {
+    "type": "object", "additionalProperties": False,
+    "required": ["version", "command", "ok", "decision", "problems"],
+    "properties": {
+        "version": {"const": VERSION}, "command": {"enum": ["preflight", "run", "operation-status"]},
+        "ok": {"type": "boolean"}, "decision": {"enum": list(DECISIONS)},
+        "problems": {"type": "array", "items": {
+            "type": "object", "required": ["code", "message", "decision"],
+            "properties": {"code": TEXT, "message": TEXT, "decision": {"enum": list(DECISIONS)},
+                           "action": {"type": "object", "required": ["kind", "argv"],
+                                      "properties": {"kind": {"enum": ["inspect", "request_approval"]},
+                                                     "argv": {"type": ["array", "null"],
+                                                              "items": {"type": "string"}}}}},
+        }},
+        "operation": {"enum": [*FIELDS, None]}, "repo": {"type": ["string", "null"]},
+        "plan_token": {"type": ["string", "null"], "pattern": "^[0-9a-f]{64}$"},
+        "status": {"enum": ["succeeded", "failed", "blocked", "indeterminate"]},
+        "replayed": {"type": "boolean"}, "idempotency_key": {"type": "string"},
+        "outcome": {"type": "object", "additionalProperties": False,
+                    "properties": {"commit": TEXT, "tree": TEXT, "remote_oid": TEXT, "pr_url": TEXT,
+                                   "already_present": {"type": "boolean"}}},
+        "checks": {"type": "array", "items": {
+            "type": "object", "required": ["code", "status", "message"],
+            "properties": {"code": TEXT, "status": {"enum": ["pass", "fail", "unknown", "skip"]},
+                           "message": TEXT}}},
+        "identity": {"type": "object", "required": ["id", "name", "email", "sign", "ssh_key", "account"],
+                     "properties": {"id": TEXT, "name": {"type": ["string", "null"]},
+                                    "email": {"type": ["string", "null"]}, "sign": {"type": "boolean"},
+                                    "ssh_key": {"type": ["string", "null"]},
+                                    "account": {"type": ["object", "null"],
+                                                "required": ["host", "cli", "login"],
+                                                "properties": {"host": TEXT, "cli": {"const": "gh"},
+                                                               "login": TEXT}}}},
+        "destination": {"type": ["string", "null"]}, "head": {"type": ["string", "null"]},
+        "effects": {"type": "object", "required": ["persistent_configuration", "network", "child_identity_isolated"],
+                    "properties": {"persistent_configuration": {"const": False}, "network": {"type": "boolean"},
+                                   "child_identity_isolated": {"const": True}}},
+        "authorization": TEXT,
+    },
+}
+
+
+class OperationError(Exception):
+    def __init__(self, code: str, message: str, decision: str = "indeterminate") -> None:
+        super().__init__(message)
+        self.code, self.decision = code, decision
+
+    def problem(self) -> dict:
+        return {"code": self.code, "message": str(self), "decision": self.decision}
+
+
+def digest(value: object) -> str:
+    return hashlib.sha256(json.dumps(value, sort_keys=True, separators=(",", ":"),
+                                     ensure_ascii=True, default=str).encode()).hexdigest()
+
+
+def unique_members(pairs: list[tuple[str, object]]) -> dict[str, object]:
+    out: dict[str, object] = {}
+    for key, value in pairs:
+        if key in out:
+            raise OperationError("invalid_request", "Duplicate JSON member.", "needs_input")
+        out[key] = value
+    return out
+
+
+def decode(text: str, *, limit: int = MAX_REQUEST) -> object:
+    if len(text.encode("utf-8")) > limit:
+        raise OperationError("invalid_request", f"Request exceeds {limit // 1024} KiB.", "needs_input")
+    try:
+        return json.loads(text, object_pairs_hook=unique_members)
+    except (ValueError, RecursionError):
+        raise OperationError("invalid_request", "Request must be a JSON object.", "needs_input") from None
+
+
+@dataclass(frozen=True)
+class Request:
+    operation: str
+    repo: Path
+    values: dict
+
+    @classmethod
+    def parse(cls, raw: object) -> Request:
+        if not isinstance(raw, dict):
+            raise OperationError("invalid_request", "Request must be an object.", "needs_input")
+        if type(raw.get("version")) is not int or raw["version"] != VERSION:
+            raise OperationError("unsupported_version", "Request version must be 1.", "needs_input")
+        op = raw.get("operation")
+        if not isinstance(op, str) or op not in FIELDS:
+            raise OperationError("unsupported_operation", "Use commit, push or pr-create.", "needs_input")
+        if set(raw) - {"version", "operation", "repo", *FIELDS[op]}:
+            raise OperationError("invalid_request", "Unknown or inapplicable request field.", "needs_input")
+        for key in ("repo", *REQUIRED[op]):
+            if key not in raw:
+                raise OperationError("missing_input", f"Supply {key}.", "needs_input")
+        for key, value in raw.items():
+            if key in ("version", "operation"):
+                continue
+            if key == "draft":
+                if type(value) is not bool:
+                    raise OperationError("invalid_request", "draft must be boolean.", "needs_input")
+            elif not isinstance(value, str) or "\0" in value or len(value) > 65536 or (not value.strip() and key != "body"):
+                raise OperationError("invalid_request", f"Invalid {key}.", "needs_input")
+        if len(json.dumps(raw, ensure_ascii=False).encode("utf-8")) > MAX_REQUEST:
+            raise OperationError("invalid_request", "Request exceeds 128 KiB.", "needs_input")
+        if ("author_name" in raw) != ("author_email" in raw):
+            raise OperationError("missing_input", "Supply both author_name and author_email.", "needs_input")
+        for key in ("author_name", "author_email", "remote", "branch", "base", "head", "title"):
+            if key in raw and (any(ord(c) < 32 or ord(c) == 127 for c in raw[key]) or
+                               (key != "title" and raw[key].startswith("-"))):
+                raise OperationError("invalid_request", f"Invalid {key}.", "needs_input")
+        repo = Path(raw["repo"])
+        if not repo.is_absolute():
+            raise OperationError("invalid_request", "repo must be an absolute path.", "needs_input")
+        values = dict(raw, repo=str(repo.resolve()))
+        if op == "pr-create":
+            values.setdefault("draft", False)
+        return cls(op, repo.resolve(), values)
+
+    @property
+    def fingerprint(self) -> str:
+        return digest(self.values)
+
+
+def request_key(value: str) -> str:
+    if not isinstance(value, str) or not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._:-]{0,127}", value):
+        raise OperationError("invalid_key", "Use a 1-128 character alphanumeric idempotency key (._:- allowed).",
+                             "needs_input")
+    return value
+
+
+def failure(command: str, error: OperationError, request: Optional[Request] = None) -> dict:
+    return {"version": VERSION, "command": command, "ok": False, "decision": error.decision,
+            "operation": request.operation if request else None, "repo": str(request.repo) if request else None,
+            "problems": [error.problem()],
+            **({"status": "indeterminate" if error.decision == "indeterminate" else "blocked"}
+               if command == "run" else {})}

gitpro/operation_io.py

@@ -0,0 +1,256 @@
+"""Bounded child processes and durable, cooperative operation serialization (Linux/macOS)."""
+from __future__ import annotations
+
+import contextlib
+import fcntl
+import hashlib
+import json
+import os
+import signal
+import sqlite3
+import subprocess
+import tempfile
+import threading
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict, Iterator, Optional, Sequence
+from types import FrameType
+
+from .operation_contract import OperationError, digest
+
+MAX_OUTPUT = 1024 * 1024
+TIMEOUT = 30
+GRACE = 2
+
+
+@contextlib.contextmanager
+def termination_signals() -> Iterator[None]:
+    """Let a CLI/MCP SIGTERM unwind locks and stop the active child, like Ctrl-C."""
+    if threading.current_thread() is not threading.main_thread():
+        yield
+        return
+
+    def terminate(signum: int, frame: Optional[FrameType]) -> None:
+        raise KeyboardInterrupt
+
+    old = signal.signal(signal.SIGTERM, terminate)
+    try:
+        yield
+    finally:
+        signal.signal(signal.SIGTERM, old)
+
+
+@dataclass(frozen=True)
+class Process:
+    code: int
+    out: str
+    err: str
+    stopped: Optional[str] = None
+
+
+def _signal_group(pid: int, sig: int) -> None:
+    try:
+        os.killpg(pid, sig)
+    except ProcessLookupError:
+        pass
+
+
+def process(argv: Sequence[str], repo: Path, env: Dict[str, str], *,
+            text: Optional[str] = None, timeout: float = TIMEOUT) -> Process:
+    """No inherited stdin, shell, or unbounded pipe buffers; output is never logged here."""
+    with tempfile.TemporaryFile() as inp, tempfile.TemporaryFile() as out, tempfile.TemporaryFile() as err:
+        if text is not None:
+            inp.write(text.encode("utf-8"))
+            inp.seek(0)
+        child = subprocess.Popen(list(argv), cwd=repo, env=env, stdin=inp, stdout=out, stderr=err,
+                                 start_new_session=True)
+        stopped = None
+        deadline = time.monotonic() + timeout
+        try:
+            while child.poll() is None:
+                if os.fstat(out.fileno()).st_size + os.fstat(err.fileno()).st_size > MAX_OUTPUT:
+                    stopped = "output_limit"
+                    break
+                if time.monotonic() >= deadline:
+                    stopped = "timeout"
+                    break
+                time.sleep(0.02)
+        except KeyboardInterrupt:
+            stopped = "cancelled"
+        finally:
+            if stopped or child.poll() is None:
+                _signal_group(child.pid, signal.SIGTERM)
+                try:
+                    child.wait(timeout=GRACE)
+                except subprocess.TimeoutExpired:
+                    pass
+            # A hook/helper may outlive its leader. Never leave it running after this operation.
+            _signal_group(child.pid, signal.SIGKILL)
+            child.wait()
+        if os.fstat(out.fileno()).st_size + os.fstat(err.fileno()).st_size > MAX_OUTPUT:
+            stopped = stopped or "output_limit"
+        out.seek(0)
+        err.seek(0)
+        return Process(child.returncode, out.read(MAX_OUTPUT).decode("utf-8", "replace"),
+                       err.read(MAX_OUTPUT).decode("utf-8", "replace"), stopped)
+
+
+def file_hash(path: Path) -> Optional[str]:
+    try:
+        return hashlib.sha256(path.read_bytes()).hexdigest()
+    except FileNotFoundError:
+        return None
+
+
+def state_dir() -> Path:
+    base = Path(os.environ.get("XDG_STATE_HOME") or Path.home() / ".local" / "state")
+    if not base.is_absolute():
+        raise OperationError("invalid_state_path", "XDG_STATE_HOME must be an absolute path; "
+                             "no operation state was opened or created.", "needs_input")
+    return base / "gitpro" / "operations"
+
+
+def sync_path(path: Path, *, directory: bool = False) -> None:
+    fd = os.open(path, os.O_RDONLY | os.O_NOFOLLOW | (os.O_DIRECTORY if directory else 0))
+    try:
+        os.fsync(fd)
+    finally:
+        os.close(fd)
+
+
+def _private_dir(path: Path) -> None:
+    path.mkdir(mode=0o700, parents=True, exist_ok=True)
+    st = path.lstat()
+    if path.is_symlink() or st.st_uid != os.getuid() or st.st_mode & 0o077:
+        raise OperationError("unsafe_state", "The operation state directory must be owned by you and mode 0700.")
+
+
+@contextlib.contextmanager
+def repository_lock(common: Path) -> Iterator[None]:
+    with state_lock(digest(str(common.resolve()))):
+        yield
+
+
+@contextlib.contextmanager
+def configuration_lock(*, exclusive: bool = False) -> Iterator[None]:
+    """Shared during scoped execution; exclusive during approved configuration changes."""
+    with state_lock("configuration", shared=not exclusive):
+        yield
+
+
+@contextlib.contextmanager
+def state_lock(name: str, *, shared: bool = False) -> Iterator[None]:
+    root = state_dir()
+    _private_dir(root)
+    path = root / (name + ".lock")
+    fd = os.open(path, os.O_CREAT | os.O_RDWR | os.O_NOFOLLOW, 0o600)
+    try:
+        try:
+            fcntl.flock(fd, (fcntl.LOCK_SH if shared else fcntl.LOCK_EX) | fcntl.LOCK_NB)
+        except BlockingIOError:
+            raise OperationError("operation_busy", "Another gitpro operation holds the required lock.",
+                                 "blocked") from None
+        yield
+    finally:
+        os.close(fd)  # Do not unlink: waiting callers must continue to lock the same inode.
+
+
+@contextlib.contextmanager
+def locked_index(index: Path, expected_hash: Optional[str]) -> Iterator[Path]:
+    """Freeze the ordinary index; Git and its hooks operate on a private copy."""
+    lock = index.with_name(index.name + ".lock")
+    try:
+        fd = os.open(lock, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o600)
+    except FileExistsError:
+        raise OperationError("index_busy", "Git's index is locked; no operation was started.") from None
+    st = os.fstat(fd)
+    os.close(fd)
+    try:
+        if file_hash(index) != expected_hash:
+            raise OperationError("stale_plan", "The staged index changed; run preflight again.", "blocked")
+        with tempfile.TemporaryDirectory(prefix="gitpro-index-") as tmp:
+            private = Path(tmp) / "index"
+            if index.exists():
+                private.write_bytes(index.read_bytes())
+            yield private
+    finally:
+        try:
+            current = lock.lstat()
+        except FileNotFoundError:
+            current = None
+        if current and (current.st_dev, current.st_ino) == (st.st_dev, st.st_ino):
+            lock.unlink()
+
+
+class Ledger:
+    """A committed 'running' row precedes every write; unfinished rows are never auto-retried."""
+
+    def __init__(self, readonly: bool = False) -> None:
+        root = state_dir()
+        path = root / "ledger.sqlite3"
+        if readonly:
+            if not path.exists():
+                raise OperationError("unknown_request", "No operation has been recorded.", "needs_input")
+            self.db = sqlite3.connect(path.as_uri() + "?mode=ro", uri=True, timeout=5)
+        else:
+            _private_dir(root)
+            fd = os.open(path, os.O_CREAT | os.O_RDWR | os.O_NOFOLLOW, 0o600)
+            os.close(fd)
+            self.db = sqlite3.connect(path, timeout=5)
+            try:
+                self.db.execute("PRAGMA synchronous=FULL")
+                with self.db:
+                    self.db.execute("CREATE TABLE IF NOT EXISTS operations "
+                                    "(key TEXT PRIMARY KEY, fingerprint TEXT NOT NULL, "
+                                    "state TEXT NOT NULL, result TEXT)")
+                    self.db.execute("CREATE TABLE IF NOT EXISTS operation_intents "
+                                    "(key TEXT PRIMARY KEY, intent TEXT NOT NULL, checksum TEXT NOT NULL)")
+                # Locks may have created this directory chain before the ledger was opened.
+                for parent in (root, *root.parents):
+                    sync_path(parent, directory=True)
+            except (OSError, sqlite3.Error):
+                self.db.close()
+                raise
+
+    def close(self) -> None:
+        self.db.close()
+
+    def get(self, key: str, fingerprint: Optional[str] = None) -> Optional[dict]:
+        row = self.db.execute("SELECT fingerprint, state, result FROM operations WHERE key = ?", (key,)).fetchone()
+        if row is None:
+            return None
+        if fingerprint is not None and row[0] != fingerprint:
+            raise OperationError("idempotency_conflict", "This key belongs to a different request or plan.", "blocked")
+        if row[1] == "running":
+            raise OperationError("outcome_unknown", "This request is running or was interrupted. "
+                                 "Inspect its effects; do not retry it under a new key.")
+        result = json.loads(row[2])
+        return dict(result, replayed=True)
+
+    def claim(self, key: str, fingerprint: str, *, intent: Optional[dict] = None) -> None:
+        try:
+            with self.db:
+                self.db.execute("INSERT INTO operations VALUES (?, ?, 'running', NULL)", (key, fingerprint))
+                if intent is not None:
+                    self.db.execute("INSERT INTO operation_intents VALUES (?, ?, ?)",
+                                    (key, json.dumps(intent), digest(intent)))
+        except sqlite3.IntegrityError:
+            raise OperationError("operation_busy", "This idempotency key was already claimed; query its status.") from None
+
+    def inspect(self, key: str) -> dict:
+        row = self.db.execute("SELECT fingerprint, state, result FROM operations WHERE key=?", (key,)).fetchone()
+        if row is None:
+            raise OperationError("unknown_request", "No operation has this key.", "needs_input")
+        exists = self.db.execute("SELECT 1 FROM sqlite_master WHERE name='operation_intents'").fetchone()
+        saved = self.db.execute("SELECT intent, checksum FROM operation_intents WHERE key=?", (key,)).fetchone() if exists else None
+        intent = json.loads(saved[0]) if saved else None
+        if saved and (not isinstance(intent, dict) or digest(intent) != saved[1]):
+            raise OperationError("journal_corrupt", "The recorded operation intent failed its integrity check.")
+        return {"fingerprint": row[0], "state": row[1],
+                "result": json.loads(row[2]) if row[2] is not None else None, "intent": intent}
+
+    def finish(self, key: str, result: dict) -> None:
+        with self.db:
+            self.db.execute("UPDATE operations SET state = ?, result = ? WHERE key = ?",
+                            (result["status"], json.dumps(result), key))

gitpro/operation_reconcile.py

@@ -0,0 +1,191 @@
+"""Read-only postcondition evidence, never a remote-write retry or proof of attribution."""
+from __future__ import annotations
+
+import contextlib
+import dataclasses
+import sqlite3
+from pathlib import Path
+from typing import Optional
+
+from . import config, operations as op, policy, resolve
+from .operation_contract import OperationError, Request, digest, failure, request_key
+from .operation_io import Ledger, configuration_lock, file_hash, repository_lock
+
+SCHEMA = {
+    "type": "object", "additionalProperties": False,
+    "required": ["version", "command", "ok", "decision", "problems", "status", "retry_safe", "attribution"],
+    "properties": {
+        "version": {"const": 1}, "command": {"const": "operation-reconcile"},
+        "ok": {"type": "boolean"}, "decision": {"enum": ["ready", "blocked", "needs_input",
+                                                          "needs_approval", "indeterminate"]},
+        "problems": {"type": "array", "items": {"type": "object"}},
+        "operation": {"type": ["string", "null"]}, "repo": {"type": ["string", "null"]},
+        "idempotency_key": {"type": "string"}, "ledger_status": {"type": "string"},
+        "status": {"enum": ["observed", "indeterminate"]},
+        "observation": {"type": "object", "additionalProperties": False, "properties": {
+            "commit": {"type": "string"}, "remote_oid": {"type": ["string", "null"]},
+            "pr_url": {"type": "string"}, "desired_state_observed": {"type": "boolean"}}},
+        "retry_safe": {"const": False}, "attribution": {"const": "not_proven"},
+    },
+}
+
+
+def capture(plan: op.Plan) -> dict:
+    return {"version": 1, "request": plan.request.values, "plan_token": plan.token,
+            "config_path": str(plan.cfg.path), "config_how": plan.cfg.how, "snapshot": plan.snapshot,
+            "common_dir": str(plan.common), "index": str(plan.index),
+            "destination": plan.destination, "expected_digest": digest(dataclasses.asdict(plan.report.expected)),
+            "account": dataclasses.asdict(plan.account) if plan.account else None, "project": plan.project}
+
+
+def _context(intent: dict) -> op.Plan:
+    req = Request.parse(intent["request"])
+    env = op.child_environment()
+    path = Path(intent["config_path"])
+    cfg = config.load_all(path, intent["config_how"])
+    env["GITPRO_CONFIG"] = str(path)
+    index = Path(op.git(req.repo, env, "rev-parse", "--path-format=absolute", "--git-path", "index").strip())
+    common = Path(op.git(req.repo, env, "rev-parse", "--path-format=absolute", "--git-common-dir").strip())
+    top = op.git(req.repo, env, "rev-parse", "--show-toplevel").strip()
+    if common != Path(intent["common_dir"]) or Path(top).resolve() != req.repo or index != Path(intent["index"]):
+        raise OperationError("reconciliation_context_changed", "Repository layout changed; inspect the original destination.")
+    destination = op._destination(req, env)
+    report = resolve.compare(req.repo, cfg, remote=req.values.get("remote"), remote_url=destination,
+                             env=env, git_env=env, extra_checks=False)
+    snapshot = op._snapshot(req, cfg, env, index)
+    for key in ("git_config", "config", "config_file", "git_trust"):
+        if snapshot[key] != intent["snapshot"][key]:
+            raise OperationError("reconciliation_context_changed", "Configuration or trust changed; automatic observation "
+                                 "will not borrow another identity.")
+    if destination != intent["destination"] or digest(dataclasses.asdict(report.expected)) != intent["expected_digest"]:
+        raise OperationError("reconciliation_context_changed", "The destination or configured identity changed.")
+    plan = op.Plan(req, cfg, env, report, common, index, dict(intent["snapshot"]), destination)
+    op._policies(plan)
+    for key in ("policies", "signers"):
+        if plan.snapshot[key] != intent["snapshot"][key]:
+            raise OperationError("reconciliation_context_changed", "Applicable policy/trust files changed.")
+    key_stat = intent["snapshot"].get("ssh_key_stat")
+    if key_stat and op._key_stat(Path(key_stat[0])) != key_stat:
+        raise OperationError("reconciliation_context_changed", "The selected SSH key changed.")
+    if req.operation != "commit" and intent["account"] is not None:
+        op._account(plan)
+        if plan.account is None or dataclasses.asdict(plan.account) != intent["account"] or plan.project != intent["project"]:
+            raise OperationError("reconciliation_context_changed", "The selected forge account changed.")
+    return plan
+
+
+def _commit(plan: op.Plan) -> dict:
+    req, env, exp = plan.request, plan.env, plan.report.expected
+    head = op.git(req.repo, env, "rev-parse", "--verify", "--quiet", "HEAD", codes=(0, 1)).strip()
+    if not head:
+        return {"desired_state_observed": False}
+    op._oid(head)
+    observation = {"commit": head, "desired_state_observed": False}
+    if head == plan.snapshot["head"] or file_hash(plan.index) != plan.snapshot["index"]:
+        return observation
+    author_name = req.values.get("author_name", exp.name)
+    author_email = req.values.get("author_email", exp.email)
+    meta = op.git(req.repo, env, "show", "-s", "--format=%P%x00%cn%x00%ce%x00%an%x00%ae", head).rstrip("\n").split("\0")
+    if meta != [plan.snapshot["head"] or "", exp.name, exp.email, author_name, author_email]:
+        return observation
+    diff = op.process(["git", "diff", "--cached", "--quiet", "--no-ext-diff", head, "--"], req.repo, env)
+    op._checked(diff, "Reviewed index comparison", (0, 1))
+    if diff.code:
+        return observation
+    body = op.git(req.repo, env, "cat-file", "commit", head).encode()
+    message = body.split(b"\n\n", 1)[1].decode("utf-8")
+    if message.rstrip("\n") != req.values["message"].rstrip("\n"):
+        return observation
+    fmt = policy._sig_format(body)
+    if (fmt is not None) != exp.sign:
+        return observation
+    op._message_problems(plan, message, author_email or "", exp.email or "", signed=fmt is not None,
+                         signing_format=fmt)
+    if exp.sign:
+        op._verify_signature(plan, head, fmt, exp.email or "")
+    observation["desired_state_observed"] = not plan.problems
+    return observation
+
+
+def _pr(plan: op.Plan) -> dict:
+    req = plan.request.values
+    op._account(plan)
+    op._authenticate(plan)
+    owner = str(plan.project).split("/")[0]
+    candidates = []
+    for page in range(1, 11):
+        rows = op._api(plan, "repos/" + str(plan.project) + "/pulls",
+                       params={"state": "all", "head": owner + ":" + req["head"], "base": req["base"],
+                               "per_page": "100", "page": str(page)})
+        if not isinstance(rows, list) or len(rows) > 100 or any(not isinstance(row, dict) for row in rows):
+            raise OperationError("invalid_response", "GitHub returned an invalid PR listing.")
+        for row in rows:
+            head, base = row.get("head"), row.get("base")
+            if not isinstance(head, dict) or not isinstance(base, dict):
+                raise OperationError("invalid_response", "A PR is missing branch metadata.")
+            if any(not isinstance(side.get("repo"), dict) for side in (head, base)):
+                raise OperationError("invalid_response", "A PR is missing repository metadata.")
+            matches = (head.get("ref") == req["head"] and base.get("ref") == req["base"] and
+                       head["repo"].get("full_name") == plan.project and base["repo"].get("full_name") == plan.project and
+                       head.get("sha") == plan.snapshot["remote_refs"][req["head"]] and
+                       base.get("sha") == plan.snapshot["remote_refs"][req["base"]])
+            if not matches:
+                continue
+            url = op._pr_url(plan, row)
+            if url == plan.snapshot.get("existing_pr") or (
+                    row.get("title") == req["title"] and (row.get("body") or "") == req["body"] and
+                    row.get("draft") is req["draft"]):
+                candidates.append(url)
+        if len(rows) < 100:
+            break
+    else:
+        raise OperationError("reconciliation_limit", "More than 1000 PRs require separate inspection.")
+    if len(candidates) != 1:
+        return {"desired_state_observed": False}
+    return {"pr_url": candidates[0], "desired_state_observed": True}
+
+
+def reconcile(key: str, *, online: bool = False) -> dict:
+    req: Optional[Request] = None
+    try:
+        request_key(key)
+        with contextlib.closing(Ledger(readonly=True)) as ledger:
+            saved = ledger.inspect(key)
+        intent = saved["intent"]
+        if intent is None:
+            raise OperationError("intent_unavailable", "This older record has no durable intent; inspect its effects "
+                                 "manually. Do not repeat the write.", "needs_input")
+        req = Request.parse(intent["request"])
+        if saved["fingerprint"] != digest({"request": req.fingerprint, "plan": intent["plan_token"]}):
+            raise OperationError("journal_corrupt", "Recorded request and plan do not match the operation key.")
+        if req.operation != "commit" and not online:
+            raise OperationError("network_approval", "Remote observation requires explicit --online.", "needs_approval")
+        with configuration_lock(), repository_lock(Path(intent["common_dir"])):
+            plan = _context(intent)
+            if req.operation == "commit":
+                observation = _commit(plan)
+            elif req.operation == "push":
+                op._transport(plan, True)
+                current = op._remote_head(plan)
+                observation = {"remote_oid": current, "desired_state_observed": current == plan.snapshot["head"]}
+            else:
+                observation = _pr(plan)
+            # Account selection is derived from the unchanged config/destination, never caller-supplied credentials.
+            if req.operation != "commit" and (
+                    (dataclasses.asdict(plan.account) if plan.account else None) != intent["account"] or
+                    plan.project != intent["project"]):
+                raise OperationError("reconciliation_context_changed", "Forge account/project changed.")
+        observed = observation["desired_state_observed"]
+        return {"version": 1, "command": "operation-reconcile", "ok": observed,
+                "decision": "ready" if observed else "indeterminate",
+                "operation": req.operation, "repo": str(req.repo), "idempotency_key": key,
+                "status": "observed" if observed else "indeterminate", "ledger_status": saved["state"],
+                "observation": observation, "retry_safe": False, "attribution": "not_proven",
+                "problems": [] if observed else [OperationError("outcome_unconfirmed",
+                    "The reviewed postcondition is not uniquely observable. Inspect effects; absence is not retry permission.").problem()]}
+    except OperationError as exc:
+        result = failure("operation-reconcile", exc, req)
+    except (OSError, ValueError, KeyError, TypeError, config.ConfigError, sqlite3.Error, KeyboardInterrupt):
+        result = failure("operation-reconcile", OperationError("reconciliation_failed", "Observation did not complete; "
+                       "the operation remains unconfirmed. No write was retried."), req)
+    return dict(result, status="indeterminate", retry_safe=False, attribution="not_proven")