@cat-factory/app 0.116.10 → 0.118.0

package/app/components/board/AddTaskModal.vue

@@ -76,6 +76,11 @@ const TASK_TYPES = computed<{ value: TaskTypeChoice; label: string; icon: string
     { value: 'bug', label: t('board.addTask.types.bug'), icon: 'i-lucide-bug' },
     { value: 'document', label: t('board.addTask.types.document'), icon: 'i-lucide-file-text' },
     { value: 'spike', label: t('board.addTask.types.spike'), icon: 'i-lucide-flask-conical' },
+    {
+      value: 'review',
+      label: t('board.addTask.types.review'),
+      icon: 'i-lucide-clipboard-check',
+    },
     { value: 'recurring', label: t('board.addTask.types.recurring'), icon: 'i-lucide-repeat' },
   ]
   // A document repository only accepts document/spike tasks (see BoardService.addTask).
@@ -103,6 +108,25 @@ const docKind = ref<DocKind | ''>('')
 const docAudience = ref('')
 const docTargetPath = ref('')
 const docOutlineHints = ref('')
+// Review-task fields: the target PR (entered as a full URL or a bare #number) + optional
+// review focus. The single input is parsed into the contract's `prUrl`/`prNumber` fields.
+const reviewPrRef = ref('')
+const reviewFocus = ref('')
+
+// Parse the PR-reference input into the contract fields: a bare positive integer (optionally
+// `#`-prefixed) becomes `prNumber` (a PR on the service's linked repo); anything else is taken
+// as a full URL (`prUrl`). Returns undefined when blank or unparseable — the caller uses that
+// to require a target on a review task.
+function parseReviewPrRef(raw: string): Pick<TaskTypeFields, 'prUrl' | 'prNumber'> | undefined {
+  const trimmed = raw.trim()
+  if (!trimmed) return undefined
+  const bareNumber = /^#?(\d+)$/.exec(trimmed)
+  if (bareNumber) {
+    const n = Number(bareNumber[1])
+    return Number.isSafeInteger(n) && n >= 1 ? { prNumber: n } : undefined
+  }
+  return { prUrl: trimmed }
+}
 // Per-kind specific fields (see DOC_KIND_FIELDS). Held in one keyed record; only the fields
 // for the selected kind are shown and submitted, so a value from a previously-selected kind is
 // never sent. The catalog keys below keep the labels/placeholders i18n and drift-guarded.
@@ -168,6 +192,11 @@ function buildTypeFields(): TaskTypeFields | undefined {
     }
     return Object.keys(f).length ? f : undefined
   }
+  if (taskType.value === 'review') {
+    const f: TaskTypeFields = { ...parseReviewPrRef(reviewPrRef.value) }
+    if (reviewFocus.value.trim()) f.reviewFocus = reviewFocus.value.trim()
+    return Object.keys(f).length ? f : undefined
+  }
   return undefined
 }
 
