@cat-factory/app 0.117.0 → 0.119.0

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,336 @@
+<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 resolve the review one of three ways: `Fix` (feed the selected
+// findings to a Fixer that commits fixes onto the PR branch), `Post` (publish them as inline PR
+// review comments), or `Finish` (just record the curated selection). Fix/Post act on the
+// selection, so they require at least one selected finding.
+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,
+  PrReviewResolution,
+  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')
+// A resolution is executing (the Fixer is committing, or comments are being posted) — show a
+// working state between the human's choice and the run advancing/the stream echoing `done`.
+const working = computed(() => status.value === 'fixing' || status.value === 'posting')
+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 canResolve = computed(() => awaiting.value && !prReview.resolving)
+// Fix / Post act on the selection, so they need at least one selected finding; Finish always
+// works (it just records the — possibly empty — curated selection and completes the review).
+const hasSelection = computed(() => selected.value.size > 0)
+
+async function onResolve(action: PrReviewResolution): Promise<void> {
+  const id = instanceId.value
+  if (!id || !canResolve.value) return
+  if ((action === 'fix' || action === 'post') && !hasSelection.value) return
+  await prReview.resolve(id, [...selected.value], action).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>
+
+          <!-- A resolution is executing: the Fixer is committing / comments are being posted. -->
+          <div
+            v-else-if="working"
+            data-testid="pr-review-working"
+            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">
+              {{ status === 'fixing' ? t('prReview.fixing.title') : t('prReview.posting.title') }}
+            </p>
+            <p class="max-w-sm text-[11px] text-slate-500">
+              {{ status === 'fixing' ? t('prReview.fixing.hint') : t('prReview.posting.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="neutral"
+            variant="ghost"
+            :disabled="!canResolve"
+            data-testid="pr-review-finish"
+            @click="onResolve('finish')"
+          >
+            {{ t('prReview.finish') }}
+          </UButton>
+          <UButton
+            color="neutral"
+            variant="soft"
+            :disabled="!canResolve || !hasSelection"
+            data-testid="pr-review-post"
+            @click="onResolve('post')"
+          >
+            {{ t('prReview.post') }}
+          </UButton>
+          <UButton
+            color="primary"
+            :loading="prReview.resolving"
+            :disabled="!canResolve || !hasSelection"
+            data-testid="pr-review-fix"
+            @click="onResolve('fix')"
+          >
+            {{ t('prReview.fix') }}
+          </UButton>
+        </footer>
+      </div>
+    </div>
+  </Teleport>
+</template>

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,30 @@
+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
+    // (`finish` completes it, `fix` feeds a Fixer, `post` publishes inline PR comments).
+    resolvePrReview: (
+      workspaceId: string,
+      executionId: string,
+      body: { action?: 'finish' | 'fix' | 'post'; 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/board.ts

@@ -42,6 +42,16 @@ export const useBoardStore = defineStore('board', () => {
       params ?? {},
     )
   const blocks = ref<Block[]>([])
+  // Client-side monotonic guard against a stale full-snapshot `hydrate` CLOBBERING newer live
+  // state. A run's status transitions (…→ in_progress → pr_ready/done) reach the board as
+  // targeted `execution`-event `upsert`s; a `refresh()` whose snapshot was FETCHED earlier (its
+  // block still `in_progress`) can resolve AFTER such an upsert and, since `hydrate` REPLACES the
+  // list, overwrite the just-applied terminal status back to the stale value — with no further
+  // event to restore it (the documented real-time coherence hazard; reliably hit under CI
+  // latency). Blocks carry no server revision, so we stamp each live `upsert` with a monotonic
+  // sequence and let `hydrate` preserve any block upserted AFTER the refresh's captured baseline.
+  let liveUpsertSeq = 0
+  const liveUpsertAt = new Map<string, number>()
   // Archived service frames (`archived === true`): hidden from the board but preserved and
   // restorable with no expiry. Hydrated from the snapshot's `archivedServices`; the frames
   // themselves are NOT in `blocks` (the snapshot filters an archived frame + its subtree out).
@@ -111,10 +121,22 @@ export const useBoardStore = defineStore('board', () => {
     }
     return s
   }
-  function hydrate(next: Block[]) {
+  /**
+   * Baseline for {@link hydrate}: capture this BEFORE a refresh's snapshot fetch and pass it
+   * back in, so a block that received a live `upsert` while the fetch was in flight is preserved
+   * (its live state is newer than the snapshot). Callers that don't pass a baseline get a plain
+   * full replace (initial load / board switch — no live-upsert race to guard).
+   */
+  function hydrateBaseline(): number {
+    return liveUpsertSeq
+  }
+  function hydrate(next: Block[], since = liveUpsertSeq) {
     const prev = new Map(blocks.value.map((b) => [b.id, b]))
     const reconciled = next.map((n) => {
       const existing = prev.get(n.id)
+      // A block live-`upsert`ed AFTER this refresh's fetch started is newer than the snapshot —
+      // keep the live version instead of clobbering it back to the stale snapshot value.
+      if (existing && (liveUpsertAt.get(n.id) ?? 0) > since) return existing
       return existing && jsonFor(existing) === jsonFor(n) ? existing : n
     })
     // Keep blocks the user just deleted hidden while their delete is still pending.
@@ -147,6 +169,8 @@ export const useBoardStore = defineStore('board', () => {
   function upsert(block: Block) {
     // A live event for a block awaiting its deferred delete must not resurrect it.
     if (pendingDoomed.has(block.id)) return
+    // Stamp the live-upsert order so a later, staler refresh `hydrate` can't clobber this.
+    liveUpsertAt.set(block.id, ++liveUpsertSeq)
     const i = blocks.value.findIndex((b) => b.id === block.id)
     if (i >= 0) blocks.value[i] = block
     else blocks.value.push(block)
@@ -612,6 +636,7 @@ export const useBoardStore = defineStore('board', () => {
     blocks,
     archived,
     hydrate,
+    hydrateBaseline,
     hydrateArchived,
     upsert,
     ...queries,

package/app/stores/prReview.ts

@@ -0,0 +1,86 @@
+import { defineStore } from 'pinia'
+import { ref } from 'vue'
+import type { PrReviewResolution, 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 act on it. `finish` completes
+   * the read-only review; `fix` feeds the selected findings to a Fixer (which commits fixes onto
+   * the reviewed PR's branch); `post` publishes them as inline PR review comments. The run then
+   * advances (or re-dispatches for `fix`). `fix`/`post` require ≥1 selected finding.
+   */
+  async function resolve(
+    executionId: string,
+    findingIds: string[],
+    action: PrReviewResolution = 'finish',
+  ): Promise<void> {
+    error.value = null
+    resolving.value = true
+    try {
+      const state = await api.resolvePrReview(workspace.requireId(), executionId, {
+        action,
+        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,