@cyber-dash-tech/revela 0.17.12 → 0.17.14

package/README.md

@@ -45,6 +45,13 @@ codex exec --help
 npx --version
 ```
 
+If `npx` fails with an npm cache permission error, repair the cache ownership or use a writable cache for local checks:
+
+```bash
+sudo chown -R "$(id -u):$(id -g)" ~/.npm
+npm_config_cache=/tmp/revela-npm-cache bun run smoke:mcp-pack
+```
+
 Install Revela through the Codex Git marketplace:
 
 ```bash
@@ -58,6 +65,8 @@ You do not need to run `bun install` inside the Codex marketplace clone.
 
 Start a new Codex thread after installing so Codex loads the Revela skills, MCP tools, and hooks.
 
+For release-aligned local validation, run `bun run smoke:mcp-pack`. It packs the current checkout to a temporary npm tarball and starts the MCP server through `npx`, matching the published Codex launcher path without requiring a registry publish.
+
 ## Built-In Designs
 
 Revela includes built-in deck designs:

package/README.zh-CN.md

@@ -45,6 +45,13 @@ codex exec --help
 npx --version
 ```
 
+如果 `npx` 报 npm cache 权限错误，可以修复 cache owner，或在本地检查时使用可写 cache：
+
+```bash
+sudo chown -R "$(id -u):$(id -g)" ~/.npm
+npm_config_cache=/tmp/revela-npm-cache bun run smoke:mcp-pack
+```
+
 通过 Codex Git marketplace 安装 Revela：
 
 ```bash
@@ -58,6 +65,8 @@ Git marketplace 安装的是 Codex plugin 壳、skills、hooks 和 MCP 配置。
 
 安装后开启一个新的 Codex thread，让 Codex 加载 Revela 的 skills、MCP tools 和 hooks。
 
+如果要按发布路径做本地验证，运行 `bun run smoke:mcp-pack`。它会把当前 checkout 打成临时 npm tarball，再通过 `npx` 启动 MCP server，不需要先发布到 registry。
+
 ## 内置设计
 
 Revela 内置多个 deck design：

package/lib/inspect/requests.ts

@@ -1,5 +1,6 @@
 import type { InspectionPromptProjection } from "../inspection-context/project"
 import { buildDeterministicInspectionResult, type InspectionResult } from "../inspection-context/result"
+import type { ReviewBridgeEvent } from "../refine/prompt-bridge"
 
 export type InspectRequestStatus = "pending" | "completed" | "failed" | "expired"
 
@@ -10,12 +11,15 @@ export interface PendingInspectRequest {
   deckVersion: string
   createdAt: number
   updatedAt: number
+  events: ReviewBridgeEvent[]
   result?: InspectionResult
   error?: string
+  raw?: string
 }
 
 const REQUEST_TTL_MS = 90 * 1000
 const requests = new Map<string, PendingInspectRequest>()