@@ -381,6 +410,8 @@ watch(open, (isOpen) => {
   docAudience.value = ''
   docTargetPath.value = ''
   docOutlineHints.value = ''
+  reviewPrRef.value = ''
+  reviewFocus.value = ''
   for (const key of Object.keys(docKindFieldValues) as DocKindFieldKey[])
     delete docKindFieldValues[key]
   riskPolicyId.value = ''
@@ -434,10 +465,13 @@ const { requestClose } = useUnsavedGuard({
 })
 
 // A recurring task only needs a target frame (its details are filled in the schedule
-// modal); every other type needs a title.
-const canAdd = computed(() =>
-  isRecurring.value ? recurringFrameId.value !== null : title.value.trim().length > 0,
-)
+// modal); every other type needs a title. A review task additionally needs a target PR.
+const canAdd = computed(() => {
+  if (isRecurring.value) return recurringFrameId.value !== null
+  if (title.value.trim().length === 0) return false
+  if (taskType.value === 'review' && !parseReviewPrRef(reviewPrRef.value)) return false
+  return true
+})
 
 async function add() {
   const containerId = ui.addTaskContainerId
@@ -720,6 +754,31 @@ async function add() {
             </UFormField>
           </div>
 
+          <div v-else-if="taskType === 'review'" class="space-y-3">
+            <UFormField
+              :label="t('board.addTask.review.prUrl')"
+              :hint="t('board.addTask.review.prUrlHint')"
+              required
+            >
+              <UInput
+                v-model="reviewPrRef"
+                placeholder="https://github.com/owner/repo/pull/123"
+                class="w-full"
+              />
+            </UFormField>
+            <UFormField
+              :label="t('board.addTask.review.focus')"
+              :hint="t('board.addTask.optional')"
+            >
+              <UTextarea
+                v-model="reviewFocus"
+                :rows="2"
+                :placeholder="t('board.addTask.review.focusPlaceholder')"
+                class="w-full"
+              />
+            </UFormField>
+          </div>
+
           <div class="grid grid-cols-2 gap-3">
             <UFormField :label="t('board.addTask.pipeline')">
               <UDropdownMenu :items="pipelineMenu" class="w-full">

package/app/components/layout/NotificationsInbox.vue

@@ -64,6 +64,9 @@ const META: Record<Notification['type'], { icon: string; color: Accent }> = {
   // the title opens the fork-decision window (see `reveal`); "act" just marks it read (the
   // choice is made in that window — pick a fork / enter a custom approach — not here).
   fork_decision_pending: { icon: 'i-lucide-git-fork', color: 'warning' },
+  // The PR reviewer surfaced findings to triage. Clicking the title opens the PR-review window
+  // (see `reveal`); "act" just marks it read (findings are selected in that window, not here).
+  pr_review_ready: { icon: 'i-lucide-clipboard-check', color: 'primary' },
   // The initiative loop needs attention (a blocked task, or completion). Clicking the title
   // opens the initiative tracker window; "act" just marks it read.
   initiative: { icon: 'i-lucide-milestone', color: 'primary' },
@@ -86,6 +89,7 @@ const ACTION_KEYS: Record<Notification['type'], string> = {
   human_review: 'layout.notifications.action.human_review',
   followup_pending: 'layout.notifications.action.followup_pending',
   fork_decision_pending: 'layout.notifications.action.fork_decision_pending',
+  pr_review_ready: 'layout.notifications.action.pr_review_ready',
   initiative: 'layout.notifications.action.initiative',
 }
 
@@ -157,6 +161,7 @@ function reveal(n: Notification) {
   else if (n.type === 'human_review') revealHumanReview(n)
   else if (n.type === 'followup_pending') revealFollowUps(n)
   else if (n.type === 'fork_decision_pending') revealForkDecision(n)
+  else if (n.type === 'pr_review_ready') revealPrReview(n)
   else if (n.type === 'initiative') ui.openInitiativeTracker(n.blockId)
   else ui.select(n.blockId)
 }
@@ -191,6 +196,15 @@ function revealForkDecision(n: Notification) {
   else if (n.blockId) ui.select(n.blockId)
 }
 
+/**
+ * Open the PR deep-review window for a run parked awaiting a finding selection.
+ * Falls back to focusing the block when the run isn't loaded.
+ */
+function revealPrReview(n: Notification) {
+  if (n.executionId && execution.getInstance(n.executionId)) ui.openPrReview(n.executionId)
+  else if (n.blockId) ui.select(n.blockId)
+}
+
 /**
  * Open the human-testing window for a parked `human-test` gate: find the run's parked
  * human-test step and open it through the universal step dispatch (its archetype declares

package/app/components/panels/StepResultViewHost.vue

@@ -23,6 +23,7 @@ import GenericStructuredResultView from '~/components/panels/GenericStructuredRe
 import ServiceSpecWindow from '~/components/spec/ServiceSpecWindow.vue'
 import FollowUpWindow from '~/components/followUp/FollowUpWindow.vue'
 import ForkDecisionWindow from '~/components/forkDecision/ForkDecisionWindow.vue'
+import PrReviewWindow from '~/components/prReview/PrReviewWindow.vue'
 import MergerResultView from '~/components/panels/MergerResultView.vue'
 import InitiativeTrackerWindow from '~/components/initiative/InitiativeTrackerWindow.vue'
 import InitiativePlanningWindow from '~/components/initiative/InitiativePlanningWindow.vue'
@@ -57,6 +58,9 @@ const STEP_RESULT_VIEWS: Record<string, Component> = {
   // human's pick / custom approach. Opened directly via `ui.openForkDecision` (the pipeline
   // chip, the inspector button, and the `fork_decision_pending` card).
   'fork-decision': ForkDecisionWindow,
+  // The PR deep-review: the reviewer's sliced, prioritized findings + the human's multi-select.
+  // Opened as the `pr-reviewer` step's result view and via the `pr_review_ready` inbox card.
+  'pr-review': PrReviewWindow,
   // The merger's verdict: the PR's complexity/risk/impact scores + the engine's auto-merge
   // or awaiting-review decision (and why), instead of the agent's raw JSON.
   merger: MergerResultView,

package/app/components/prReview/PrReviewWindow.vue

@@ -0,0 +1,289 @@
+<script setup lang="ts">
+// PR deep-review window — the dedicated surface for the read-only `pr-reviewer`'s sliced,
+// prioritized findings, opened via the universal result-view host. It reads the live review
+// state straight off the run's `pr-reviewer` step (`step.prReview`, kept fresh by the
+// execution stream) and lets a human multi-SELECT which findings matter, grouped by slice and
+// sorted by severity, then finish the review. The Fixer / inline-comment resolutions are the
+// tracked PR 3 follow-up; this window's `Finish review` records the curated selection.
+import { computed, ref, watch } from 'vue'
+import { useResultView } from '~/composables/useResultView'
+import { useExecutionStore } from '~/stores/execution'
+import { useBoardStore } from '~/stores/board'
+import { usePrReviewStore } from '~/stores/prReview'
+import type { PrReviewFinding, PrReviewSeverity, PrReviewStepState } from '~/types/execution'
+
+const execution = useExecutionStore()
+const board = useBoardStore()
+const prReview = usePrReviewStore()
+
+const { t } = useI18n()
+
+const { open, blockId, instanceId, stepIndex, close } = useResultView('pr-review', {
+  onOpen: (_id) => {
+    if (instanceId.value) void prReview.load(instanceId.value)
+  },
+})
+
+const block = computed(() => (blockId.value ? board.getBlock(blockId.value) : undefined))
+const instance = computed(() =>
+  instanceId.value === null ? null : (execution.getInstance(instanceId.value) ?? null),
+)
+const step = computed(() => {
+  if (instance.value === null || stepIndex.value === null) return null
+  return instance.value.steps[stepIndex.value] ?? null
+})
+const state = computed<PrReviewStepState | null>(() => step.value?.prReview ?? null)
+const status = computed(() => state.value?.status ?? null)
+const awaiting = computed(() => status.value === 'awaiting_selection')
+const findings = computed<PrReviewFinding[]>(() => state.value?.findings ?? [])
+
+/** Severity → chip classes (styling, not copy). */
+const SEVERITY_CLASS: Record<PrReviewSeverity, string> = {
+  blocker: 'bg-rose-500/15 text-rose-300 ring-rose-500/30',
+  high: 'bg-orange-500/15 text-orange-300 ring-orange-500/30',
+  medium: 'bg-amber-500/15 text-amber-300 ring-amber-500/30',
+  low: 'bg-sky-500/15 text-sky-300 ring-sky-500/30',
+  nit: 'bg-slate-500/15 text-slate-300 ring-slate-500/30',
+}
+
+/** Findings grouped under their slice (in the review's slice order), plus an "Other" bucket. */
+const groups = computed(() => {
+  const slices = state.value?.slices ?? []
+  const byId = new Map<string, PrReviewFinding[]>()
+  const unsliced: PrReviewFinding[] = []
+  for (const f of findings.value) {
+    if (f.sliceId && slices.some((s) => s.id === f.sliceId)) {
+      const arr = byId.get(f.sliceId) ?? []
+      arr.push(f)
+      byId.set(f.sliceId, arr)
+    } else {
+      unsliced.push(f)
+    }
+  }
+  const out = slices
+    .map((s) => ({ id: s.id, title: s.title, rationale: s.rationale, items: byId.get(s.id) ?? [] }))
+    .filter((g) => g.items.length > 0)
+  if (unsliced.length > 0) {
+    out.push({ id: '__unsliced', title: t('prReview.unsliced'), rationale: '', items: unsliced })
+  }
+  return out
+})
+
+// The human's selection — a set of finding ids. Defaults to every finding (the human deselects
+// the noise), so "Finish" without touching anything keeps all. Re-seeded ONLY when the set of
+// finding IDS actually changes — NOT on every execution-stream re-emit (which hands us a fresh
+// `findings` array reference on each reconnect/resync). Keying on the id set keeps the human's
+// in-progress curation from being silently reset by an unrelated live update.
+const findingIdKey = computed(() => findings.value.map((f) => f.id).join('\n'))
+const selected = ref<Set<string>>(new Set())
+watch(
+  findingIdKey,
+  () => {
+    selected.value = new Set(findings.value.map((f) => f.id))
+  },
+  { immediate: true },
+)
+
+function toggle(id: string): void {
+  const next = new Set(selected.value)
+  if (next.has(id)) next.delete(id)
+  else next.add(id)
+  selected.value = next
+}
+function selectAll(): void {
+  selected.value = new Set(findings.value.map((f) => f.id))
+}
+function clearAll(): void {
+  selected.value = new Set()
+}
+
+const canFinish = computed(() => awaiting.value && !prReview.resolving)
+
+async function onFinish(): Promise<void> {
+  const id = instanceId.value
+  if (!id || !canFinish.value) return
+  await prReview.resolve(id, [...selected.value]).catch(() => {})
+}
+</script>
+
+<template>
+  <Teleport to="body">
+    <div
+      v-if="open"
+      data-testid="pr-review-window"
+      class="fixed inset-0 z-50 flex max-h-[100dvh] items-stretch justify-center bg-slate-950/70 backdrop-blur-sm"
+      @click.self="close"
+    >
+      <div
+        class="m-4 flex w-full max-w-3xl flex-col overflow-hidden rounded-2xl border border-slate-800 bg-slate-900 shadow-2xl"
+        role="dialog"
+        aria-modal="true"
+      >
+        <!-- Header -->
+        <header class="flex items-center gap-3 border-b border-slate-800 px-5 py-3">
+          <span
+            class="flex h-8 w-8 items-center justify-center rounded-lg bg-indigo-500/15 text-indigo-300"
+          >
+            <UIcon name="i-lucide-clipboard-check" class="h-4 w-4" />
+          </span>
+          <div class="min-w-0 flex-1">
+            <h2 class="truncate text-sm font-semibold text-slate-100">
+              {{
+                block ? t('prReview.titleWithBlock', { title: block.title }) : t('prReview.title')
+              }}
+            </h2>
+            <p class="truncate text-[11px] text-slate-400">{{ t('prReview.subtitle') }}</p>
+          </div>
+          <a
+            v-if="state?.prUrl"
+            :href="state.prUrl"
+            target="_blank"
+            rel="noopener"
+            class="rounded-md px-2 py-1 text-[11px] text-indigo-300 hover:bg-slate-800"
+          >
+            {{ t('prReview.openPr') }}
+          </a>
+          <button
+            class="rounded-md p-1.5 text-slate-400 hover:bg-slate-800 hover:text-slate-200"
+            @click="close"
+          >
+            <UIcon name="i-lucide-x" class="h-4 w-4" />
+          </button>
+        </header>
+
+        <div class="min-h-0 flex-1 overflow-y-auto px-5 py-4">
+          <!-- Reviewing: the read-only reviewer is still working. -->
+          <div
+            v-if="status === 'reviewing'"
+            class="flex h-full flex-col items-center justify-center gap-2 py-10 text-center text-slate-400"
+          >
+            <UIcon name="i-lucide-loader-circle" class="h-8 w-8 animate-spin opacity-60" />
+            <p class="text-sm">{{ t('prReview.reviewing.title') }}</p>
+            <p class="max-w-sm text-[11px] text-slate-500">{{ t('prReview.reviewing.hint') }}</p>
+          </div>
+
+          <template v-else>
+            <p
+              v-if="prReview.error"
+              class="mb-3 rounded-md bg-rose-500/10 px-3 py-2 text-[12px] text-rose-300"
+            >
+              {{ prReview.error }}
+            </p>
+
+            <!-- The reviewer's overall assessment. -->
+            <p
+              v-if="state?.summary"
+              class="mb-3 rounded-md bg-slate-800/50 px-3 py-2 text-[12px] text-slate-300"
+            >
+              <span class="text-slate-500">{{ t('prReview.summaryLabel') }}</span>
+              {{ state.summary }}
+            </p>
+
+            <!-- A clean PR / resolved review with no findings. -->
+            <div
+              v-if="findings.length === 0"
+              class="rounded-xl border border-slate-800 bg-slate-900/60 px-4 py-6 text-center text-[13px] text-slate-300"
+            >
+              {{ t('prReview.noFindings') }}
+            </div>
+
+            <template v-else>
+              <!-- Selection toolbar -->
+              <div v-if="awaiting" class="mb-2 flex items-center gap-3 text-[11px] text-slate-400">
+                <span data-testid="pr-review-selected-count">
+                  {{ t('prReview.selectedCount', { count: selected.size }) }}
+                </span>
+                <button class="text-indigo-300 hover:underline" @click="selectAll">
+                  {{ t('prReview.selectAll') }}
+                </button>
+                <button class="text-indigo-300 hover:underline" @click="clearAll">
+                  {{ t('prReview.clear') }}
+                </button>
+              </div>
+
+              <!-- Findings grouped by slice -->
+              <section v-for="g in groups" :key="g.id" class="mb-4">
+                <h3 class="mb-1.5 text-[11px] font-semibold uppercase tracking-wide text-slate-400">
+                  {{ g.title }}
+                </h3>
+                <p v-if="g.rationale" class="mb-1.5 text-[11px] text-slate-500">
+                  {{ g.rationale }}
+                </p>
+                <article
+                  v-for="f in g.items"
+                  :key="f.id"
+                  data-testid="pr-review-finding"
+                  class="mb-1.5 rounded-xl border px-3 py-2 transition"
+                  :class="
+                    awaiting && selected.has(f.id)
+                      ? 'border-indigo-500/60 bg-indigo-500/5'
+                      : 'border-slate-800 bg-slate-900/60'
+                  "
+                >
+                  <div class="flex items-start gap-2">
+                    <input
+                      v-if="awaiting"
+                      type="checkbox"
+                      class="mt-1 accent-indigo-500"
+                      data-testid="pr-review-finding-toggle"
+                      :checked="selected.has(f.id)"
+                      @change="toggle(f.id)"
+                    />
+                    <div class="min-w-0 flex-1">
+                      <div class="flex flex-wrap items-center gap-1.5">
+                        <span
+                          class="rounded px-1.5 py-0.5 text-[10px] font-semibold uppercase ring-1"
+                          :class="SEVERITY_CLASS[f.severity]"
+                        >
+                          {{ t(`prReview.severity.${f.severity}`) }}
+                        </span>
+                        <span class="rounded bg-slate-800 px-1.5 py-0.5 text-[10px] text-slate-300">
+                          {{ t(`prReview.category.${f.category}`) }}
+                        </span>
+                        <h4 class="min-w-0 flex-1 text-[13px] font-medium text-slate-100">
+                          {{ f.title }}
+                        </h4>
+                      </div>
+                      <p class="mt-0.5 text-[11px] text-slate-500">
+                        {{ f.path
+                        }}<template v-if="f.line != null">
+                          · {{ t('prReview.line', { line: f.line }) }}</template
+                        >
+                      </p>
+                      <p class="mt-1 whitespace-pre-wrap text-[12px] text-slate-300">
+                        {{ f.detail }}
+                      </p>
+                      <p
+                        v-if="f.suggestedFix"
+                        class="mt-1 whitespace-pre-wrap rounded-md bg-slate-800/50 px-2 py-1 text-[11px] text-slate-300"
+                      >
+                        <span class="text-slate-500">{{ t('prReview.suggestedFix') }}</span>
+                        {{ f.suggestedFix }}
+                      </p>
+                    </div>
+                  </div>
+                </article>
+              </section>
+            </template>
+          </template>
+        </div>
+
+        <!-- Footer -->
+        <footer
+          v-if="awaiting"
+          class="flex items-center justify-end gap-2 border-t border-slate-800 px-5 py-3"
+        >
+          <UButton
+            color="primary"
+            :loading="prReview.resolving"
+            :disabled="!canFinish"
+            data-testid="pr-review-finish"
+            @click="onFinish"
+          >
+            {{ t('prReview.finish') }}
+          </UButton>
+        </footer>
+      </div>
+    </div>
+  </Teleport>
+</template>

package/app/components/settings/WorkspaceSettingsPanel.vue

@@ -98,6 +98,7 @@ const TASK_TYPE_KEYS: Record<CreateTaskType, string> = {
   bug: 'settings.workspaceSettings.taskTypes.bug',
   document: 'settings.workspaceSettings.taskTypes.document',
   spike: 'settings.workspaceSettings.taskTypes.spike',
+  review: 'settings.workspaceSettings.taskTypes.review',
 }
 
 const MODES = computed<{ value: TaskLimitMode; label: string }[]>(() => [

package/app/components/slack/SlackPanel.vue

@@ -39,6 +39,7 @@ const ROUTABLE = computed<{ type: NotificationType; label: string }[]>(() => [
   { type: 'release_regression', label: t('slack.routable.release_regression') },
   { type: 'human_test_ready', label: t('slack.routable.human_test_ready') },
   { type: 'visual_confirmation_ready', label: t('slack.routable.visual_confirmation_ready') },
+  { type: 'pr_review_ready', label: t('slack.routable.pr_review_ready') },
   { type: 'initiative', label: t('slack.routable.initiative') },
 ])
 
@@ -64,6 +65,7 @@ const routes = reactive<Record<NotificationType, SlackRoute>>({
   human_review: { enabled: false, channel: '' },
   followup_pending: { enabled: false, channel: '' },
   fork_decision_pending: { enabled: false, channel: '' },
+  pr_review_ready: { enabled: false, channel: '' },
   initiative: { enabled: false, channel: '' },
 })
 const mentionsEnabled = ref(false)

package/app/composables/api/prReview.ts

@@ -0,0 +1,29 @@
+import { getPrReviewContract, resolvePrReviewContract } from '@cat-factory/contracts'
+import type { ApiContext } from './context'
+
+/**
+ * The PR deep-review phase: the read-only `pr-reviewer` agent slices an open pull request and
+ * surfaces prioritized findings on the run's `pr-reviewer` step, then the run parks for a human
+ * to SELECT which findings matter. These endpoints read the surfaced findings and record the
+ * human's curated selection + resolution. The read returns null when no `pr-reviewer` step
+ * carries review state.
+ */
+export function prReviewApi({ send, ws }: ApiContext) {
+  return {
+    // The live PR-review state for a run (null when no pr-reviewer step carries one).
+    getPrReview: (workspaceId: string, executionId: string) =>
+      send(getPrReviewContract, { pathPrefix: ws(workspaceId), pathParams: { executionId } }),
+
+    // Resolve a parked PR review: the curated finding selection + how it was resolved.
+    resolvePrReview: (
+      workspaceId: string,
+      executionId: string,
+      body: { action?: 'finish'; findingIds?: string[] },
+    ) =>
+      send(resolvePrReviewContract, {
+        pathPrefix: ws(workspaceId),
+        pathParams: { executionId },
+        body,
+      }),
+  }
+}

package/app/composables/useApi.ts

@@ -9,6 +9,7 @@ import { documentsApi } from './api/documents'
 import { executionApi } from './api/execution'
 import { followUpsApi } from './api/followUps'
 import { forkDecisionApi } from './api/forkDecision'
+import { prReviewApi } from './api/prReview'
 import { fragmentsApi } from './api/fragments'
 import { githubApi } from './api/github'
 import { humanReviewApi } from './api/humanReview'
@@ -110,6 +111,7 @@ export function useApi() {
     ...reviewsApi(ctx),
     ...followUpsApi(ctx),
     ...forkDecisionApi(ctx),
+    ...prReviewApi(ctx),
     ...humanTestApi(ctx),
     ...visualConfirmApi(ctx),
     ...humanReviewApi(ctx),

package/app/stores/prReview.ts

@@ -0,0 +1,80 @@
+import { defineStore } from 'pinia'
+import { ref } from 'vue'
+import type { PrReviewStepState } from '~/types/execution'
+import { useApi } from '~/composables/useApi'
+import { useWorkspaceStore } from '~/stores/workspace'
+import { useExecutionStore } from '~/stores/execution'
+
+/**
+ * The PR deep-review action surface. The live review state lives on the run's `pr-reviewer`
+ * step (`step.prReview`) and is kept fresh by the execution stream, so the window reads it
+ * straight off the execution store — this store only wraps the `resolve` action (and a warm-up
+ * `load`), tracks the in-flight state so the window can disable its controls, and reflects the
+ * returned state back onto the execution store so the UI updates immediately even before the
+ * stream echoes the change. Keyed by executionId, mirroring the fork-decision store.
+ */
+export const usePrReviewStore = defineStore('prReview', () => {
+  const api = useApi()
+  const workspace = useWorkspaceStore()
+  const execution = useExecutionStore()
+
+  /** True while a resolve call is in flight (drives the Finish button spinner / disabled state). */
+  const resolving = ref(false)
+  /** The last error message from an action, surfaced inline; cleared on the next action. */
+  const error = ref<string | null>(null)
+
+  /**
+   * Reflect an authoritative PR-review state onto the run's `pr-reviewer` step. A pipeline could
+   * carry more than one such step, so target the step this review is about: prefer the step that
+   * is still awaiting a selection, then the current step, and only then the first step carrying
+   * review state. The stream corrects any mismatch; this keeps the immediate optimistic echo on
+   * the right step.
+   */
+  function reflect(executionId: string, state: PrReviewStepState | null): void {
+    if (!state) return
+    const instance = execution.getInstance(executionId)
+    if (!instance) return
+    const isLive = (s: (typeof instance.steps)[number]) =>
+      s.agentKind === 'pr-reviewer' && s.prReview?.status === 'awaiting_selection'
+    const current = instance.steps[instance.currentStep]
+    const step =
+      instance.steps.find(isLive) ??
+      (current?.agentKind === 'pr-reviewer' && current.prReview ? current : undefined) ??
+      instance.steps.find((s) => s.prReview)
+    if (step) step.prReview = state
+  }
+
+  /** Warm the live state from the GET (the stream also keeps it fresh). Best-effort. */
+  async function load(executionId: string): Promise<void> {
+    error.value = null
+    try {
+      const state = await api.getPrReview(workspace.requireId(), executionId)
+      reflect(executionId, state as PrReviewStepState | null)
+    } catch (e) {
+      error.value = e instanceof Error ? e.message : 'Failed to load'
+    }
+  }
+
+  /**
+   * Resolve the review: record the curated finding selection and complete the read-only review
+   * (the run then advances to done). PR 2 supports only the `finish` action.
+   */
+  async function resolve(executionId: string, findingIds: string[]): Promise<void> {
+    error.value = null
+    resolving.value = true
+    try {
+      const state = await api.resolvePrReview(workspace.requireId(), executionId, {
+        action: 'finish',
+        findingIds,
+      })
+      reflect(executionId, state as PrReviewStepState)
+    } catch (e) {
+      error.value = e instanceof Error ? e.message : 'Failed to resolve review'
+      throw e
+    } finally {
+      resolving.value = false
+    }
+  }
+
+  return { resolving, error, load, resolve }
+})

package/app/stores/ui.ts

@@ -834,6 +834,31 @@ export const useUiStore = defineStore('ui', () => {
       stepIndex: idx,
     }
   }
+  // Open the PR deep-review window for a run's `pr-reviewer` step (from the `pr_review_ready`
+  // notification / the step). Resolves the step index from the run when not given, preferring
+  // the step parked awaiting a finding selection.
+  function openPrReview(instanceId: string, stepIndex: number | null = null) {
+    const execution = useExecutionStore()
+    const instance = execution.getInstance(instanceId)
+    if (!instance) return
+    const resolveIdx = () => {
+      const awaiting = instance.steps.findIndex(
+        (s) => s.agentKind === 'pr-reviewer' && s.prReview?.status === 'awaiting_selection',
+      )
+      if (awaiting >= 0) return awaiting
+      const current = instance.steps[instance.currentStep]
+      if (current?.agentKind === 'pr-reviewer' && current.prReview) return instance.currentStep
+      return instance.steps.findIndex((s) => s.agentKind === 'pr-reviewer' && s.prReview)
+    }
+    const idx = stepIndex ?? resolveIdx()
+    if (idx < 0) return
+    resultView.value = {
+      view: 'pr-review',
+      blockId: instance.blockId,
+      instanceId,
+      stepIndex: idx,
+    }
+  }
   function closeResultView() {
     resultView.value = null
   }
@@ -1032,6 +1057,7 @@ export const useUiStore = defineStore('ui', () => {
     openInitiativePlanning,
     openFollowUps,
     openForkDecision,
+    openPrReview,
     closeRequirementReview,
     openStepDetail,
     closeStepDetail,

package/app/types/execution.ts

@@ -38,6 +38,11 @@ export type {
   ForkDecisionStatus,
   ForkChoice,
   ForkDecisionStepState,
+  PrReviewStepState,
+  PrReviewFinding,
+  PrReviewSlice,
+  PrReviewSeverity,
+  PrReviewCategory,
   GateFailingCheck,
   GateAttempt,
   GateStepState,