ltcai 5.5.0 → 6.0.0

package/frontend/src/components/FirstRunGuide.tsx

@@ -53,10 +53,10 @@ export function FirstRunGuide() {
     <section className="arrival-panel" aria-label="First 10 minutes">
       <div className="arrival-copy">
         <div className="page-kicker"><CheckCircle2 className="h-4 w-4" /> First 10 minutes</div>
-        <h2>Build your living Brain without guessing.</h2>
+        <h2>Start locally, with clear consent at each step.</h2>
         <p>
-          Start with a local Brain, let Lattice recommend a model voice, then add the first pieces of durable knowledge.
-          Every step keeps the next action visible.
+          Create the local Brain first, choose when to download a model, then add durable knowledge when you are ready.
+          Nothing needs cloud access unless you explicitly choose it.
         </p>
         <div className="arrival-actions">
           <Button onClick={() => go(nextStep.action)}>{nextStep.done ? "Open relationships" : `Continue: ${nextStep.label}`}</Button>

package/frontend/src/features/review/ReviewCard.tsx

@@ -0,0 +1,91 @@
+import { RotateCcw } from "lucide-react";
+import type { ApiResult, ReviewItem } from "@/api/client";
+import { ActionButton, KeyValueList } from "@/components/primitives";
+import { Badge } from "@/components/ui/badge";
+import { Button } from "@/components/ui/button";
+import { useAppStore } from "@/store/appStore";
+import {
+  formatSnoozedUntil,
+  hasRunBefore,
+  isActionableReview,
+  reviewSourceDetail,
+  reviewSourceLabel,
+  reviewStatusVariant,
+  type ReviewAction,
+} from "./reviewHelpers";
+
+type ReviewCardProps = {
+  item: ReviewItem;
+  feedback?: string;
+  onAction: (item: ReviewItem, action: ReviewAction, hadRunBefore?: boolean) => Promise<ApiResult<ReviewItem>>;
+};
+
+export function ReviewCard({ item, feedback, onAction }: ReviewCardProps) {
+  const mode = useAppStore((state) => state.mode);
+  const provenance = item.provenance || {};
+  const payload = item.payload || {};
+  const hadRun = hasRunBefore(item);
+  const snoozed = item.effective_status === "snoozed";
+  const actionable = isActionableReview(item);
+
+  return (
+    <div 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 leading-6 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>
+
+      {snoozed ? (
+        <div className="mt-3 flex flex-wrap items-center justify-between gap-3 rounded-md border border-border bg-muted/24 p-3 text-sm">
+          <div>
+            <div className="font-medium">{formatSnoozedUntil(item.snoozed_until)}</div>
+            <p className="mt-1 text-muted-foreground">This stays out of the pending queue until then. Unsnooze brings it back immediately.</p>
+          </div>
+          <Button size="sm" variant="outline" onClick={() => onAction(item, "unsnooze")} disabled={!actionable}>
+            <RotateCcw className="h-3.5 w-3.5" /> Unsnooze
+          </Button>
+        </div>
+      ) : null}
+
+      {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 ? (
+        <div className="mt-4 flex flex-wrap gap-2">
+          <ActionButton
+            label="Run now"
+            successLabel={hadRun ? "Regenerated" : "Executed"}
+            action={() => onAction(item, "run_now", hadRun)}
+            invalidate={[]}
+          />
+          <ActionButton label="Approve" action={() => onAction(item, "approve")} invalidate={[]} />
+          {!snoozed ? <ActionButton label="Snooze 1 day" action={() => onAction(item, "snooze")} invalidate={[]} /> : null}
+          <ActionButton label="Dismiss" action={() => onAction(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>
+  );
+}

package/frontend/src/features/review/ReviewInbox.tsx

@@ -0,0 +1,112 @@
+import * as React from "react";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { latticeApi, type ReviewItem, type ReviewSourceFilter, type ReviewStatusFilter } from "@/api/client";
+import { EmptyState, LoadingPanel, Tabs } from "@/components/primitives";
+import { Badge } from "@/components/ui/badge";
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
+import { ReviewCard } from "./ReviewCard";
+import {
+  defaultSnoozeUntil,
+  reviewSourceFilters,
+  reviewStatusFilters,
+  type ReviewAction,
+} from "./reviewHelpers";
+
+export function ReviewInbox() {
+  const qc = useQueryClient();
+  const [statusFilter, setStatusFilter] = React.useState<ReviewStatusFilter>("pending");
+  const [sourceFilter, setSourceFilter] = React.useState<ReviewSourceFilter>("all");
+  const [runFeedback, setRunFeedback] = React.useState<Record<string, string>>({});
+  const reviews = useQuery({
+    queryKey: ["automationReviews", statusFilter, sourceFilter],
+    queryFn: () => latticeApi.automationReviews({
+      ...(statusFilter !== "all" ? { status: statusFilter } : {}),
+      ...(sourceFilter !== "all" ? { source: sourceFilter } : {}),
+    }),
+  });
+  const items = reviews.data?.data.items || [];
+
+  const actOnReview = async (
+    item: ReviewItem,
+    action: ReviewAction,
+    hadRunBefore = false,
+  ) => {
+    const call =
+      action === "approve" ? () => latticeApi.approveReviewItem(item.id) :
+      action === "dismiss" ? () => latticeApi.dismissReviewItem(item.id) :
+      action === "snooze" ? () => latticeApi.snoozeReviewItem(item.id, defaultSnoozeUntil()) :
+      action === "unsnooze" ? () => latticeApi.unsnoozeReviewItem(item.id) :
+      () => 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 executes without approving.</CardDescription>
+          </div>
+          {reviews.data ? (
+            <Badge variant={reviews.data.ok ? "success" : "warning"}>{reviews.data.ok ? "connected" : "unavailable"}</Badge>
+          ) : null}
+        </div>
+        <div className="grid gap-2">
+          <Tabs
+            tabs={reviewStatusFilters}
+            value={statusFilter}
+            onChange={(id) => setStatusFilter(id as ReviewStatusFilter)}
+          />
+          <Tabs
+            tabs={reviewSourceFilters}
+            value={sourceFilter}
+            onChange={(id) => setSourceFilter(id as ReviewSourceFilter)}
+          />
+        </div>
+      </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={statusFilter === "snoozed" ? "Snoozed items will appear here until they are unsnoozed or become pending again." : "When automations opt into the review queue, new suggestions will appear here."}
+          />
+        ) : (
+          <div className="grid gap-3">
+            {items.map((item) => (
+              <ReviewCard
+                key={item.id}
+                item={item}
+                feedback={runFeedback[item.id]}
+                onAction={actOnReview}
+              />
+            ))}
+          </div>
+        )}
+      </CardContent>
+    </Card>
+  );
+}

package/frontend/src/features/review/reviewHelpers.ts

@@ -0,0 +1,69 @@
+import type * as React from "react";
+import type { ReviewItem, ReviewSourceFilter, ReviewStatusFilter } from "@/api/client";
+import type { Badge } from "@/components/ui/badge";
+
+export type ReviewAction = "approve" | "dismiss" | "snooze" | "unsnooze" | "run_now";
+
+export const reviewStatusFilters: Array<{ id: ReviewStatusFilter; label: string }> = [
+  { id: "pending", label: "Pending" },
+  { id: "snoozed", label: "Snoozed" },
+  { id: "all", label: "All" },
+  { id: "approved", label: "Approved" },
+  { id: "dismissed", label: "Dismissed" },
+];
+
+export const reviewSourceFilters: Array<{ id: ReviewSourceFilter; label: string }> = [
+  { id: "all", label: "All sources" },
+  { id: "workflow_run", label: "Workflow" },
+  { id: "trigger", label: "Trigger" },
+  { id: "kg_change_digest", label: "KG digest" },
+];
+
+export 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";
+}
+
+export 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";
+}
+
+export 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);
+}
+
+export function defaultSnoozeUntil() {
+  const until = new Date();
+  until.setDate(until.getDate() + 1);
+  return until.toISOString();
+}
+
+export function formatSnoozedUntil(value?: string | null) {
+  if (!value) return "Snoozed";
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return `Snoozed until ${value}`;
+  return `Snoozed until ${new Intl.DateTimeFormat(undefined, {
+    dateStyle: "medium",
+    timeStyle: "short",
+  }).format(date)}`;
+}
+
+export function isActionableReview(item: ReviewItem) {
+  return item.effective_status === "pending" || item.effective_status === "snoozed";
+}
+
+export function hasRunBefore(item: ReviewItem) {
+  const payload = item.payload || {};
+  const provenance = item.provenance || {};
+  return Boolean(payload.last_run_id || provenance.run_id);
+}

