diffbutler 0.5.0__py3-none-any.whl

diffbutler/store/models.py

@@ -0,0 +1,290 @@
+"""Identity, review-cycle history, and durable per-account monitoring."""
+
+from datetime import UTC, datetime
+from uuid import UUID, uuid4
+
+from sqlalchemy import (
+    JSON,
+    CheckConstraint,
+    DateTime,
+    Float,
+    ForeignKey,
+    ForeignKeyConstraint,
+    LargeBinary,
+    MetaData,
+    String,
+    Text,
+    UniqueConstraint,
+)
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+LOCAL_ACCOUNT_ID = UUID("00000000-0000-0000-0000-000000000001")
+
+
+def utc_now() -> datetime:
+    return datetime.now(UTC)
+
+
+class Base(DeclarativeBase):
+    metadata = MetaData(
+        naming_convention={
+            "ix": "ix_%(table_name)s_%(column_0_name)s",
+            "uq": "uq_%(table_name)s_%(column_0_name)s",
+            "ck": "ck_%(table_name)s_%(constraint_name)s",
+            "fk": "fk_%(table_name)s_%(column_0_name)s_%(referred_table_name)s",
+            "pk": "pk_%(table_name)s",
+        }
+    )
+
+
+class Account(Base):
+    __tablename__ = "account"
+    id: Mapped[UUID] = mapped_column(primary_key=True, default=uuid4)
+    forge: Mapped[str] = mapped_column(String(32))
+    login: Mapped[str] = mapped_column(String(255))
+    display_name: Mapped[str] = mapped_column(String(255))
+
+
+class Repository(Base):
+    __tablename__ = "repository"
+    __table_args__ = (UniqueConstraint("forge", "namespace", "name"),)
+    id: Mapped[UUID] = mapped_column(primary_key=True, default=uuid4)
+    forge: Mapped[str] = mapped_column(String(255))
+    namespace: Mapped[str] = mapped_column(String(255))
+    name: Mapped[str] = mapped_column(String(255))
+    default_branch: Mapped[str] = mapped_column(String(255))
+    config_json: Mapped[dict[str, object]] = mapped_column(JSON, default=dict)
+    enabled: Mapped[bool] = mapped_column(default=True)
+
+
+class PullRequest(Base):
+    __tablename__ = "pull_request"
+    __table_args__ = (UniqueConstraint("repository_id", "number"),)
+    id: Mapped[UUID] = mapped_column(primary_key=True, default=uuid4)
+    repository_id: Mapped[UUID] = mapped_column(ForeignKey("repository.id"))
+    number: Mapped[int]
+    title: Mapped[str] = mapped_column(String(1024))
+    author: Mapped[str] = mapped_column(String(255))
+    head_sha: Mapped[str] = mapped_column(String(64))
+    base_sha: Mapped[str] = mapped_column(String(64))
+    head_ref: Mapped[str] = mapped_column(String(255))
+    base_ref: Mapped[str] = mapped_column(String(255))
+    is_draft: Mapped[bool] = mapped_column(default=False)
+    url: Mapped[str] = mapped_column(String(2048))
+    state: Mapped[str] = mapped_column(String(32))
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+    updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+    fetched_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now)
+    extra_json: Mapped[dict[str, object]] = mapped_column(JSON, default=dict)
+
+
+class ReviewTask(Base):
+    __tablename__ = "review_task"
+    __table_args__ = (
+        UniqueConstraint("pull_request_id", "account_id", "cycle_number"),
+        CheckConstraint("cycle_number > 0", name="positive_cycle"),
+    )
+    id: Mapped[UUID] = mapped_column(primary_key=True, default=uuid4)
+    pull_request_id: Mapped[UUID] = mapped_column(ForeignKey("pull_request.id"))
+    account_id: Mapped[UUID] = mapped_column(ForeignKey("account.id"), default=LOCAL_ACCOUNT_ID)
+    cycle_number: Mapped[int] = mapped_column(default=1)
+    state: Mapped[str] = mapped_column(String(32), default="PENDING_AI_REVIEW")
+    snapshot_json: Mapped[dict[str, object] | None] = mapped_column(JSON)
+    snoozed_until: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    priority: Mapped[int] = mapped_column(default=0)
+    notes: Mapped[str | None] = mapped_column(String(16384))
+    first_seen_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now)
+    opened_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    posted_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now)
+    following: Mapped[bool] = mapped_column(default=True)
+    request_sources_json: Mapped[list[str]] = mapped_column(JSON, default=list)
+    last_request_event: Mapped[str | None] = mapped_column(String(255))
+    last_activity_cursor: Mapped[str | None] = mapped_column(String(1024))
+    last_reviewed_sha: Mapped[str | None] = mapped_column(String(64))
+    approved_sha: Mapped[str | None] = mapped_column(String(64))
+    completed_head_sha: Mapped[str | None] = mapped_column(String(64))
+    completion_reason: Mapped[str | None] = mapped_column(String(64))
+    completion_source: Mapped[str | None] = mapped_column(String(64))
+    completion_event_watermark: Mapped[str | None] = mapped_column(String(1024))
+    action_version: Mapped[int] = mapped_column(default=0)
+    state_source: Mapped[str | None] = mapped_column(String(64))
+    state_event_watermark: Mapped[str | None] = mapped_column(String(1024))
+    completed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+
+
+class CleanupJob(Base):
+    __tablename__ = "cleanup_job"
+    __table_args__ = (UniqueConstraint("review_task_id"),)
+    id: Mapped[UUID] = mapped_column(primary_key=True, default=uuid4)
+    review_task_id: Mapped[UUID] = mapped_column(ForeignKey("review_task.id"))
+    status: Mapped[str] = mapped_column(String(32), default="pending")
+    attempts: Mapped[int] = mapped_column(default=0)
+    next_retry_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    last_error: Mapped[str | None] = mapped_column(String(4096))
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now)
+    completed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+
+
+class ForgeAccount(Base):
+    """Full API-instance identity mapped to a ledger account; local stays separate."""
+
+    __tablename__ = "forge_account"
+    __table_args__ = (UniqueConstraint("forge", "login"),)
+    account_id: Mapped[UUID] = mapped_column(ForeignKey("account.id"), primary_key=True)
+    forge: Mapped[str] = mapped_column(String(255))
+    login: Mapped[str] = mapped_column(String(255))
+    version: Mapped[int] = mapped_column(default=0)
+
+
+class PRMonitor(Base):
+    """Monitoring persists independently of request membership and completed cycles."""
+
+    __tablename__ = "pr_monitor"
+    account_id: Mapped[UUID] = mapped_column(ForeignKey("account.id"), primary_key=True)
+    pull_request_id: Mapped[UUID] = mapped_column(ForeignKey("pull_request.id"), primary_key=True)
+    task_id: Mapped[UUID] = mapped_column(ForeignKey("review_task.id"))
+    following: Mapped[bool] = mapped_column(default=True)
+    sources: Mapped[list[str]] = mapped_column(JSON, default=list)
+    snapshot_json: Mapped[dict[str, object]] = mapped_column(JSON)
+    activity_json: Mapped[str | None] = mapped_column(Text)
+    refresh_pending: Mapped[bool] = mapped_column(default=False)
+    notice: Mapped[str] = mapped_column(String(255), default="")
+    request_key: Mapped[str] = mapped_column(String(1024), default="")
+    review_key: Mapped[str] = mapped_column(String(1024), default="")
+
+
+class ReviewSession(Base):
+    """A conversation belongs to a task/account cycle, independently of its runs."""
+
+    __tablename__ = "review_session"
+    __table_args__ = (
+        UniqueConstraint("review_task_id", "reviewer_id", "generation"),
+        UniqueConstraint("id", "review_task_id", "reviewer_id"),
+        CheckConstraint("generation > 0", name="positive_generation"),
+        CheckConstraint("status IN ('ready', 'suspended', 'cleaned')", name="session_status"),
+    )
+    id: Mapped[UUID] = mapped_column(primary_key=True, default=uuid4)
+    review_task_id: Mapped[UUID] = mapped_column(ForeignKey("review_task.id"))
+    reviewer_id: Mapped[str] = mapped_column(String(255))
+    generation: Mapped[int] = mapped_column(default=1)
+    display_name: Mapped[str] = mapped_column(String(1024))
+    backend_session_id: Mapped[str | None] = mapped_column(String(1024))
+    repository_path: Mapped[str | None] = mapped_column(String(4096))
+    status: Mapped[str] = mapped_column(String(32), default="ready")
+    transcript_ref: Mapped[str | None] = mapped_column(String(4096))
+    resource_manifest_json: Mapped[list[dict[str, str]]] = mapped_column(JSON, default=list)
+    cleanup_status: Mapped[str] = mapped_column(String(32), default="not_requested")
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now)
+    resumed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    cleaned_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+
+
+class AIRun(Base):
+    """Attempt metadata survives deletion of raw output and session resources."""
+
+    __tablename__ = "ai_run"
+    __table_args__ = (
+        UniqueConstraint("analysis_key", "attempt"),
+        ForeignKeyConstraint(
+            ["review_session_id", "review_task_id", "reviewer_id"],
+            ["review_session.id", "review_session.review_task_id", "review_session.reviewer_id"],
+        ),
+        CheckConstraint("attempt > 0", name="positive_attempt"),
+        CheckConstraint(
+            "status IN ('queued', 'running', 'succeeded', 'failed', 'cancelled', 'stale')",
+            name="run_status",
+        ),
+        CheckConstraint("parse_status IN ('pending', 'succeeded', 'failed')", name="parse_status"),
+    )
+    id: Mapped[UUID] = mapped_column(primary_key=True, default=uuid4)
+    review_task_id: Mapped[UUID] = mapped_column(ForeignKey("review_task.id"))
+    review_session_id: Mapped[UUID]
+    reviewer_id: Mapped[str] = mapped_column(String(255))
+    prompt_version: Mapped[str] = mapped_column(String(255))
+    config_hash: Mapped[str] = mapped_column(String(64))
+    head_sha: Mapped[str] = mapped_column(String(64))
+    base_sha: Mapped[str] = mapped_column(String(64))
+    analysis_key: Mapped[str] = mapped_column(String(64))
+    attempt: Mapped[int]
+    status: Mapped[str] = mapped_column(String(32), default="queued")
+    parse_status: Mapped[str] = mapped_column(String(32), default="pending")
+    requested_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now)
+    started_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    finished_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    exit_code: Mapped[int | None]
+    status_reason: Mapped[str | None] = mapped_column(Text)
+    stdout_blob: Mapped[bytes | None] = mapped_column(LargeBinary)
+    stderr_blob: Mapped[bytes | None] = mapped_column(LargeBinary)
+
+
+class RunClaim(Base):
+    """Cancellation invalidates results without releasing a live worker's slot."""
+
+    __tablename__ = "run_claim"
+    token: Mapped[UUID] = mapped_column(primary_key=True, default=uuid4)
+    run_id: Mapped[UUID] = mapped_column(ForeignKey("ai_run.id"), unique=True)
+
+
+class ReviewResult(Base):
+    """Retained analysis is separate from cleanup-eligible raw AIRun output."""
+
+    __tablename__ = "review_result"
+    run_id: Mapped[UUID] = mapped_column(ForeignKey("ai_run.id"), primary_key=True)
+    document_json: Mapped[str | None] = mapped_column(Text)
+    anchors_json: Mapped[str | None] = mapped_column(Text)
+    parse_tier: Mapped[str | None] = mapped_column(String(32))
+    error: Mapped[str | None] = mapped_column(String(255))
+    notes: Mapped[list[str]] = mapped_column(JSON)
+    selected_indices: Mapped[list[int]] = mapped_column(JSON)
+    min_confidence: Mapped[float] = mapped_column(Float)
+    findings_threshold: Mapped[str] = mapped_column(String(32))
+
+
+class ForegroundLease(Base):
+    __tablename__ = "foreground_lease"
+    token: Mapped[UUID] = mapped_column(primary_key=True, default=uuid4)
+    session_id: Mapped[UUID] = mapped_column(ForeignKey("review_session.id"), unique=True)
+    backend_session_id: Mapped[str] = mapped_column(String(1024))
+    head_sha: Mapped[str] = mapped_column(String(128))
+    task_version: Mapped[int] = mapped_column()
+    acquired_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now)
+
+
+class CleanupClaim(Base):
+    __tablename__ = "cleanup_claim"
+    token: Mapped[UUID] = mapped_column(primary_key=True, default=uuid4)
+    job_id: Mapped[UUID] = mapped_column(ForeignKey("cleanup_job.id"), unique=True)
+    acquired_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now)
+
+
+class ProcessLaunch(Base):
+    """Historical ownership metadata; token references one of three claim types."""
+
+    __tablename__ = "process_launch"
+    __table_args__ = (
+        CheckConstraint("kind IN ('background', 'foreground', 'cleanup')", name="operation_kind"),
+        CheckConstraint("launcher_pid IS NULL OR launcher_pid > 0", name="positive_launcher_pid"),
+    )
+    token: Mapped[UUID] = mapped_column(primary_key=True)
+    kind: Mapped[str] = mapped_column(String(32))
+    host_id: Mapped[UUID] = mapped_column()
+    boot_id: Mapped[UUID] = mapped_column()
+    launcher_pid: Mapped[int | None] = mapped_column()
+
+
+class ObservedActivity(Base):
+    """Published forge evidence, deduplicated across polling and review cycles."""
+
+    __tablename__ = "observed_activity"
+    account_id: Mapped[UUID] = mapped_column(ForeignKey("account.id"), primary_key=True)
+    pull_request_id: Mapped[UUID] = mapped_column(ForeignKey("pull_request.id"), primary_key=True)
+    event_id: Mapped[str] = mapped_column(String(255), primary_key=True)
+    review_task_id: Mapped[UUID] = mapped_column(ForeignKey("review_task.id"))
+    payload_json: Mapped[str] = mapped_column(Text)
+
+
+class UIPreference(Base):
+    __tablename__ = "ui_preference"
+    key: Mapped[str] = mapped_column(String(255), primary_key=True)
+    value: Mapped[str] = mapped_column(Text)

