ltcai 5.4.0 → 5.6.0

package/frontend/src/pages/Act.tsx

@@ -2,8 +2,8 @@ import * as React from "react";
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import ReactFlow, { Background, Controls, Edge, Node } from "reactflow";
 import { Bot, CalendarClock, GitBranch, PauseCircle, Play, ShieldCheck, Workflow } from "lucide-react";
-import { latticeApi } from "@/api/client";
-import { ActionButton, DataPanel, EntityList, KeyValueList, ModeGate, OperationResult, StructuredView, Tabs } from "@/components/primitives";
+import { latticeApi, type ReviewItem } from "@/api/client";
+import { ActionButton, DataPanel, EmptyState, EntityList, KeyValueList, LoadingPanel, ModeGate, OperationResult, StructuredView, Tabs } from "@/components/primitives";
 import { Badge } from "@/components/ui/badge";
 import { Button } from "@/components/ui/button";
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
@@ -13,6 +13,20 @@ import { useAppStore } from "@/store/appStore";
 import { asArray, shortId } from "@/lib/utils";
 
 type ActTab = "agents" | "runs" | "workflows" | "hooks" | "tools";
+type RunsSubTab = "runs" | "review";
+type ReviewSourceFilter = "all" | "workflow_run" | "trigger" | "kg_change_digest";
+
+const runsSubTabs: Array<{ id: RunsSubTab; label: string }> = [
+  { id: "runs", label: "Runs" },
+  { id: "review", label: "Review" },
+];
+
+const reviewSourceFilters: Array<{ id: ReviewSourceFilter; label: string }> = [
+  { id: "all", label: "All" },
+  { id: "workflow_run", label: "Workflow" },
+  { id: "trigger", label: "Trigger" },
+  { id: "kg_change_digest", label: "KG digest" },
+];
 
 const tabs: Array<{ id: ActTab; label: string }> = [
   { id: "agents", label: "Goals" },
@@ -24,8 +38,17 @@ const tabs: Array<{ id: ActTab; label: string }> = [
 
 export function ActPage({ initialTab }: { initialTab?: string }) {
   const mode = useAppStore((state) => state.mode);
-  const [tab, setTab] = React.useState<ActTab>((initialTab as ActTab) || "agents");
+  const [tab, setTab] = React.useState<ActTab>(() => {
+    if (initialTab === "review") return "runs";
+    return (initialTab as ActTab) || "agents";
+  });
+  const [runsSubTab, setRunsSubTab] = React.useState<RunsSubTab>(initialTab === "review" ? "review" : "runs");
   React.useEffect(() => {
+    if (initialTab === "review") {
+      setTab("runs");
+      setRunsSubTab("review");
+      return;
+    }
     if (tabs.some((item) => item.id === initialTab)) setTab(initialTab as ActTab);
   }, [initialTab]);
   return (
@@ -37,7 +60,7 @@ export function ActPage({ initialTab }: { initialTab?: string }) {
       </header>
       <Tabs tabs={tabs.map((item) => mode === "basic" ? item : item.id === "hooks" ? { ...item, label: "Hooks" } : item.id === "tools" ? { ...item, label: "Tools" } : item)} value={tab} onChange={(id) => setTab(id as ActTab)} />
       {tab === "agents" ? <AgentsPanel /> : null}
-      {tab === "runs" ? <RunsPanel /> : null}
+      {tab === "runs" ? <RunsPanel subTab={runsSubTab} onSubTabChange={setRunsSubTab} /> : null}
       {tab === "workflows" ? <WorkflowsPanel /> : null}
       {tab === "hooks" ? <HooksPanel /> : null}
       {tab === "tools" ? <ToolsPanel /> : null}
@@ -123,7 +146,16 @@ function AgentsPanel() {
   );
 }
 
-function RunsPanel() {
+function RunsPanel({ subTab, onSubTabChange }: { subTab: RunsSubTab; onSubTabChange: (tab: RunsSubTab) => void }) {
+  return (
+    <div className="space-y-4">
+      <Tabs tabs={runsSubTabs} value={subTab} onChange={(id) => onSubTabChange(id as RunsSubTab)} />
+      {subTab === "runs" ? <RunsListPanel /> : <ReviewInboxPanel />}
+    </div>
+  );
+}
+
+function RunsListPanel() {
   const mode = useAppStore((state) => state.mode);
   const runtime = useQuery({ queryKey: ["agentRuntime"], queryFn: latticeApi.agentRuntime });
   const workflows = useQuery({ queryKey: ["workflowRuns"], queryFn: latticeApi.workflowRuns });
@@ -166,6 +198,171 @@ function RunsPanel() {
   );
 }
 
+function reviewStatusVariant(status: string): React.ComponentProps<typeof Badge>["variant"] {
+  if (status === "pending") return "warning";
+  if (status === "snoozed") return "muted";
+  if (status === "approved") return "success";
+  if (status === "dismissed") return "danger";
+  return "muted";
+}
+
+function reviewSourceLabel(source?: string) {
+  if (source === "workflow_run") return "Workflow run";
+  if (source === "trigger") return "Trigger";
+  if (source === "kg_change_digest") return "KG digest";
+  return source || "Automation";
+}
+
+function reviewSourceDetail(provenance: Record<string, unknown>, source?: string) {
+  const detail = provenance.source_detail;
+  if (detail != null && String(detail).trim()) return String(detail);
+  const triggerId = provenance.trigger_id;
+  if (triggerId != null && String(triggerId).trim()) return String(triggerId);
+  return reviewSourceLabel(source);
+}
+
+function defaultSnoozeUntil() {
+  const until = new Date();
+  until.setDate(until.getDate() + 1);
+  return until.toISOString();
+}
+
+function ReviewInboxPanel() {
+  const mode = useAppStore((state) => state.mode);
+  const qc = useQueryClient();
+  const [sourceFilter, setSourceFilter] = React.useState<ReviewSourceFilter>("all");
+  const [runFeedback, setRunFeedback] = React.useState<Record<string, string>>({});
+  const reviews = useQuery({
+    queryKey: ["automationReviews", sourceFilter],
+    queryFn: () => latticeApi.automationReviews({
+      status: "pending",
+      ...(sourceFilter !== "all" ? { source: sourceFilter } : {}),
+    }),
+  });
+  const items = asArray<ReviewItem>((reviews.data?.data as { items?: ReviewItem[] })?.items);
+  const actionable = (item: ReviewItem) => item.effective_status === "pending" || item.effective_status === "snoozed";
+
+  const actOnReview = async (
+    item: ReviewItem,
+    action: "approve" | "dismiss" | "snooze" | "run_now",
+    hadRunBefore = false,
+  ) => {
+    const call =
+      action === "approve" ? () => latticeApi.approveReviewItem(item.id) :
+      action === "dismiss" ? () => latticeApi.dismissReviewItem(item.id) :
+      action === "snooze" ? () => latticeApi.snoozeReviewItem(item.id, defaultSnoozeUntil()) :
+      () => latticeApi.runNowReviewItem(item.id);
+    const result = await call();
+    if (result.ok) {
+      if (action === "run_now") {
+        setRunFeedback((prev) => ({
+          ...prev,
+          [item.id]: hadRunBefore ? "Regenerated" : "Executed",
+        }));
+      } else {
+        setRunFeedback((prev) => {
+          const next = { ...prev };
+          delete next[item.id];
+          return next;
+        });
+      }
+      await qc.invalidateQueries({ queryKey: ["automationReviews"] });
+    }
+    return result;
+  };
+
+  if (reviews.isLoading) return <LoadingPanel title="Review inbox" />;
+
+  return (
+    <Card>
+      <CardHeader className="gap-3">
+        <div className="flex flex-wrap items-start justify-between gap-3">
+          <div>
+            <CardTitle>Review inbox</CardTitle>
+            <CardDescription>Automation suggestions waiting for your decision. Run now previews without approving.</CardDescription>
+          </div>
+          {reviews.data ? (
+            <Badge variant={reviews.data.ok ? "success" : "warning"}>{reviews.data.ok ? "connected" : "unavailable"}</Badge>
+          ) : null}
+        </div>
+        <Tabs
+          tabs={reviewSourceFilters}
+          value={sourceFilter}
+          onChange={(id) => setSourceFilter(id as ReviewSourceFilter)}
+        />
+      </CardHeader>
+      <CardContent>
+        {reviews.isError || (reviews.data && !reviews.data.ok) ? (
+          <EmptyState
+            title="Could not load review inbox"
+            detail={reviews.data?.error || "The review queue is not available right now."}
+          />
+        ) : !items.length ? (
+          <EmptyState
+            title="Nothing to review"
+            detail="When automations opt into the review queue, new suggestions will appear here."
+          />
+        ) : (
+          <div className="grid gap-3">
+            {items.map((item) => {
+              const provenance = (item.provenance || {}) as Record<string, unknown>;
+              const payload = (item.payload || {}) as Record<string, unknown>;
+              const hadRunBefore = Boolean(payload.last_run_id || provenance.run_id);
+              const feedback = runFeedback[item.id];
+              return (
+                <div key={item.id} className="rounded-lg border border-border bg-background/55 p-4">
+                  <div className="flex flex-wrap items-start justify-between gap-3">
+                    <div className="min-w-0 flex-1">
+                      <div className="font-medium">{item.title}</div>
+                      {item.summary ? <p className="mt-1 text-sm text-muted-foreground">{item.summary}</p> : null}
+                    </div>
+                    <div className="flex flex-wrap items-center gap-2">
+                      <Badge variant="muted">{reviewSourceLabel(item.source)}</Badge>
+                      <Badge variant={reviewStatusVariant(item.effective_status)}>{item.effective_status}</Badge>
+                    </div>
+                  </div>
+                  {mode !== "basic" ? (
+                    <div className="mt-3">
+                      <KeyValueList
+                        data={{
+                          workflow: provenance.workflow_id,
+                          trigger: provenance.trigger_id,
+                          run: payload.last_run_id || provenance.run_id,
+                          source_detail: reviewSourceDetail(provenance, item.source),
+                          snoozed_until: item.snoozed_until,
+                          created_at: item.created_at,
+                          updated_at: item.updated_at,
+                        }}
+                        limit={8}
+                      />
+                    </div>
+                  ) : null}
+                  {actionable(item) ? (
+                    <div className="mt-4 flex flex-wrap gap-2">
+                      <ActionButton
+                        label="Run now"
+                        successLabel={hadRunBefore ? "Regenerated" : "Executed"}
+                        action={() => actOnReview(item, "run_now", hadRunBefore)}
+                        invalidate={[]}
+                      />
+                      <ActionButton label="Approve" action={() => actOnReview(item, "approve")} invalidate={[]} />
+                      <ActionButton label="Snooze" action={() => actOnReview(item, "snooze")} invalidate={[]} />
+                      <ActionButton label="Dismiss" action={() => actOnReview(item, "dismiss")} invalidate={[]} variant="destructive" />
+                    </div>
+                  ) : null}
+                  {feedback ? (
+                    <p className="mt-2 text-xs text-emerald-300">{feedback} — item stays open until you approve or dismiss.</p>
+                  ) : null}
+                </div>
+              );
+            })}
+          </div>
+        )}
+      </CardContent>
+    </Card>
+  );
+}
+
 function RunList({ runs, kind }: { runs: Array<Record<string, unknown>>; kind: "agent" | "workflow" }) {
   if (!runs.length) return <EntityList items={[]} />;
   return (

package/frontend/src/routes.ts

@@ -31,6 +31,7 @@ export const routeAliases: Record<string, { primary: PrimaryRoute; tab?: string
   "my-computer": { primary: "capture", tab: "local" },
   agents: { primary: "act", tab: "agents" },
   runs: { primary: "act", tab: "runs" },
+  review: { primary: "act", tab: "review" },
   workflows: { primary: "act", tab: "workflows" },
   planning: { primary: "act", tab: "agents" },
   hooks: { primary: "act", tab: "hooks" },

package/lattice_brain/__init__.py

@@ -26,7 +26,7 @@ from .storage import (
     storage_from_env,
 )
 
-__version__ = "5.4.0"
+__version__ = "5.6.0"
 
 __all__ = [
     "AgentRuntime",

package/lattice_brain/runtime/multi_agent.py

@@ -19,7 +19,7 @@ from datetime import datetime
 from typing import Any, Callable, Dict, List, Optional
 
 
-MULTI_AGENT_VERSION = "5.4.0"
+MULTI_AGENT_VERSION = "5.6.0"
 
 AGENT_ROLES = ("researcher", "planner", "executor", "reviewer", "release")
 CORE_PIPELINE = ("planner", "executor", "reviewer")

package/latticeai/__init__.py

@@ -1,3 +1,3 @@
 """Lattice AI - modular server package."""
 
-__version__ = "5.4.0"
+__version__ = "5.6.0"

package/latticeai/api/review_queue.py

@@ -0,0 +1,158 @@
+"""Brain Review Queue API router (5.6.0).
+
+The suggestion inbox the /app Review view drives. Follows the existing
+auth/workspace dependency pattern (``require_user`` + ``gate_read``/``gate_write``)
+and exposes explicit response models so the OpenAPI types are usable from the
+frontend without massaging.
+
+Action semantics live in :class:`~latticeai.services.review_queue.ReviewQueueService`:
+
+* ``approve`` / ``dismiss`` / ``snooze`` are status transitions; an illegal
+  transition returns **409**.
+* ``run_now`` previews/regenerates without changing status (back-links the run).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, List, Optional
+
+from fastapi import APIRouter, HTTPException, Request
+from pydantic import BaseModel, Field
+
+from latticeai.services.review_queue import InvalidReviewTransition, ReviewQueueService
+
+
+class ReviewItem(BaseModel):
+    id: str
+    status: str
+    effective_status: str
+    title: str
+    summary: str = ""
+    source: str = "workflow_run"
+    kind: str = "suggestion"
+    payload: Dict[str, Any] = Field(default_factory=dict)
+    provenance: Dict[str, Any] = Field(default_factory=dict)
+    snoozed_until: Optional[str] = None
+    user_email: Optional[str] = None
+    workspace_id: Optional[str] = None
+    created_at: Optional[str] = None
+    updated_at: Optional[str] = None
+
+
+class ReviewItemList(BaseModel):
+    items: List[ReviewItem] = Field(default_factory=list)
+
+
+class CreateReviewItemRequest(BaseModel):
+    title: str
+    summary: str = ""
+    source: str = "workflow_run"
+    kind: str = "suggestion"
+    payload: Dict[str, Any] = Field(default_factory=dict)
+    provenance: Dict[str, Any] = Field(default_factory=dict)
+
+
+class SnoozeRequest(BaseModel):
+    until: str
+
+
+def create_review_queue_router(
+    *,
+    service: ReviewQueueService,
+    require_user: Callable[[Request], str],
+    gate_read: Callable[[Request], Optional[str]],
+    gate_write: Callable[[Request], Optional[str]],
+    run_review_item: Callable[..., Any],
+    append_audit_event: Callable[..., None],
+) -> APIRouter:
+    router = APIRouter()
+
+    @router.get("/automation/reviews", response_model=ReviewItemList)
+    async def list_items(
+        request: Request, status: Optional[str] = None, source: Optional[str] = None,
+    ):
+        user = require_user(request)
+        scope = gate_read(request)
+        return service.list(workspace_id=scope, user_email=user, status=status, source=source)
+
+    @router.post("/automation/reviews", response_model=ReviewItem)
+    async def create_item(req: CreateReviewItemRequest, request: Request):
+        user = require_user(request)
+        scope = gate_write(request)
+        try:
+            item = service.create(
+                title=req.title,
+                summary=req.summary,
+                source=req.source,
+                kind=req.kind,
+                payload=req.payload,
+                provenance=req.provenance,
+                user_email=user,
+                workspace_id=scope,
+            )
+        except ValueError as exc:
+            raise HTTPException(status_code=422, detail=str(exc)) from exc
+        append_audit_event("review_item_created", user_email=user, item_id=item["id"])
+        return item
+
+    @router.get("/automation/reviews/{item_id}", response_model=ReviewItem)
+    async def get_item(item_id: str, request: Request):
+        require_user(request)
+        scope = gate_read(request)
+        try:
+            return service.get(item_id, workspace_id=scope)
+        except FileNotFoundError as exc:
+            raise HTTPException(status_code=404, detail="review item not found") from exc
+
+    @router.post("/automation/reviews/{item_id}/approve", response_model=ReviewItem)
+    async def approve_item(item_id: str, request: Request):
+        return _act(request, item_id, "approve")
+
+    @router.post("/automation/reviews/{item_id}/dismiss", response_model=ReviewItem)
+    async def dismiss_item(item_id: str, request: Request):
+        return _act(request, item_id, "dismiss")
+
+    @router.post("/automation/reviews/{item_id}/snooze", response_model=ReviewItem)
+    async def snooze_item(item_id: str, req: SnoozeRequest, request: Request):
+        user = require_user(request)
+        scope = gate_write(request)
+        try:
+            item = service.snooze(item_id, until=req.until, workspace_id=scope)
+        except FileNotFoundError as exc:
+            raise HTTPException(status_code=404, detail="review item not found") from exc
+        except InvalidReviewTransition as exc:
+            raise HTTPException(status_code=409, detail=str(exc)) from exc
+        append_audit_event("review_item_snooze", user_email=user, item_id=item_id)
+        return item
+
+    @router.post("/automation/reviews/{item_id}/run_now", response_model=ReviewItem)
+    async def run_now_item(item_id: str, request: Request):
+        user = require_user(request)
+        scope = gate_write(request)
+        try:
+            item = service.run_now(
+                item_id,
+                runner=lambda stored: run_review_item(stored, user_email=user, scope=scope),
+                workspace_id=scope,
+            )
+        except FileNotFoundError as exc:
+            raise HTTPException(status_code=404, detail="review item not found") from exc
+        except InvalidReviewTransition as exc:
+            raise HTTPException(status_code=409, detail=str(exc)) from exc
+        append_audit_event("review_item_run_now", user_email=user, item_id=item_id)
+        return item
+
+    def _act(request: Request, item_id: str, action: str) -> Dict[str, Any]:
+        user = require_user(request)
+        scope = gate_write(request)
+        fn = getattr(service, action)
+        try:
+            item = fn(item_id, workspace_id=scope)
+        except FileNotFoundError as exc:
+            raise HTTPException(status_code=404, detail="review item not found") from exc
+        except InvalidReviewTransition as exc:
+            raise HTTPException(status_code=409, detail=str(exc)) from exc
+        append_audit_event(f"review_item_{action}", user_email=user, item_id=item_id)
+        return item
+
+    return router

package/latticeai/app_factory.py

@@ -1480,6 +1480,11 @@ def _build(config: "Optional[Config]" = None) -> Dict[str, Any]:
         agent_registry=AGENT_REGISTRY,
     )
 
+    # ── Brain review queue (5.6.0): the suggestion inbox automation drops into.
+    from latticeai.services.review_queue import ReviewQueueService
+
+    REVIEW_QUEUE = ReviewQueueService(store=WORKSPACE_OS)
+
     # ── v4 Trigger system (T7d): interval + brain-event workflow triggers.
     from latticeai.services.triggers import TRIGGER_HOOK_NAME, TriggerService
 
@@ -1489,6 +1494,7 @@ def _build(config: "Optional[Config]" = None) -> Dict[str, Any]:
             wf_id, None, None, with_agent=False, inputs=inputs,
         ),
         data_dir=DATA_DIR,
+        review_sink=REVIEW_QUEUE,
     )
     # Idempotent hook registration: ingestion post_tool events fan into triggers.
     _trigger_hook_id = next(
@@ -1520,6 +1526,7 @@ def _build(config: "Optional[Config]" = None) -> Dict[str, Any]:
         workspace_graph=_workspace_graph,
         append_audit_event=append_audit_event,
         hooks=HOOKS_REGISTRY,
+        review_sink=REVIEW_QUEUE,
     )
     AGENT_RUNTIME.attach_executor(RUN_EXECUTOR)
     app.state.run_executor = RUN_EXECUTOR
@@ -1723,6 +1730,27 @@ def _build(config: "Optional[Config]" = None) -> Dict[str, Any]:
         append_audit_event=append_audit_event,
     ))
 
+    from latticeai.api.review_queue import create_review_queue_router
+
+    def _run_review_item(item, *, user_email, scope):
+        """run_now: re-execute the suggestion's source workflow (preview/regenerate)."""
+        wf_id = (item.get("payload") or {}).get("workflow_id") or (item.get("provenance") or {}).get("workflow_id")
+        if not wf_id:
+            raise HTTPException(status_code=409, detail="review item has no workflow to run")
+        return PLATFORM.run_workflow_by_id(
+            wf_id, user_email, scope, with_agent=False,
+            inputs={"__review_item__": item.get("id")},
+        )
+
+    app.include_router(create_review_queue_router(
+        service=REVIEW_QUEUE,
+        require_user=require_user,
+        gate_read=PLATFORM.gate_read,
+        gate_write=PLATFORM.gate_write,
+        run_review_item=_run_review_item,
+        append_audit_event=append_audit_event,
+    ))
+
     app.include_router(create_browser_router(
         pipeline=INGESTION_PIPELINE,
         require_user=require_user,

package/latticeai/core/marketplace.py

@@ -11,7 +11,7 @@ from copy import deepcopy
 from typing import Any, Dict, List, Optional
 
 
-MARKETPLACE_VERSION = "5.4.0"
+MARKETPLACE_VERSION = "5.6.0"
 TEMPLATE_KINDS = ("plugin", "workflow", "agent")
 
 

package/latticeai/core/workspace_os.py

@@ -19,7 +19,7 @@ from pathlib import Path
 from typing import Any, Callable, Dict, Iterable, List, Optional
 
 
-WORKSPACE_OS_VERSION = "5.4.0"
+WORKSPACE_OS_VERSION = "5.6.0"
 
 # Workspace types separate single-user Personal workspaces from shared
 # Organization workspaces. Both keep the same local-first JSON store; the type
@@ -480,6 +480,7 @@ class WorkspaceOSStore:
             "handoffs": [],
             "workflows": [],
             "workflow_runs": [],
+            "review_items": [],
             "skill_registry": {},
             "plugin_registry": {},
             "template_registry": {},
@@ -1881,6 +1882,90 @@ class WorkspaceOSStore:
             raise FileNotFoundError(run_id)
         return run
 
+    # ── review queue (5.6.0) ─────────────────────────────────────────────
+    # Workspace-scoped suggestion inbox. Automation/trigger runs write drafts
+    # here for the user to approve/dismiss/snooze. Persistence only; the
+    # transition policy lives in ReviewQueueService (services/review_queue.py).
+
+    def create_review_item(
+        self,
+        *,
+        title: str,
+        summary: str = "",
+        source: str = "workflow_run",
+        kind: str = "suggestion",
+        payload: Optional[Dict[str, Any]] = None,
+        provenance: Optional[Dict[str, Any]] = None,
+        user_email: Optional[str] = None,
+        workspace_id: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        if not str(title or "").strip():
+            raise ValueError("title is required")
+        state = self.load_state()
+        resolved_workspace = self._resolve_scope(workspace_id, state)
+        now = _now()
+        item = {
+            "id": f"review-{_json_hash([title, source, kind, user_email, now])[:16]}",
+            "status": "pending",
+            "title": title,
+            "summary": summary or "",
+            "source": source or "workflow_run",
+            "kind": kind or "suggestion",
+            "payload": dict(payload or {}),
+            "provenance": dict(provenance or {}),
+            "snoozed_until": None,
+            "user_email": user_email,
+            "workspace_id": resolved_workspace,
+            "created_at": now,
+            "updated_at": now,
+        }
+        state.setdefault("review_items", []).append(item)
+        self.save_state(state)
+        self.record_timeline_event(
+            "review", "review_item_created",
+            {"item_id": item["id"], "source": item["source"], "kind": item["kind"]},
+            workspace_id=resolved_workspace,
+        )
+        return item
+
+    def list_review_items(
+        self, *, workspace_id: Optional[str] = None, user_email: Optional[str] = None,
+        source: Optional[str] = None,
+    ) -> List[Dict[str, Any]]:
+        items = self._scoped(_listify(self.load_state().get("review_items")), workspace_id)
+        if user_email:
+            items = [item for item in items if item.get("user_email") in {None, user_email}]
+        if source:
+            items = [item for item in items if item.get("source") == source]
+        return list(reversed(items))
+
+    def get_review_item(self, item_id: str, *, workspace_id: Optional[str] = None) -> Dict[str, Any]:
+        item = next(
+            (it for it in _listify(self.load_state().get("review_items")) if it.get("id") == item_id),
+            None,
+        )
+        if item is None or (workspace_id and self._record_workspace(item) != str(workspace_id)):
+            raise FileNotFoundError(item_id)
+        return item
+
+    def update_review_item(
+        self, item_id: str, *, workspace_id: Optional[str] = None, **fields: Any,
+    ) -> Dict[str, Any]:
+        state = self.load_state()
+        item = next((it for it in _listify(state.get("review_items")) if it.get("id") == item_id), None)
+        if item is None or (workspace_id and self._record_workspace(item) != str(workspace_id)):
+            raise FileNotFoundError(item_id)
+        for key, value in fields.items():
+            item[key] = value
+        item["updated_at"] = _now()
+        self.save_state(state)
+        self.record_timeline_event(
+            "review", "review_item_updated",
+            {"item_id": item_id, "status": item.get("status")},
+            workspace_id=self._record_workspace(item),
+        )
+        return item
+
     def reconcile_interrupted_runs(self, *, reason: str = "server_startup") -> Dict[str, Any]:
         """Mark durable active runs as interrupted after a process restart.