package/frontend/src/i18n.ts

@@ -77,7 +77,7 @@ export const COPY: Record<Language, TextMap> = {
     "admin.body": "사용자, 로그, 보안, Brain 상태는 일반 사용자 화면과 분리됩니다.",
     "flow.shell": "내 로컬 AI 브레인 만들기",
     "flow.login.title": "내 AI 브레인의 주인을 정합니다.",
-    "flow.login.body": "Lattice AI는 모델이 바뀌어도 내 지식과 맥락을 보존하는 로컬 우선 AI 브레인입니다. 대화와 기억은 기본적으로 이 컴퓨터에 저장됩니다.",
+    "flow.login.body": "Lattice AI는 내 지식과 맥락을 이 컴퓨터에 보관하는 로컬 우선 AI 브레인입니다. 모델은 바꿀 수 있고, 외부 전송은 사용자가 선택할 때만 시작됩니다.",
     "flow.name": "이름",
     "flow.email": "이메일",
     "flow.password": "비밀번호",
@@ -94,9 +94,9 @@ export const COPY: Record<Language, TextMap> = {
     "flow.promise.model.k": "교체 가능한 모델",
     "flow.promise.model.v": "모델은 목소리이고, 자산은 Brain입니다.",
     "flow.promise.ownership.k": "사용자 소유",
-    "flow.promise.ownership.v": "백업, 복원, 이동이 가능합니다.",
+    "flow.promise.ownership.v": "백업, 복원, 이동을 직접 결정합니다.",
     "flow.analysis.title": "이 컴퓨터에서 가능한 경험을 확인합니다.",
-    "flow.analysis.body": "스펙 점수가 아니라, 이 Mac에서 어떤 로컬 AI 브레인 경험이 편한지 알려드립니다. 클라우드 모델은 선택 사항입니다.",
+    "flow.analysis.body": "스펙 점수가 아니라, 이 Mac에서 어떤 로컬 AI 브레인 경험이 편한지 알려드립니다. 확인은 로컬 상태를 읽는 것이고, 클라우드 모델은 선택 사항입니다.",
     "flow.analysis.finding": "가장 편한 설정을 찾는 중...",
     "flow.analysis.ready": "추천 모델을 바로 시작할 수 있게 준비했습니다.",
     "flow.analysis.wait": "잠시만 기다리면 자동으로 정리됩니다.",
@@ -109,7 +109,7 @@ export const COPY: Record<Language, TextMap> = {
     "flow.recommend.back": "뒤로",
     "flow.recommend.hint": "잘 모르겠다면 추천대로 시작하면 됩니다.",
     "flow.install.title": "모델을 설치하고 시작합니다.",
-    "flow.install.body": "이 모델이 Brain의 로컬 목소리가 됩니다. 다운로드할 때만 인터넷이 필요하고, 실행은 내 컴퓨터에서 진행됩니다.",
+    "flow.install.body": "이 모델이 Brain의 로컬 목소리가 됩니다. 인터넷은 다운로드할 때만 필요하고, 실행과 기억은 이 컴퓨터에서 유지됩니다.",
     "flow.install.wait": "Brain이 사용할 모델을 기다리고 있습니다.",
     "flow.install.prepare": "Brain 준비 중입니다.",
     "flow.install.done": "Brain이 준비되었습니다.",
@@ -190,7 +190,7 @@ export const COPY: Record<Language, TextMap> = {
     "admin.body": "Users, logs, security, and Brain health stay out of the normal user experience.",
     "flow.shell": "Create your local AI Brain",
     "flow.login.title": "Choose the owner of your AI Brain.",
-    "flow.login.body": "Lattice AI is a local-first Digital Brain that keeps your knowledge durable across any AI model. Conversations and memories are stored on this computer by default.",
+    "flow.login.body": "Lattice AI is a local-first Digital Brain that keeps your knowledge on this computer. Models can change; external transfer starts only when you choose it.",
     "flow.name": "Name",
     "flow.email": "Email",
     "flow.password": "Password",
@@ -207,9 +207,9 @@ export const COPY: Record<Language, TextMap> = {
     "flow.promise.model.k": "Replaceable models",
     "flow.promise.model.v": "The model is the voice; the Brain is the asset.",
     "flow.promise.ownership.k": "User owned",
-    "flow.promise.ownership.v": "Back up, restore, and move it.",
+    "flow.promise.ownership.v": "You decide when to back up, restore, or move it.",
     "flow.analysis.title": "Checking what this computer can do.",
-    "flow.analysis.body": "This is not a spec test. Lattice explains what local AI Brain experience this Mac can support. Cloud models remain optional.",
+    "flow.analysis.body": "This is not a spec test. Lattice reads local capability and explains what AI Brain experience this Mac can support. Cloud models remain optional.",
     "flow.analysis.finding": "Finding the easiest setup...",
     "flow.analysis.ready": "Your recommended model is ready to start.",
     "flow.analysis.wait": "This will be summarized automatically in a moment.",
@@ -222,7 +222,7 @@ export const COPY: Record<Language, TextMap> = {
     "flow.recommend.back": "Back",
     "flow.recommend.hint": "If unsure, start with the recommendation.",
     "flow.install.title": "Install the model and start.",
-    "flow.install.body": "This model becomes your Brain's local voice. Internet is needed only for download; execution happens on this computer.",
+    "flow.install.body": "This model becomes your Brain's local voice. Internet is needed only for download; execution and memory stay on this computer.",
     "flow.install.wait": "Waiting for the model your Brain will use.",
     "flow.install.prepare": "Preparing your Brain.",
     "flow.install.done": "Your Brain is ready.",

package/frontend/src/pages/Act.tsx

@@ -9,10 +9,17 @@ import { Button } from "@/components/ui/button";
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
 import { Input } from "@/components/ui/input";
 import { Textarea } from "@/components/ui/textarea";
+import { ReviewInbox } from "@/features/review/ReviewInbox";
 import { useAppStore } from "@/store/appStore";
 import { asArray, shortId } from "@/lib/utils";
 
 type ActTab = "agents" | "runs" | "workflows" | "hooks" | "tools";
+type RunsSubTab = "runs" | "review";
+
+const runsSubTabs: Array<{ id: RunsSubTab; label: string }> = [
+  { id: "runs", label: "Runs" },
+  { id: "review", label: "Review Center" },
+];
 
 const tabs: Array<{ id: ActTab; label: string }> = [
   { id: "agents", label: "Goals" },
@@ -24,8 +31,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 +53,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 +139,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 /> : <ReviewInbox />}
+    </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 });

package/frontend/src/routes.ts

@@ -31,6 +31,8 @@ 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" },
+  "review-center": { 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.5.0"
+__version__ = "6.0.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.5.0"
+MULTI_AGENT_VERSION = "6.0.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.5.0"
+__version__ = "6.0.0"

package/latticeai/api/review_queue.py

@@ -0,0 +1,162 @@
+"""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`` / ``unsnooze`` 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}/unsnooze", response_model=ReviewItem)
+    async def unsnooze_item(item_id: str, request: Request):
+        return _act(request, item_id, "unsnooze")
+
+    @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