diffbutler/store/process.py

@@ -0,0 +1,75 @@
+"""Claim-protected launch metadata. Historical records never authorize a new launch."""
+
+from typing import cast
+from uuid import UUID
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from diffbutler.domain.process import HostBoot, OperationKind, ProcessLaunch
+from diffbutler.domain.review import ReviewConflict
+from diffbutler.store.database import Database
+from diffbutler.store.models import CleanupClaim, ForegroundLease, RunClaim
+from diffbutler.store.models import ProcessLaunch as LaunchModel
+
+
+def record(row: LaunchModel) -> ProcessLaunch:
+    return ProcessLaunch(
+        row.token,
+        cast(OperationKind, row.kind),
+        HostBoot(row.host_id, row.boot_id),
+        row.launcher_pid,
+    )
+
+
+class SQLiteProcessStore:
+    def __init__(self, database: Database) -> None:
+        self.database = database
+
+    async def _owned(self, db: AsyncSession, token: UUID, kind: OperationKind) -> None:
+        model = {"background": RunClaim, "foreground": ForegroundLease, "cleanup": CleanupClaim}[
+            kind
+        ]
+        if await db.get(model, token) is None:
+            raise ReviewConflict("Operation no longer owns its claim")
+
+    async def get_launch(self, token: UUID) -> ProcessLaunch | None:
+        async with self.database.sessions() as db:
+            row = await db.get(LaunchModel, token)
+            return None if row is None else record(row)
+
+    async def reserve_launch(self, launch: ProcessLaunch) -> None:
+        if launch.launcher_pid is not None:
+            raise ValueError("Launch intent must be saved before starting a process")
+        async with self.database.sessions() as db:
+            connection = await db.connection()
+            await connection.exec_driver_sql("BEGIN IMMEDIATE")
+            await self._owned(db, launch.token, launch.kind)
+            row = await db.get(LaunchModel, launch.token)
+            if row is not None:
+                # Never authorize another spawn on an existing intent, even if a
+                # crash prevented saving its PID. Recovery must resolve that gap.
+                raise ReviewConflict("Launch intent already exists")
+            db.add(
+                LaunchModel(
+                    token=launch.token,
+                    kind=launch.kind,
+                    host_id=launch.origin.host_id,
+                    boot_id=launch.origin.boot_id,
+                )
+            )
+            await db.commit()
+
+    async def bind_launcher(self, token: UUID, pid: int) -> None:
+        if pid < 1:
+            raise ValueError("Launcher PID must be positive")
+        async with self.database.sessions() as db:
+            connection = await db.connection()
+            await connection.exec_driver_sql("BEGIN IMMEDIATE")
+            row = await db.get(LaunchModel, token)
+            if row is None:
+                raise ReviewConflict("Launch intent does not exist")
+            await self._owned(db, token, cast(OperationKind, row.kind))
+            if row.launcher_pid not in {None, pid}:
+                raise ReviewConflict("Launcher identity cannot be replaced")
+            row.launcher_pid = pid
+            await db.commit()