+const subscribers = new Map<string, Set<(event: ReviewBridgeEvent) => void>>()
 
 export function createInspectRequest(input: {
   requestId: string
@@ -31,6 +35,7 @@ export function createInspectRequest(input: {
     deckVersion: input.deckVersion,
     createdAt: now,
     updatedAt: now,
+    events: [],
   }
   requests.set(input.requestId, request)
   return request
@@ -43,6 +48,11 @@ export function getInspectRequest(requestId: string): PendingInspectRequest | un
   if (request.status === "pending" && Date.now() - request.createdAt > REQUEST_TTL_MS) {
     request.status = "expired"
     request.error = "Inspection timed out before the LLM submitted a result."
+    appendInspectRequestEvent(request, {
+      type: "timeout",
+      message: request.error,
+      timestamp: Date.now(),
+    })
     request.updatedAt = Date.now()
   }
   return request
@@ -55,6 +65,13 @@ export function completeInspectRequest(requestId: string, result: InspectionResu
   request.status = "completed"
   request.result = normalizeInspectionResult(request.projection, result, requestId)
   request.updatedAt = Date.now()
+  if (!hasTerminalEvent(request)) {
+    appendInspectRequestEvent(request, {
+      type: "completed",
+      message: "Codex completed the inspection.",
+      timestamp: request.updatedAt,
+    })
+  }
   return request
 }
 
@@ -77,29 +94,92 @@ function normalizeInspectionResult(
   }
 }
 
-export function failInspectRequest(requestId: string, error: string): PendingInspectRequest | undefined {
+export function failInspectRequest(requestId: string, error: string, raw?: string): PendingInspectRequest | undefined {
   const request = getInspectRequest(requestId)
   if (!request || request.status !== "pending") return request
   request.status = "failed"
   request.error = error
+  if (raw) request.raw = boundedTail(raw)
+  request.updatedAt = Date.now()
+  if (!hasTerminalEvent(request)) {
+    appendInspectRequestEvent(request, {
+      type: "failed",
+      message: error,
+      timestamp: request.updatedAt,
+      ...(raw ? { detail: boundedTail(raw) } : {}),
+    })
+  }
+  return request
+}
+
+export function addInspectRequestEvent(requestId: string, event: ReviewBridgeEvent): PendingInspectRequest | undefined {
+  const request = getInspectRequest(requestId)
+  if (!request) return undefined
+  appendInspectRequestEvent(request, event)
   request.updatedAt = Date.now()
   return request
 }
 
+export function subscribeInspectRequestEvents(
+  requestId: string,
+  listener: (event: ReviewBridgeEvent) => void,
+): () => void {
+  const set = subscribers.get(requestId) ?? new Set<(event: ReviewBridgeEvent) => void>()
+  set.add(listener)
+  subscribers.set(requestId, set)
+  return () => {
+    set.delete(listener)
+    if (set.size === 0) subscribers.delete(requestId)
+  }
+}
+
 export function cleanupInspectRequests(now = Date.now()): void {
   for (const [requestId, request] of requests) {
     if (request.status === "pending" && now - request.createdAt > REQUEST_TTL_MS) {
       request.status = "expired"
       request.error = "Inspection timed out before the LLM submitted a result."
       request.updatedAt = now
+      appendInspectRequestEvent(request, {
+        type: "timeout",
+        message: request.error,
+        timestamp: now,
+      })
       continue
     }
     if (request.status !== "pending" && now - request.updatedAt > REQUEST_TTL_MS) {
       requests.delete(requestId)
+      subscribers.delete(requestId)
     }
   }
 }
 
 export function clearInspectRequestsForTests(): void {
   requests.clear()
+  subscribers.clear()
+}
+
+function appendInspectRequestEvent(request: PendingInspectRequest, event: ReviewBridgeEvent): void {
+  const previous = request.events.at(-1)
+  if (
+    previous
+    && previous.type === event.type
+    && previous.message === event.message
+    && previous.detail === event.detail
+    && Math.abs(previous.timestamp - event.timestamp) < 100
+  ) {
+    return
+  }
+  request.events.push(event)
+  const set = subscribers.get(request.requestId)
+  if (!set) return
+  for (const listener of set) listener(event)
+}
+
+function hasTerminalEvent(request: PendingInspectRequest): boolean {
+  return request.events.some((event) => event.type === "completed" || event.type === "failed" || event.type === "timeout")
+}
+
+function boundedTail(text: string, limit = 4096): string {
+  if (text.length <= limit) return text
+  return text.slice(text.length - limit)
 }

package/lib/refine/comment-requests.ts

@@ -1,3 +1,5 @@
+import type { ReviewBridgeEvent } from "./prompt-bridge"
+
 export type CommentRequestStatus = "pending" | "completed" | "failed" | "expired"
 
 export interface PendingCommentRequest {
@@ -6,11 +8,14 @@ export interface PendingCommentRequest {
   deckVersion: string
   createdAt: number
   updatedAt: number
+  events: ReviewBridgeEvent[]
   error?: string
+  raw?: string
 }
 
 const REQUEST_TTL_MS = 120 * 1000
 const requests = new Map<string, PendingCommentRequest>()
+const subscribers = new Map<string, Set<(event: ReviewBridgeEvent) => void>>()
 
 export function createCommentRequest(input: {
   requestId: string
@@ -24,6 +29,7 @@ export function createCommentRequest(input: {
     deckVersion: input.deckVersion,
     createdAt: now,
     updatedAt: now,
+    events: [],
   }
   requests.set(input.requestId, request)
   return request
@@ -36,6 +42,11 @@ export function getCommentRequest(requestId: string): PendingCommentRequest | un
   if (request.status === "pending" && Date.now() - request.createdAt > REQUEST_TTL_MS) {
     request.status = "expired"
     request.error = "Review agent timed out before completing the comment request."
+    appendCommentRequestEvent(request, {
+      type: "timeout",
+      message: request.error,
+      timestamp: Date.now(),
+    })
     request.updatedAt = Date.now()
   }
   return request
@@ -46,32 +57,102 @@ export function completeCommentRequest(requestId: string): PendingCommentRequest
   if (!request || request.status !== "pending") return request
   request.status = "completed"
   request.updatedAt = Date.now()
+  if (!hasTerminalEvent(request)) {
+    appendCommentRequestEvent(request, {
+      type: "completed",
+      message: "Codex completed.",
+      timestamp: request.updatedAt,
+    })
+  }
   return request
 }
 
-export function failCommentRequest(requestId: string, error: string): PendingCommentRequest | undefined {
+export function failCommentRequest(requestId: string, error: string, raw?: string): PendingCommentRequest | undefined {
   const request = getCommentRequest(requestId)
   if (!request || request.status !== "pending") return request
   request.status = "failed"
   request.error = error
+  if (raw) request.raw = boundedTail(raw)
   request.updatedAt = Date.now()
+  if (!hasTerminalEvent(request)) {
+    appendCommentRequestEvent(request, {
+      type: "failed",
+      message: error,
+      timestamp: request.updatedAt,
+      ...(raw ? { detail: boundedTail(raw) } : {}),
+    })
+  }
   return request
 }
 
+function boundedTail(text: string, limit = 4096): string {
+  if (text.length <= limit) return text
+  return text.slice(text.length - limit)
+}
+
+export function addCommentRequestEvent(requestId: string, event: ReviewBridgeEvent): PendingCommentRequest | undefined {
+  const request = getCommentRequest(requestId)
+  if (!request) return undefined
+  appendCommentRequestEvent(request, event)
+  request.updatedAt = Date.now()
+  return request
+}
+
+export function subscribeCommentRequestEvents(
+  requestId: string,
+  listener: (event: ReviewBridgeEvent) => void,
+): () => void {
+  const set = subscribers.get(requestId) ?? new Set<(event: ReviewBridgeEvent) => void>()
+  set.add(listener)
+  subscribers.set(requestId, set)
+  return () => {
+    set.delete(listener)
+    if (set.size === 0) subscribers.delete(requestId)
+  }
+}
+
 export function cleanupCommentRequests(now = Date.now()): void {
   for (const [requestId, request] of requests) {
     if (request.status === "pending" && now - request.createdAt > REQUEST_TTL_MS) {
       request.status = "expired"
       request.error = "Review agent timed out before completing the comment request."
       request.updatedAt = now
+      appendCommentRequestEvent(request, {
+        type: "timeout",
+        message: request.error,
+        timestamp: now,
+      })
       continue
     }
     if (request.status !== "pending" && now - request.updatedAt > REQUEST_TTL_MS) {
       requests.delete(requestId)
+      subscribers.delete(requestId)
     }
   }
 }
 
 export function clearCommentRequestsForTests(): void {
   requests.clear()
+  subscribers.clear()
+}
+
+function appendCommentRequestEvent(request: PendingCommentRequest, event: ReviewBridgeEvent): void {
+  const previous = request.events.at(-1)
+  if (
+    previous
+    && previous.type === event.type
+    && previous.message === event.message
+    && previous.detail === event.detail
+    && Math.abs(previous.timestamp - event.timestamp) < 100
+  ) {
+    return
+  }
+  request.events.push(event)
+  const set = subscribers.get(request.requestId)
+  if (!set) return
+  for (const listener of set) listener(event)
+}
+
+function hasTerminalEvent(request: PendingCommentRequest): boolean {
+  return request.events.some((event) => event.type === "completed" || event.type === "failed" || event.type === "timeout")
 }

package/lib/refine/open.ts

@@ -9,7 +9,7 @@ import { openUrl } from "../edit/open"
 import { resolveEditableDeck, type EditableDeck } from "../edit/resolve-deck"
 import { buildPrompt } from "../prompt-builder"
 import type { ReviewPromptBridge } from "./prompt-bridge"
-import { startRefineServer, type RefineMode } from "./server"
+import { startRefineServer, type RefineMode, type ReviewShellSurface } from "./server"
 
 export interface OpenRefineDeckResult {
   deck: EditableDeck
@@ -35,6 +35,7 @@ export interface OpenRefineDeckOptions {
   openBrowser?: boolean
   openUrl?: (url: string) => void
   promptBridge?: ReviewPromptBridge
+  surface?: ReviewShellSurface
 }
 
 export function openRefineDeck(target: string, options: OpenRefineDeckOptions): OpenRefineDeckResult {
@@ -74,7 +75,8 @@ function openRefineDeckInternal(
     mode,
     promptBridge: options.promptBridge,
   })
-  const url = `${refineServer.baseUrl}/refine?token=${encodeURIComponent(session.token)}`
+  const route = options.surface === "codex" ? "/codex-review" : "/refine"
+  const url = `${refineServer.baseUrl}${route}?token=${encodeURIComponent(session.token)}`
   const shouldOpen = options.openBrowser !== false && !(behavior.skipLiveSession && session.live)
   if (shouldOpen) (options.openUrl ?? openUrl)(url)
 

package/lib/refine/prompt-bridge.ts

@@ -4,6 +4,13 @@ import type { InspectionResult } from "../inspection-context/result"
 export type ReviewPromptAction = "comment" | "inspect"
 export type ReviewPromptBridgeKind = "opencode" | "codex-exec"
 
+export type ReviewBridgeEvent = {
+  type: "started" | "codex_event" | "stdout" | "stderr" | "completed" | "failed" | "timeout"
+  message: string
+  timestamp: number
+  detail?: string
+}
+
 export interface ReviewPromptInput {
   action: ReviewPromptAction
   prompt: string
@@ -11,6 +18,7 @@ export interface ReviewPromptInput {
   file: string
   requestId?: string
   timeoutMs?: number
+  onEvent?: (event: ReviewBridgeEvent) => void
 }
 
 export type ReviewPromptResult =
@@ -35,6 +43,7 @@ export type CodexExecRunner = (input: {
   timeoutMs: number
   sandboxMode: "read-only" | "workspace-write"
   skipGitRepoCheck: boolean
+  onEvent?: (event: ReviewBridgeEvent) => void
 }) => Promise<CodexExecRunResult>
 
 export function createOpenCodeReviewPromptBridge(client: any, sessionID: string): ReviewPromptBridge {
@@ -69,6 +78,7 @@ export function createCodexExecReviewPromptBridge(options: {
     kind: "codex-exec",
     async send(input) {
       const sandboxMode = input.action === "comment" ? "workspace-write" : "read-only"
+      input.onEvent?.(bridgeEvent("started", "Starting Codex..."))
       const output = await runner({
         action: input.action,
         prompt: input.prompt,
@@ -76,9 +86,11 @@ export function createCodexExecReviewPromptBridge(options: {
         timeoutMs: input.timeoutMs ?? timeoutMs,
         sandboxMode,
         skipGitRepoCheck: true,
+        onEvent: input.onEvent,
       })
       const raw = [output.stdout, output.stderr].filter(Boolean).join("\n")
       if (output.exitCode !== 0) {
+        input.onEvent?.(bridgeEvent("failed", `codex exec failed with exit code ${output.exitCode ?? "unknown"}.`, boundedTail(raw)))
         return {
           ok: false,
           status: "failed",
@@ -87,6 +99,7 @@ export function createCodexExecReviewPromptBridge(options: {
         }
       }
       if (input.action === "comment" && isCodexWriteBlocked(raw)) {
+        input.onEvent?.(bridgeEvent("failed", "codex exec could not write the deck because its sandbox blocked file changes.", boundedTail(raw)))
         return {
           ok: false,
           status: "failed",
@@ -94,9 +107,13 @@ export function createCodexExecReviewPromptBridge(options: {
           raw,
         }
       }
-      if (input.action === "comment") return { ok: true, status: "completed", raw }
+      if (input.action === "comment") {
+        input.onEvent?.(bridgeEvent("completed", "Codex completed."))
+        return { ok: true, status: "completed", raw }
+      }
       const result = extractInspectionResult(output.stdout)
       if (!result) {
+        input.onEvent?.(bridgeEvent("failed", "codex exec did not return a valid inspection result JSON object.", boundedTail(raw)))
         return {
           ok: false,
           status: "failed",
@@ -104,6 +121,7 @@ export function createCodexExecReviewPromptBridge(options: {
           raw,
         }
       }
+      input.onEvent?.(bridgeEvent("completed", "Codex completed the inspection."))
       return { ok: true, status: "completed", result, raw }
     },
   }
@@ -116,6 +134,7 @@ async function runCodexExec(input: {
   timeoutMs: number
   sandboxMode: "read-only" | "workspace-write"
   skipGitRepoCheck: boolean
+  onEvent?: (event: ReviewBridgeEvent) => void
 }): Promise<CodexExecRunResult> {
   return new Promise((resolve) => {
     const args = ["exec", "--json", "--ephemeral"]
@@ -126,31 +145,88 @@ async function runCodexExec(input: {
     })
     let stdout = ""
     let stderr = ""
+    let stdoutLineBuffer = ""
+    let resolved = false
+    const resolveOnce = (output: CodexExecRunResult) => {
+      if (resolved) return
+      resolved = true
+      resolve(output)
+    }
     const timer = setTimeout(() => {
       child.kill()
-      resolve({
+      const nextStderr = `${stderr}${stderr ? "\n" : ""}codex exec timed out after ${input.timeoutMs}ms.`
+      input.onEvent?.(bridgeEvent("timeout", "Codex timed out before completing.", boundedTail(nextStderr)))
+      resolveOnce({
         exitCode: 124,
         stdout,
-        stderr: `${stderr}${stderr ? "\n" : ""}codex exec timed out after ${input.timeoutMs}ms.`,
+        stderr: nextStderr,
       })
     }, input.timeoutMs)
     child.stdout?.on("data", (chunk) => {
-      stdout += chunk.toString()
+      const text = chunk.toString()
+      stdout += text
+      stdoutLineBuffer = emitCodexJsonProgress(stdoutLineBuffer + text, input.action, input.onEvent)
     })
     child.stderr?.on("data", (chunk) => {
-      stderr += chunk.toString()
+      const text = chunk.toString()
+      stderr += text
+      input.onEvent?.(bridgeEvent("stderr", "Codex wrote diagnostic output.", boundedTail(text)))
     })
     child.on("error", (error) => {
       clearTimeout(timer)
-      resolve({ exitCode: 127, stdout, stderr: error.message })
+      input.onEvent?.(bridgeEvent("failed", "Failed to start codex exec.", boundedTail(error.message)))
+      resolveOnce({ exitCode: 127, stdout, stderr: error.message })
     })
     child.on("close", (code) => {
       clearTimeout(timer)
-      resolve({ exitCode: code, stdout, stderr })
+      emitCodexJsonProgress(`${stdoutLineBuffer}\n`, input.action, input.onEvent)
+      resolveOnce({ exitCode: code, stdout, stderr })
     })
   })
 }
 
+function emitCodexJsonProgress(buffer: string, action: ReviewPromptAction, onEvent?: (event: ReviewBridgeEvent) => void): string {
+  const lines = buffer.split(/\r?\n/)
+  const remainder = lines.pop() ?? ""
+  for (const line of lines) {
+    const parsed = parseJson(line)
+    const message = codexProgressMessage(parsed, action)
+    if (message) {
+      onEvent?.(bridgeEvent("codex_event", message, boundedTail(line)))
+    } else if (parsed === undefined && line.trim()) {
+      onEvent?.(bridgeEvent("stdout", "Codex wrote output.", boundedTail(line)))
+    }
+  }
+  return remainder
+}
+
+function codexProgressMessage(value: unknown, action: ReviewPromptAction): string | undefined {
+  if (!value || typeof value !== "object") return undefined
+  const record = value as Record<string, unknown>
+  const type = typeof record.type === "string" ? record.type.toLowerCase() : ""
+  const event = typeof record.event === "string" ? record.event.toLowerCase() : ""
+  const name = `${type} ${event}`
+  if (!name.trim()) return undefined
+  if (name.includes("turn_completed") || name.includes("completed")) {
+    return action === "comment" ? undefined : "Codex completed the inspection."
+  }
+  if (name.includes("exec") || name.includes("patch") || name.includes("tool") || name.includes("apply")) {
+    return action === "comment" ? "Codex is applying the requested edit..." : "Codex is reading the deck..."
+  }
+  if (name.includes("session") || name.includes("turn") || name.includes("start")) return "Codex is reading the deck..."
+  if (name.includes("message") || name.includes("delta") || name.includes("agent")) return "Codex is working..."
+  return "Codex is working..."
+}
+
+function bridgeEvent(type: ReviewBridgeEvent["type"], message: string, detail?: string): ReviewBridgeEvent {
+  return { type, message, timestamp: Date.now(), ...(detail ? { detail } : {}) }
+}
+
+function boundedTail(text: string, limit = 4096): string {
+  if (text.length <= limit) return text
+  return text.slice(text.length - limit)
+}
+
 function isCodexWriteBlocked(raw: string): boolean {
   const text = raw.toLowerCase()
   return (

package/lib/refine/server.ts

@@ -9,11 +9,11 @@ import { buildPrompt } from "../prompt-builder"
 import type { InspectionElementSnapshot } from "../inspection-context/match"
 import { buildInspectionPrompt } from "../inspect/prompt"
 import { projectWorkspaceElement } from "../inspect/request"
-import { completeInspectRequest, createInspectRequest, failInspectRequest, getInspectRequest } from "../inspect/requests"
+import { addInspectRequestEvent, completeInspectRequest, createInspectRequest, failInspectRequest, getInspectRequest, subscribeInspectRequestEvents } from "../inspect/requests"
 import { saveMediaAsset } from "../media/save"
 import { searchRemoteImages, type ImageCandidate } from "../media/search"
 import type { MediaAssetRecord, MediaPurpose } from "../media/types"
-import { completeCommentRequest, createCommentRequest, failCommentRequest, getCommentRequest } from "./comment-requests"
+import { addCommentRequestEvent, completeCommentRequest, createCommentRequest, failCommentRequest, getCommentRequest, subscribeCommentRequestEvents } from "./comment-requests"
 import { createOpenCodeReviewPromptBridge, type ReviewPromptBridge } from "./prompt-bridge"
 import { suppressReviewApplyFixArtifactQa } from "./qa-suppression"
 import { annotateVisualEditTargets, applyVisualTargetChanges, type VisualEditTarget } from "./visual-targets"
@@ -48,6 +48,7 @@ interface EditSession {
 }
 
 export type RefineMode = "edit" | "inspect"
+export type ReviewShellSurface = "legacy" | "codex"
 
 export interface RefineServerHandle {
   baseUrl: string
@@ -177,6 +178,12 @@ async function handleRequest(req: Request): Promise<Response> {
     return htmlResponse(renderRefineShell(session.value.token, session.value.defaultMode))
   }
 
+  if (url.pathname === "/codex-review" && req.method === "GET") {
+    const session = validateSession(url.searchParams.get("token"))
+    if (!session.ok) return session.response
+    return htmlResponse(renderCodexReviewShell(session.value.token, session.value.defaultMode))
+  }
+
   if (url.pathname === "/deck" && req.method === "GET") {
     const session = validateSession(url.searchParams.get("token"))
     if (!session.ok) return session.response
@@ -201,6 +208,12 @@ async function handleRequest(req: Request): Promise<Response> {
     return handleCommentResult(url.searchParams.get("requestId"), session.value)
   }
 
+  if (url.pathname === "/api/comment-events" && req.method === "GET") {
+    const session = validateSession(url.searchParams.get("token"))
+    if (!session.ok) return session.response
+    return handleCommentEvents(url.searchParams.get("requestId"), session.value)
+  }
+
   if (url.pathname === "/api/inspect" && req.method === "POST") {
     const session = validateSession(url.searchParams.get("token"))
     if (!session.ok) return session.response
@@ -213,6 +226,12 @@ async function handleRequest(req: Request): Promise<Response> {
     return handleInspectResult(url.searchParams.get("requestId"), session.value)
   }
 
+  if (url.pathname === "/api/inspect-events" && req.method === "GET") {
+    const session = validateSession(url.searchParams.get("token"))
+    if (!session.ok) return session.response
+    return handleInspectEvents(url.searchParams.get("requestId"), session.value)
+  }
+
   if (url.pathname === "/api/deck-version" && req.method === "GET") {
     const session = validateSession(url.searchParams.get("token"))
     if (!session.ok) return session.response
@@ -474,11 +493,7 @@ function handleDeck(session: EditSession): Response {
   session.assets.clear()
   session.assetKeys.clear()
   session.nextAssetId = 1
-  const sourceHtml = readFileSync(session.absoluteFile, "utf-8")
-  const version = readDeckVersion(session).version
-  const annotated = annotateVisualEditTargets(sourceHtml)
-  session.visualTargets = annotated.targets
-  session.visualTargetDeckVersion = version
+  const annotated = refreshVisualTargets(session)
   return htmlResponse(rewriteLocalAssetRefs(annotated.html, {
     session,
     sourceFile: session.absoluteFile,
@@ -486,6 +501,15 @@ function handleDeck(session: EditSession): Response {
   }))
 }
 
+function refreshVisualTargets(session: EditSession): { html: string; version: string } {
+  const sourceHtml = readFileSync(session.absoluteFile, "utf-8")
+  const version = readDeckVersion(session).version
+  const annotated = annotateVisualEditTargets(sourceHtml)
+  session.visualTargets = annotated.targets
+  session.visualTargetDeckVersion = version
+  return { html: annotated.html, version }
+}
+
 function handleAsset(session: EditSession, id: string | null, method: string): Response {
   if (!id) return textResponse("Missing asset id", 400)
   const asset = session.assets.get(id)
@@ -707,9 +731,10 @@ async function handleVisualChanges(req: Request, session: EditSession): Promise<
       targets: session.visualTargets,
       changes,
     })
+    const refreshed = refreshVisualTargets(session)
     session.lastActiveAt = Date.now()
     scheduleIdleStop()
-    return jsonResponse({ ok: true, deckVersion: result.deckVersion, changeCount: result.changeCount })
+    return jsonResponse({ ok: true, deckVersion: refreshed.version, changeCount: result.changeCount })
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error)
     return jsonResponse({ ok: false, error: message }, 400)
@@ -765,11 +790,12 @@ async function handleComment(req: Request, session: EditSession): Promise<Respon
     workspaceRoot: session.workspaceRoot,
     file: session.file,
     requestId,
+    onEvent: (event) => addCommentRequestEvent(requestId, event),
   }).then((result) => {
     if (result.ok) {
       completeCommentRequest(requestId)
     } else {
-      failCommentRequest(requestId, result.error)
+      failCommentRequest(requestId, result.error, result.raw)
     }
   }).catch((error: unknown) => {
     const message = error instanceof Error ? error.message : String(error)
@@ -781,6 +807,88 @@ async function handleComment(req: Request, session: EditSession): Promise<Respon
   return jsonResponse({ ok: true, requestId, commentRequestId: requestId, deckVersion, status: "pending" })
 }
 
+function handleCommentEvents(requestId: string | null, session: EditSession): Response {
+  if (!requestId) return jsonResponse({ ok: false, error: "Missing requestId" }, 400)
+  const request = getCommentRequest(requestId)
+  if (!request) return jsonResponse({ ok: false, requestId, error: "Comment request not found" }, 404)
+  session.lastActiveAt = Date.now()
+  scheduleIdleStop()
+
+  const encoder = new TextEncoder()
+  let unsubscribe = () => {}
+  const stream = new ReadableStream<Uint8Array>({
+    start(controller) {
+      const send = (event: unknown) => {
+        controller.enqueue(encoder.encode(`event: progress\ndata: ${JSON.stringify(event)}\n\n`))
+      }
+      for (const event of request.events) send(event)
+      if (request.status !== "pending") {
+        controller.close()
+        return
+      }
+      unsubscribe = subscribeCommentRequestEvents(requestId, (event) => {
+        send(event)
+        if (event.type === "completed" || event.type === "failed" || event.type === "timeout") {
+          unsubscribe()
+          controller.close()
+        }
+      })
+    },
+    cancel() {
+      unsubscribe()
+    },
+  })
+
+  return new Response(stream, {
+    headers: {
+      "content-type": "text/event-stream; charset=utf-8",
+      "cache-control": "no-store",
+      connection: "keep-alive",
+    },
+  })
+}
+
+function handleInspectEvents(requestId: string | null, session: EditSession): Response {
+  if (!requestId) return jsonResponse({ ok: false, error: "Missing requestId" }, 400)
+  const request = getInspectRequest(requestId)
+  if (!request) return jsonResponse({ ok: false, requestId, error: "Inspection request not found" }, 404)
+  session.lastActiveAt = Date.now()
+  scheduleIdleStop()
+
+  const encoder = new TextEncoder()
+  let unsubscribe = () => {}
+  const stream = new ReadableStream<Uint8Array>({
+    start(controller) {
+      const send = (event: unknown) => {
+        controller.enqueue(encoder.encode(`event: progress\ndata: ${JSON.stringify(event)}\n\n`))
+      }
+      for (const event of request.events) send(event)
+      if (request.status !== "pending") {
+        controller.close()
+        return
+      }
+      unsubscribe = subscribeInspectRequestEvents(requestId, (event) => {
+        send(event)
+        if (event.type === "completed" || event.type === "failed" || event.type === "timeout") {
+          unsubscribe()
+          controller.close()
+        }
+      })
+    },
+    cancel() {
+      unsubscribe()
+    },
+  })
+
+  return new Response(stream, {
+    headers: {
+      "content-type": "text/event-stream; charset=utf-8",
+      "cache-control": "no-store",
+      connection: "keep-alive",
+    },
+  })
+}
+
 function handleCommentResult(requestId: string | null, session: EditSession): Response {
   if (!requestId) return jsonResponse({ ok: false, error: "Missing requestId" }, 400)
   const request = getCommentRequest(requestId)
@@ -788,7 +896,14 @@ function handleCommentResult(requestId: string | null, session: EditSession): Re
   session.lastActiveAt = Date.now()
   scheduleIdleStop()
   if (request.status === "failed" || request.status === "expired") {
-    return jsonResponse({ ok: true, requestId, status: request.status, deckVersion: request.deckVersion, error: request.error || "Review agent failed" })
+    return jsonResponse({
+      ok: true,
+      requestId,
+      status: request.status,
+      deckVersion: request.deckVersion,
+      error: request.error || "Review agent failed",
+      raw: request.raw,
+    })
   }
   return jsonResponse({ ok: true, requestId, status: request.status, deckVersion: request.deckVersion })
 }
@@ -834,11 +949,12 @@ async function handleInspect(req: Request, session: EditSession): Promise<Respon
       workspaceRoot: session.workspaceRoot,
       file: session.file,
       requestId,
+      onEvent: (event) => addInspectRequestEvent(requestId, event),
     }).then((result) => {
       if (result.ok && result.result) {
         completeInspectRequest(requestId, result.result)
       } else if (!result.ok) {
-        failInspectRequest(requestId, result.error)
+        failInspectRequest(requestId, result.error, result.raw)
       }
     }).catch((error: unknown) => {
       const message = error instanceof Error ? error.message : String(error)
@@ -860,7 +976,7 @@ function handleInspectResult(requestId: string | null, session: EditSession): Re
   session.lastActiveAt = Date.now()
   scheduleIdleStop()
   if (request.status === "completed") return jsonResponse({ ok: true, requestId, status: request.status, deckVersion: request.deckVersion, result: request.result })
-  if (request.status === "failed" || request.status === "expired") return jsonResponse({ ok: true, requestId, status: request.status, deckVersion: request.deckVersion, error: request.error || "Insight failed" })
+  if (request.status === "failed" || request.status === "expired") return jsonResponse({ ok: true, requestId, status: request.status, deckVersion: request.deckVersion, error: request.error || "Insight failed", raw: request.raw })
   return jsonResponse({ ok: true, requestId, status: request.status, deckVersion: request.deckVersion })
 }
 
@@ -964,9 +1080,16 @@ function jsonResponse(body: unknown, status = 200): Response {
   })
 }
 
-export function renderRefineShell(token: string, defaultMode: RefineMode = "edit"): string {
+export function renderCodexReviewShell(token: string, defaultMode: RefineMode = "edit"): string {
+  return renderRefineShell(token, defaultMode, "codex")
+}
+
+export function renderRefineShell(token: string, defaultMode: RefineMode = "edit", surface: ReviewShellSurface = "legacy"): string {
   const encodedToken = JSON.stringify(token)
   const encodedDefaultMode = JSON.stringify(defaultMode)
+  const encodedSurface = JSON.stringify(surface)
+  const activityLabel = surface === "codex" ? "Codex Activity" : "Activity"
+  const bodyClass = surface === "codex" ? "codex-review" : "legacy-review"
   return `<!doctype html>
 <html lang="en">
 <head>
@@ -1029,6 +1152,19 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
     .comment-bubble.failed { border-color: #c58f82; background: #f7eae5; }
     .comment-bubble-text { white-space: pre-wrap; overflow-wrap: anywhere; }
     .comment-bubble-state { margin-top: 8px; color: #8a6231; font-size: 12px; font-weight: 800; }
+    .comment-progress { margin-top: 8px; display: flex; flex-direction: column; gap: 4px; color: #5f574d; font-size: 12px; }
+    .comment-progress-line { display: flex; gap: 6px; align-items: flex-start; }
+    .comment-progress-line::before { content: ""; width: 6px; height: 6px; margin-top: 6px; border-radius: 999px; background: #b48b52; flex: 0 0 auto; }
+    .comment-raw { margin-top: 8px; color: #6f473c; font-size: 12px; }
+    .comment-raw summary { cursor: pointer; font-weight: 800; }
+    .comment-raw pre { margin: 6px 0 0; max-height: 160px; overflow: auto; white-space: pre-wrap; overflow-wrap: anywhere; background: rgba(255,255,255,.55); border: 1px solid rgba(143,70,56,.22); border-radius: 8px; padding: 8px; }
+    .codex-log { margin-top: 8px; color: #4b5563; font-size: 12px; }
+    .codex-log summary { cursor: pointer; font-weight: 900; }
+    .codex-log-list { margin-top: 7px; display: flex; flex-direction: column; gap: 6px; max-height: 240px; overflow: auto; }
+    .codex-log-entry { padding: 7px 8px; border: 1px solid rgba(148,163,184,.34); border-radius: 8px; background: rgba(255,255,255,.58); }
+    .codex-log-meta { display: flex; justify-content: space-between; gap: 8px; color: #6b7280; font-size: 11px; font-weight: 800; text-transform: uppercase; }
+    .codex-log-message { margin-top: 4px; color: #374151; white-space: pre-wrap; overflow-wrap: anywhere; }
+    .codex-log-detail { margin: 5px 0 0; max-height: 120px; overflow: auto; white-space: pre-wrap; overflow-wrap: anywhere; color: #111827; background: rgba(17,24,39,.05); border-radius: 6px; padding: 6px; }
     .comment-bubble.updated .comment-bubble-state { color: #556b3f; }
     .comment-bubble.stale .comment-bubble-state { color: #8a6231; }
     .comment-bubble.failed .comment-bubble-state { color: #8f4638; }
@@ -1098,7 +1234,7 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
     @media (max-width: 900px) { .app { grid-template-columns: 1fr; grid-template-rows: minmax(0, 1fr) auto; } .resize-handle { display: none; } aside { max-height: 48vh; } .deck-nav { bottom: 10px; } }
   </style>
 </head>
-<body>
+<body class="${bodyClass}">
   <main class="app">
     <section class="preview"><iframe id="deck" src="/deck?token=${encodeURIComponent(token)}"></iframe><div id="hitbox" class="hitbox" aria-label="Deck element selection layer"></div><div id="visualMoveHandle" class="visual-move-handle" aria-hidden="true"></div><div id="visualResizeHandle" class="visual-resize-handle" aria-hidden="true"></div><div id="visualEditToolbar" class="visual-edit-toolbar" aria-live="polite"><span id="visualEditCount">No unsaved visual changes</span><button id="visualUndo" type="button">Undo</button><button id="visualReset" type="button">Reset</button><button id="visualSave" class="save-visual" type="button">Save Changes</button></div><nav class="deck-nav" aria-label="Deck navigation"><button id="deckPrev" type="button" title="Previous slide (ArrowLeft / ArrowUp / PageUp)">Previous</button><div id="deckCounter" class="deck-nav-status" aria-live="polite">-- / --</div><button id="deckNext" type="button" title="Next slide (ArrowRight / ArrowDown / Space / PageDown)">Next</button></nav></section>
     <div id="resizeHandle" class="resize-handle" role="separator" aria-label="Resize editor panel" aria-orientation="vertical" title="Drag to resize editor. Double-click to reset."></div>
@@ -1123,7 +1259,7 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
           </div>
         </div>
         <button id="send" class="primary-action" disabled><svg class="send-icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M14.7 6.3a1 1 0 0 0 0 1.4l1.6 1.6a1 1 0 0 0 1.4 0l3.77-3.77a6 6 0 0 1-7.94 7.94l-6.91 6.91a2.12 2.12 0 0 1-3-3l6.91-6.91a6 6 0 0 1 7.94-7.94L14.7 6.3z"/></svg><span>Apply Fix</span></button>
-        <div class="activity-panel"><div class="label">Activity</div><div id="commentThread" class="comment-thread" aria-live="polite"></div></div>
+        <div class="activity-panel"><div class="label">${activityLabel}</div><div id="commentThread" class="comment-thread" aria-live="polite"></div></div>
       </div>
       <div id="inspectPanel" class="tab-panel">
         <div class="panel">
@@ -1155,6 +1291,8 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
     (() => {
       const token = ${encodedToken};
       const defaultMode = ${encodedDefaultMode};
+      const reviewSurface = ${encodedSurface};
+      const codexReview = reviewSurface === 'codex';
       const COMMENT_STALE_MS = 60000;
       const EDITOR_WIDTH_KEY = 'revela-edit-editor-width';
       const DEFAULT_EDITOR_WIDTH = 376;
@@ -1192,6 +1330,7 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         mode: defaultMode === 'inspect' ? 'inspect' : 'edit',
         inspecting: false,
         activeInspectRequestId: '',
+        inspectEventLog: [],
         inspectLanguage: 'Auto',
         inspectFallback: null,
         sendingEdit: false,
@@ -1975,12 +2114,19 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         window.setInterval(pollDeckVersion, 2000);
       }
 
+      async function fetchDeckVersion() {
+        const res = await fetch('/api/deck-version?token=' + encodeURIComponent(token), { cache: 'no-store' });
+        const body = await res.json().catch(() => ({}));
+        if (!res.ok || !body.ok) throw new Error(body.error || 'Failed to check deck version');
+        return {
+          body,
+          version: body.version || (String(body.mtimeMs) + ':' + String(body.size)),
+        };
+      }
+
       async function pollDeckVersion() {
         try {
-          const res = await fetch('/api/deck-version?token=' + encodeURIComponent(token), { cache: 'no-store' });
-          const body = await res.json().catch(() => ({}));
-          if (!res.ok || !body.ok) throw new Error(body.error || 'Failed to check deck version');
-          const nextVersion = body.version || (String(body.mtimeMs) + ':' + String(body.size));
+          const { body, version: nextVersion } = await fetchDeckVersion();
           if (!state.deckVersion) {
             state.deckVersion = nextVersion;
             markCommentsUpdatedForVersion(nextVersion);
@@ -1999,6 +2145,28 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         }
       }
 
+      async function watchDeckVersionAfterComment(commentId) {
+        const comment = state.pendingComments.find((item) => item.id === commentId);
+        const baseDeckVersion = comment?.baseDeckVersion || state.deckVersion;
+        const started = Date.now();
+        while (Date.now() - started < 15000) {
+          if (pendingCommentStatus(commentId) === 'updated' || pendingCommentStatus(commentId) === 'failed') return;
+          await delay(250);
+          try {
+            const { body, version: nextVersion } = await fetchDeckVersion();
+            if (nextVersion && nextVersion !== baseDeckVersion) {
+              state.deckVersion = nextVersion;
+              markCommentsUpdatedForVersion(nextVersion);
+              refreshDeckPreview(body.mtimeMs);
+              return;
+            }
+          } catch (error) {
+            reportError(error);
+            return;
+          }
+        }
+      }
+
       function refreshDeckPreview(version) {
         state.pendingRefreshMessage = true;
         state.pendingDeckSlideRestore = state.deckSlideIndex;
@@ -2098,7 +2266,7 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
           if (!res.ok || !body.ok) throw new Error(body.error || 'Failed to send comment');
           updatePendingCommentStatus(commentId, 'sent', { baseDeckVersion: body.deckVersion || state.deckVersion, requestId: body.commentRequestId || body.requestId || '' });
           if (pendingCommentStatus(commentId) !== 'updated') setStatus('Comment sent. Waiting for deck update...');
-          if (body.commentRequestId || body.requestId) pollCommentResult(commentId, body.commentRequestId || body.requestId);
+          if (body.commentRequestId || body.requestId) watchCommentProgress(commentId, body.commentRequestId || body.requestId);
         } catch (error) {
           updatePendingCommentStatus(commentId, 'failed');
           reportError(error);
@@ -2458,7 +2626,7 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
           if (!res.ok || !body.ok) throw new Error(body.error || 'Failed to send asset placement');
           updatePendingCommentStatus(commentId, 'sent', { baseDeckVersion: body.deckVersion || state.deckVersion, requestId: body.commentRequestId || body.requestId || '' });
           if (pendingCommentStatus(commentId) !== 'updated') setStatus('Asset placement sent. Waiting for deck update...');
-          if (body.commentRequestId || body.requestId) pollCommentResult(commentId, body.commentRequestId || body.requestId);
+          if (body.commentRequestId || body.requestId) watchCommentProgress(commentId, body.commentRequestId || body.requestId);
         } catch (error) {
           updatePendingCommentStatus(commentId, 'failed');
           reportError(error);
@@ -2543,6 +2711,9 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
           baseDeckVersion: state.deckVersion,
           updatedVersion: null,
           requestId: '',
+          progressEvent: null,
+          eventLog: [],
+          failureRaw: '',
         });
         renderCommentThread();
         return id;
@@ -2554,6 +2725,7 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         if (comment.status === 'updated' && status !== 'failed') return;
         comment.status = status;
         if (updates) Object.assign(comment, updates);
+        if (status === 'updated' || status === 'failed') comment.progressEvent = null;
         renderCommentThread();
       }
 
@@ -2563,6 +2735,7 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
           if ((comment.status === 'sent' || comment.status === 'sending' || comment.status === 'stale') && comment.baseDeckVersion !== version) {
             comment.status = 'updated';
             comment.updatedVersion = version;
+            comment.progressEvent = null;
             changed = true;
           }
         });
@@ -2601,7 +2774,7 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
             const body = await res.json().catch(() => ({}));
             if (!res.ok || !body.ok) throw new Error(body.error || 'Comment result failed');
             if (body.status === 'failed' || body.status === 'expired') {
-              updatePendingCommentStatus(commentId, 'failed');
+              updatePendingCommentStatus(commentId, 'failed', { failureRaw: body.raw || '' });
               setStatus(body.error || 'Review agent failed to apply the comment.');
               return;
             }
@@ -2619,6 +2792,135 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         }
       }
 
+      function watchCommentProgress(commentId, requestId) {
+        if (!requestId) return;
+        if (!('EventSource' in window)) {
+          pollCommentResult(commentId, requestId);
+          return;
+        }
+        let closed = false;
+        let fallbackStarted = false;
+        const startFallback = () => {
+          if (fallbackStarted) return;
+          fallbackStarted = true;
+          pollCommentResult(commentId, requestId);
+        };
+        let source;
+        try {
+          source = new EventSource('/api/comment-events?token=' + encodeURIComponent(token) + '&requestId=' + encodeURIComponent(requestId));
+        } catch {
+          startFallback();
+          return;
+        }
+        source.addEventListener('progress', (event) => {
+          let payload;
+          try {
+            payload = JSON.parse(event.data || '{}');
+          } catch {
+            return;
+          }
+          recordCommentProgress(commentId, payload);
+          if (payload.type === 'failed' || payload.type === 'timeout') {
+            closed = true;
+            source.close();
+            updatePendingCommentStatus(commentId, 'failed', { failureRaw: payload.detail || '' });
+            setStatus(payload.message || 'Review agent failed to apply the comment.');
+          } else if (payload.type === 'completed') {
+            closed = true;
+            source.close();
+            if (pendingCommentStatus(commentId) !== 'updated') setStatus(payload.message || 'Waiting for deck file update...');
+            watchDeckVersionAfterComment(commentId);
+          } else if (payload.message) {
+            setStatus(payload.message);
+          }
+        });
+        source.onerror = () => {
+          source.close();
+          if (!closed && pendingCommentStatus(commentId) !== 'updated' && pendingCommentStatus(commentId) !== 'failed') {
+            startFallback();
+          }
+        };
+      }
+
+      function recordCommentProgress(commentId, event) {
+        const comment = state.pendingComments.find((item) => item.id === commentId);
+        if (!comment || !event || !event.message) return;
+        if (codexReview) {
+          appendCodexEventLog(comment, event);
+        }
+        if (event.type === 'completed') {
+          comment.progressEvent = null;
+          if (codexReview) renderCommentThread();
+          return;
+        }
+        const nextEvent = {
+          type: event.type || 'codex_event',
+          message: String(event.message).slice(0, 240),
+          detail: typeof event.detail === 'string' ? event.detail.slice(-4096) : '',
+        };
+        const duplicate = comment.progressEvent;
+        if (duplicate && duplicate.type === nextEvent.type && duplicate.message === nextEvent.message && duplicate.detail === nextEvent.detail) return;
+        comment.progressEvent = nextEvent;
+        if (event.type === 'failed' || event.type === 'timeout') comment.failureRaw = typeof event.detail === 'string' ? event.detail.slice(-4096) : '';
+        renderCommentThread();
+      }
+
+      function appendCodexEventLog(target, event) {
+        if (!target.eventLog) target.eventLog = [];
+        const next = {
+          type: event.type || 'codex_event',
+          message: String(event.message || '').slice(0, 500),
+          detail: typeof event.detail === 'string' ? event.detail.slice(-12000) : '',
+          timestamp: typeof event.timestamp === 'number' ? event.timestamp : Date.now(),
+        };
+        const previous = target.eventLog[target.eventLog.length - 1];
+        if (previous && previous.type === next.type && previous.message === next.message && previous.detail === next.detail) return;
+        target.eventLog.push(next);
+        if (target.eventLog.length > 250) target.eventLog.splice(0, target.eventLog.length - 250);
+      }
+
+      function codexLogSummary(log) {
+        const count = Array.isArray(log) ? log.length : 0;
+        return count === 1 ? 'Codex execution log (1 event)' : 'Codex execution log (' + count + ' events)';
+      }
+
+      function renderCodexLog(log) {
+        if (!codexReview || !Array.isArray(log) || !log.length) return null;
+        const details = document.createElement('details');
+        details.className = 'codex-log';
+        const summary = document.createElement('summary');
+        summary.textContent = codexLogSummary(log);
+        const list = document.createElement('div');
+        list.className = 'codex-log-list';
+        log.forEach((item) => {
+          const row = document.createElement('div');
+          row.className = 'codex-log-entry';
+          const meta = document.createElement('div');
+          meta.className = 'codex-log-meta';
+          const type = document.createElement('span');
+          type.textContent = item.type || 'event';
+          const time = document.createElement('span');
+          time.textContent = item.timestamp ? new Date(item.timestamp).toLocaleTimeString() : '';
+          meta.appendChild(type);
+          meta.appendChild(time);
+          const message = document.createElement('div');
+          message.className = 'codex-log-message';
+          message.textContent = item.message || '';
+          row.appendChild(meta);
+          row.appendChild(message);
+          if (item.detail) {
+            const detail = document.createElement('pre');
+            detail.className = 'codex-log-detail';
+            detail.textContent = item.detail;
+            row.appendChild(detail);
+          }
+          list.appendChild(row);
+        });
+        details.appendChild(summary);
+        details.appendChild(list);
+        return details;
+      }
+
       function renderCommentThread() {
         els.commentThread.textContent = '';
         state.pendingComments.forEach((comment) => {
@@ -2635,6 +2937,28 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
 
           bubble.appendChild(text);
           bubble.appendChild(status);
+          if (comment.progressEvent) {
+            const progress = document.createElement('div');
+            progress.className = 'comment-progress';
+            const line = document.createElement('div');
+            line.className = 'comment-progress-line';
+            line.textContent = comment.progressEvent.message;
+            progress.appendChild(line);
+            bubble.appendChild(progress);
+          }
+          if (comment.status === 'failed' && comment.failureRaw) {
+            const details = document.createElement('details');
+            details.className = 'comment-raw';
+            const summary = document.createElement('summary');
+            summary.textContent = 'Details';
+            const pre = document.createElement('pre');
+            pre.textContent = comment.failureRaw;
+            details.appendChild(summary);
+            details.appendChild(pre);
+            bubble.appendChild(details);
+          }
+          const codexLog = renderCodexLog(comment.eventLog);
+          if (codexLog) bubble.appendChild(codexLog);
           els.commentThread.appendChild(bubble);
         });
       }
@@ -2767,6 +3091,7 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         els.inspectCards.innerHTML = '<div class="inspect-loading"><span class="loading-row"><span class="spinner" aria-hidden="true"></span><b>' + escapeHtml(message) + '</b></span><br>Preparing concise Purpose and Source context.</div>'
           + '<div class="skeleton-card"><div class="skeleton-line short"></div><div class="skeleton-line long"></div><div class="skeleton-line medium"></div></div>'
           + '<div class="skeleton-card"><div class="skeleton-line short"></div><div class="skeleton-line long"></div><div class="skeleton-line medium"></div></div>';
+        renderInspectCodexLog();
       }
 
       function getInspectComment() {
@@ -2783,6 +3108,7 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         setMode('inspect');
         els.inspectStale.innerHTML = '';
         state.inspectFallback = null;
+        state.inspectEventLog = [];
         renderInspectLoading('Reading selection...');
         try {
           const res = await fetch('/api/inspect?token=' + encodeURIComponent(token), {
@@ -2796,7 +3122,7 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
           state.activeInspectRequestId = body.requestId;
           state.inspectFallback = body.preprocess || null;
           renderInspectLoading('Waiting for Purpose and Source...');
-          await pollInspectResult(body.requestId);
+          await watchInspectProgress(body.requestId);
         } catch (error) {
           if (state.inspectFallback) {
             renderInspectResult(state.inspectFallback, 'Deterministic fallback');
@@ -2826,6 +3152,92 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         throw new Error('Insight timed out while waiting for Review agent result');
       }
 
+      async function fetchInspectResultOnce(requestId) {
+        const res = await fetch('/api/inspect-result?token=' + encodeURIComponent(token) + '&requestId=' + encodeURIComponent(requestId), { cache: 'no-store' });
+        const body = await res.json().catch(() => ({}));
+        if (!res.ok || !body.ok) throw new Error(body.error || 'Insight result failed');
+        if (body.status === 'completed') {
+          state.deckVersion = body.deckVersion || state.deckVersion;
+          renderInspectResult(body.result, 'Generated');
+          renderInspectCodexLog();
+          return true;
+        }
+        if (body.status === 'failed' || body.status === 'expired') {
+          const error = new Error(body.error || 'Insight failed');
+          error.raw = body.raw || '';
+          throw error;
+        }
+        return false;
+      }
+
+      async function watchInspectProgress(requestId) {
+        if (!requestId) return;
+        if (!codexReview || !('EventSource' in window)) {
+          await pollInspectResult(requestId);
+          renderInspectCodexLog();
+          return;
+        }
+        await new Promise((resolve, reject) => {
+          let settled = false;
+          let source;
+          const finish = (ok, error) => {
+            if (settled) return;
+            settled = true;
+            if (source) source.close();
+            if (ok) resolve();
+            else reject(error);
+          };
+          try {
+            source = new EventSource('/api/inspect-events?token=' + encodeURIComponent(token) + '&requestId=' + encodeURIComponent(requestId));
+          } catch (error) {
+            pollInspectResult(requestId).then(resolve, reject);
+            return;
+          }
+          source.addEventListener('progress', (event) => {
+            let payload;
+            try {
+              payload = JSON.parse(event.data || '{}');
+            } catch {
+              return;
+            }
+            recordInspectProgress(payload);
+            if (payload.type === 'failed' || payload.type === 'timeout') {
+              const error = new Error(payload.message || 'Insight failed');
+              error.raw = payload.detail || '';
+              finish(false, error);
+            } else if (payload.type === 'completed') {
+              fetchInspectResultOnce(requestId).then((ready) => {
+                if (ready) finish(true);
+                else pollInspectResult(requestId).then(() => finish(true), (error) => finish(false, error));
+              }, (error) => finish(false, error));
+            }
+          });
+          source.onerror = () => {
+            if (!settled) {
+              source.close();
+              pollInspectResult(requestId).then(() => finish(true), (error) => finish(false, error));
+            }
+          };
+        });
+      }
+
+      function recordInspectProgress(event) {
+        if (!event || !event.message) return;
+        const inspectLog = { eventLog: state.inspectEventLog };
+        appendCodexEventLog(inspectLog, event);
+        state.inspectEventLog = inspectLog.eventLog;
+        if (event.type !== 'completed') {
+          renderInspectLoading(event.message);
+        } else {
+          renderInspectCodexLog();
+        }
+      }
+
+      function renderInspectCodexLog() {
+        const codexLog = renderCodexLog(state.inspectEventLog);
+        if (codexLog) els.inspectCards.appendChild(codexLog);
+      }
+
       function collectReferenceSnapshot() {
         const elements = state.references.map((reference) => reference.payload);
         const first = elements[0] || {};

package/lib/runtime/review.ts

@@ -105,6 +105,7 @@ export async function reviewDeckOpen(input: ReviewDeckOpenInput): Promise<any> {
       openUrl: input.openUrl,
       sessionID: `codex-review:${requestedFile}`,
       promptBridge: createCodexExecReviewPromptBridge(),
+      surface: "codex",
     })
     return {
       ok: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyber-dash-tech/revela",
-  "version": "0.17.12",
+  "version": "0.17.14",
   "description": "OpenCode plugin for trusted narrative artifacts from local sources, research, and evidence",
   "type": "module",
   "main": "./index.ts",
@@ -53,7 +53,9 @@
   },
   "scripts": {
     "test": "bun test",
-    "typecheck": "tsc"
+    "typecheck": "tsc",
+    "smoke:mcp": "bun scripts/codex-mcp-smoke.ts",
+    "smoke:mcp-pack": "bun scripts/codex-mcp-pack-smoke.ts"
   },
   "peerDependencies": {
     "@opencode-ai/plugin": "*"

package/plugins/revela/.mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "revela": {
       "command": "npx",
-      "args": ["-y", "@cyber-dash-tech/revela@0.17.12", "mcp"]
+      "args": ["-y", "@cyber-dash-tech/revela@0.17.14", "mcp"]
     }
   }
 }