diffbutler/store/queue.py

@@ -0,0 +1,289 @@
+"""SQLite queue repository. Network reads happen before short atomic commits."""
+
+from datetime import UTC
+from typing import cast
+
+from pydantic import TypeAdapter
+from sqlalchemy import func, select, text
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from diffbutler.domain.forge import Account as ForgeIdentity
+from diffbutler.domain.forge import PRRef
+from diffbutler.domain.forge import PullRequest as ForgePR
+from diffbutler.domain.sync import (
+    CommentEvent,
+    QueueSnapshot,
+    ReviewActivity,
+    ReviewEvent,
+    TrackedPR,
+)
+from diffbutler.store.base import SyncConflict
+from diffbutler.store.database import Database
+from diffbutler.store.models import (
+    Account,
+    AIRun,
+    CleanupJob,
+    ForgeAccount,
+    ObservedActivity,
+    PRMonitor,
+    PullRequest,
+    Repository,
+    ReviewTask,
+    utc_now,
+)
+
+PR_ADAPTER = TypeAdapter(ForgePR)
+ACTIVITY_ADAPTER = TypeAdapter(ReviewActivity)
+EVENT_ADAPTER: TypeAdapter[ReviewEvent | CommentEvent] = TypeAdapter(ReviewEvent | CommentEvent)
+
+
+class SQLiteQueueStore:
+    def __init__(self, database: Database) -> None:
+        self.database = database
+
+    async def accounts(self) -> tuple[ForgeIdentity, ...]:
+        async with self.database.sessions() as session:
+            rows = await session.execute(select(ForgeAccount, Account).join(Account))
+            return tuple(
+                ForgeIdentity(identity.forge, identity.login, account.display_name)
+                for identity, account in rows
+            )
+
+    async def snapshot(self, account: ForgeIdentity) -> QueueSnapshot:
+        async with self.database.sessions() as session:
+            # One read transaction pairs the generation with all its monitor rows.
+            await session.execute(text("BEGIN"))
+            identity = await session.scalar(
+                select(ForgeAccount).where(
+                    ForgeAccount.forge == account.forge, ForgeAccount.login == account.login.lower()
+                )
+            )
+            if identity is None:
+                return QueueSnapshot(0, ())
+            rows = await session.execute(
+                select(
+                    PRMonitor,
+                    ReviewTask,
+                    select(func.max(AIRun.requested_at))
+                    .where(AIRun.review_task_id == ReviewTask.id)
+                    .correlate(ReviewTask)
+                    .scalar_subquery(),
+                )
+                .join(ReviewTask, PRMonitor.task_id == ReviewTask.id)
+                .where(PRMonitor.account_id == identity.account_id)
+            )
+            return QueueSnapshot(
+                identity.version,
+                tuple(
+                    TrackedPR(
+                        PR_ADAPTER.validate_python(monitor.snapshot_json),
+                        monitor.following,
+                        tuple(monitor.sources),
+                        task.cycle_number,
+                        task.id,
+                        task.state,
+                        monitor.request_key,
+                        monitor.review_key,
+                        task.completion_reason,
+                        task.completion_event_watermark,
+                        ACTIVITY_ADAPTER.validate_json(monitor.activity_json)
+                        if monitor.activity_json
+                        else None,
+                        monitor.refresh_pending,
+                        task.state_event_watermark or "",
+                        task.opened_at,
+                        monitor.notice,
+                        task.posted_at,
+                        requested_at.replace(tzinfo=UTC) if requested_at else None,
+                    )
+                    for monitor, task, requested_at in rows
+                ),
+            )
+
+    async def apply(
+        self,
+        account: ForgeIdentity,
+        version: int,
+        items: tuple[TrackedPR, ...],
+        *,
+        refreshed: frozenset[PRRef] = frozenset(),
+    ) -> None:
+        async with self.database.sessions() as session:
+            connection = await session.connection()
+            await connection.exec_driver_sql("BEGIN IMMEDIATE")
+            identity = await session.scalar(
+                select(ForgeAccount).where(
+                    ForgeAccount.forge == account.forge, ForgeAccount.login == account.login.lower()
+                )
+            )
+            if identity is None:
+                if version != 0:
+                    raise SyncConflict()
+                ledger = Account(
+                    forge=account.forge.split(":", 1)[0],
+                    login=account.login.lower(),
+                    display_name=account.display_name,
+                )
+                session.add(ledger)
+                await session.flush()
+                identity = ForgeAccount(
+                    account_id=ledger.id,
+                    forge=account.forge,
+                    login=account.login.lower(),
+                    version=0,
+                )
+                session.add(identity)
+            if identity.version != version:
+                raise SyncConflict()
+            for item in items:
+                if item.pull_request.ref.forge != account.forge:
+                    raise ValueError("Cannot persist a PR belonging to a different account forge")
+                await self._save(
+                    session, identity, item, refresh=item.pull_request.ref in refreshed
+                )
+            identity.version += 1
+            await session.commit()
+
+    async def _save(
+        self,
+        session: AsyncSession,
+        identity: ForgeAccount,
+        item: TrackedPR,
+        *,
+        refresh: bool,
+    ) -> None:
+        remote = item.pull_request
+        ref = remote.ref
+        repo = await session.scalar(
+            select(Repository).where(
+                Repository.forge == ref.forge,
+                Repository.namespace == ref.namespace,
+                Repository.name == ref.repository,
+            )
+        )
+        if repo is None:
+            # The PR base branch is not necessarily the repository default branch.
+            repo = Repository(
+                forge=ref.forge, namespace=ref.namespace, name=ref.repository, default_branch=""
+            )
+            session.add(repo)
+            await session.flush()
+        pr = await session.scalar(
+            select(PullRequest).where(
+                PullRequest.repository_id == repo.id, PullRequest.number == ref.number
+            )
+        )
+        if pr is None:
+            refresh = True
+            pr = PullRequest(repository_id=repo.id, number=ref.number)
+            session.add(pr)
+        if refresh:
+            for name in (
+                "title",
+                "author",
+                "url",
+                "state",
+                "head_sha",
+                "base_sha",
+                "head_ref",
+                "base_ref",
+                "is_draft",
+                "created_at",
+                "updated_at",
+            ):
+                setattr(pr, name, getattr(remote, name))
+            pr.fetched_at = utc_now()
+        await session.flush()
+        monitor = await session.get(PRMonitor, (identity.account_id, pr.id))
+        task = await session.get(ReviewTask, item.task_id) if item.task_id else None
+        if task is None:
+            last_cycle = await session.scalar(
+                select(func.max(ReviewTask.cycle_number)).where(
+                    ReviewTask.pull_request_id == pr.id,
+                    ReviewTask.account_id == identity.account_id,
+                )
+            )
+            task = ReviewTask(
+                pull_request_id=pr.id,
+                account_id=identity.account_id,
+                cycle_number=max(item.cycle, (last_cycle or 0) + 1),
+            )
+            session.add(task)
+            await session.flush()
+        if task.account_id != identity.account_id or task.pull_request_id != pr.id:
+            raise ValueError("Review task belongs to a different account or PR")
+        if monitor is not None and (
+            item.state == "DONE"
+            or remote.head_sha != monitor.snapshot_json.get("head_sha")
+            or (item.request_key > monitor.request_key and item.state == "PENDING_AI_REVIEW")
+        ):
+            # Invalidate analysis in the same commit as the observed change. A
+            # worker's separate claim remains held until it acknowledges exit.
+            runs = await session.scalars(
+                select(AIRun).where(
+                    AIRun.review_task_id == monitor.task_id,
+                    AIRun.status.in_(["queued", "running"]),
+                )
+            )
+            for run in runs:
+                run.status = "cancelled" if item.state == "DONE" else "stale"
+                run.status_reason = (
+                    "Review task completed"
+                    if item.state == "DONE"
+                    else "PR commits changed during review"
+                    if remote.head_sha != run.head_sha
+                    else "Review requested again"
+                )
+                run.finished_at = utc_now()
+        if task.completed_at is None:
+            if task.state != item.state:
+                task.action_version += 1
+                task.updated_at = utc_now()
+            task.snapshot_json = cast(
+                dict[str, object], PR_ADAPTER.dump_python(remote, mode="json")
+            )
+            if task.state != item.state:
+                task.state_source = "forge"
+            task.posted_at = item.posted_at
+            task.state = item.state
+            task.following = item.following
+            task.request_sources_json = list(item.sources)
+            task.last_request_event = item.request_key or None
+            task.last_activity_cursor = item.review_key or None
+            task.state_event_watermark = item.manual_after or None
+        if item.state == "DONE" and task.completed_at is None:
+            task.completed_at = utc_now()
+            task.completed_head_sha = remote.head_sha
+            task.completion_reason = item.completion_reason
+            task.completion_source = "forge"
+            task.completion_event_watermark = item.completion_event
+            task.approved_sha = (
+                remote.head_sha if item.completion_reason == "own_approval" else None
+            )
+            session.add(CleanupJob(review_task_id=task.id))
+        if monitor is None:
+            monitor = PRMonitor(account_id=identity.account_id, pull_request_id=pr.id)
+            session.add(monitor)
+        monitor.task_id = task.id
+        monitor.following = item.following
+        monitor.sources = list(item.sources)
+        monitor.snapshot_json = cast(dict[str, object], PR_ADAPTER.dump_python(remote, mode="json"))
+        monitor.request_key = item.request_key
+        monitor.review_key = item.review_key
+
+        monitor.refresh_pending = item.refresh_pending
+        monitor.notice = item.notice
+        if item.activity is not None:
+            monitor.activity_json = ACTIVITY_ADAPTER.dump_json(item.activity).decode()
+            for event in (*item.activity.reviews, *item.activity.comments):
+                key = (identity.account_id, pr.id, event.id)
+                receipt = await session.get(ObservedActivity, key)
+                if receipt is None:
+                    receipt = ObservedActivity(
+                        account_id=identity.account_id,
+                        pull_request_id=pr.id,
+                        event_id=event.id,
+                        review_task_id=task.id,
+                    )
+                    session.add(receipt)
+                receipt.payload_json = EVENT_ADAPTER.dump_json(event).decode()