feat: surface desktop run unblock summaries (#79)

xiaojiou176 · web-flow · commit 19076f30d3f2 · 2026-04-12T18:38:04.000-07:00
* feat: surface desktop run unblock summaries

* fix: harden desktop completion governance summary
diff --git a/apps/desktop/src/pages/RunDetailPage.tsx b/apps/desktop/src/pages/RunDetailPage.tsx
@@ -13,7 +13,7 @@ import {
 } from "../lib/types";
 import {
   fetchRun, fetchEvents, fetchDiff, fetchReports, fetchToolCalls, fetchChainSpec,
-  fetchAgentStatus, fetchRuns, rollbackRun, rejectRun, replayRun, promoteEvidence, fetchOperatorCopilotBrief,
+  fetchAgentStatus, fetchRuns, fetchArtifact, rollbackRun, rejectRun, replayRun, promoteEvidence, fetchOperatorCopilotBrief,
   type EventsStream,
   openEventsStream,
 } from "../lib/api";
@@ -113,6 +113,7 @@ function isTerminalEvent(event: EventRecord): boolean {
 
 export function RunDetailPage({ runId, onBack, onOpenCompare = () => {}, locale = DEFAULT_UI_LOCALE }: RunDetailPageProps) {
   const runDetailCopy = getUiCopy(locale).desktop.runDetail;
+  const completionGovernanceCopy = runDetailCopy.completionGovernance;
   const [run, setRun] = useState<RunDetailPayload | null>(null);
   const [events, setEvents] = useState<EventRecord[]>([]);
   const [diff, setDiff] = useState("");
@@ -123,6 +124,8 @@ export function RunDetailPage({ runId, onBack, onOpenCompare = () => {}, locale
   const [availableRuns, setAvailableRuns] = useState<RunSummary[]>([]);
   const [baselineRunId, setBaselineRunId] = useState("");
   const [replayResult, setReplayResult] = useState<Record<string, JsonValue> | null>(null);
+  const [planningContracts, setPlanningContracts] = useState<Array<Record<string, JsonValue>>>([]);
+  const [unblockTasks, setUnblockTasks] = useState<Array<Record<string, JsonValue>>>([]);
 
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState("");
@@ -184,6 +187,38 @@ export function RunDetailPage({ runId, onBack, onOpenCompare = () => {}, locale
         setAgentStatus(toArr(d?.agents));
       }
       if (runsRes.status === "fulfilled") setAvailableRuns(toArr(runsRes.value));
+
+      const artifacts = toArr((runData as any)?.manifest?.artifacts);
+      const hasPlanningContractsArtifact = artifacts.some((item) => {
+        const record = asRecord(item);
+        return toStr(record.name, "") === "planning_worker_prompt_contracts" || toStr(record.path, "") === "artifacts/planning_worker_prompt_contracts.json";
+      });
+      const hasUnblockTasksArtifact = artifacts.some((item) => {
+        const record = asRecord(item);
+        return toStr(record.name, "") === "planning_unblock_tasks" || toStr(record.path, "") === "artifacts/planning_unblock_tasks.json";
+      });
+
+      const [planningContractsArtifactRes, unblockTasksArtifactRes] = await Promise.allSettled([
+        hasPlanningContractsArtifact
+          ? fetchArtifact(runId, "planning_worker_prompt_contracts.json")
+          : Promise.resolve(null),
+        hasUnblockTasksArtifact
+          ? fetchArtifact(runId, "planning_unblock_tasks.json")
+          : Promise.resolve(null),
+      ]);
+      if (loadToken !== loadTokenRef.current) {
+        return;
+      }
+      setPlanningContracts(
+        planningContractsArtifactRes.status === "fulfilled" && planningContractsArtifactRes.value
+          ? toArr(planningContractsArtifactRes.value.data as Array<Record<string, JsonValue>>)
+          : [],
+      );
+      setUnblockTasks(
+        unblockTasksArtifactRes.status === "fulfilled" && unblockTasksArtifactRes.value
+          ? toArr(unblockTasksArtifactRes.value.data as Array<Record<string, JsonValue>>)
+          : [],
+      );
     } catch (err) {
       setError(sanitizeUiError(err, "Run detail failed to load"));
     } finally {
@@ -376,6 +411,32 @@ export function RunDetailPage({ runId, onBack, onOpenCompare = () => {}, locale
   const roleBindingReadModel = run.role_binding_read_model;
   const isTerminal = isTerminalStatus(run.status);
   const pendingApprovals = events.filter(ev => (ev.event || "").toUpperCase() === "HUMAN_APPROVAL_REQUIRED");
+  const continuationOnIncomplete = Array.from(
+    new Set(
+      planningContracts
+        .map((contract) => toStr(asRecord(asRecord(contract).continuation_policy).on_incomplete, ""))
+        .filter(Boolean),
+    ),
+  );
+  const continuationOnBlocked = Array.from(
+    new Set(
+      planningContracts
+        .map((contract) => toStr(asRecord(asRecord(contract).continuation_policy).on_blocked, ""))
+        .filter(Boolean),
+    ),
+  );
+  const doneChecks = Array.from(
+    new Set(
+      planningContracts.flatMap((contract) =>
+        toArr(asRecord(asRecord(contract).done_definition).acceptance_checks as unknown[] | null | undefined)
+          .map((item) => toStr(item, ""))
+          .filter(Boolean),
+      ),
+    ),
+  );
+  const unblockOwners = Array.from(new Set(unblockTasks.map((task) => toStr(asRecord(task).owner, "")).filter(Boolean)));
+  const unblockModes = Array.from(new Set(unblockTasks.map((task) => toStr(asRecord(task).mode, "")).filter(Boolean)));
+  const unblockTriggers = Array.from(new Set(unblockTasks.map((task) => toStr(asRecord(task).trigger, "")).filter(Boolean)));
   const semanticType = outcomeSemantic(run.outcome_type, run.status, run.failure_class, run.failure_code);
   const outcomeSemanticText = outcomeSemanticLabel(
     run.outcome_type,
@@ -485,6 +546,36 @@ export function RunDetailPage({ runId, onBack, onOpenCompare = () => {}, locale
                 <div className="muted text-xs">{runDetailCopy.bindingReadModel.readOnlyNote}</div>
               </div>
             ) : null}
+            {planningContracts.length > 0 || unblockTasks.length > 0 ? (
+              <div className="stack-gap-2 mt-3" data-testid="run-detail-completion-governance">
+                <div className="muted text-xs fw-500">{completionGovernanceCopy.title}</div>
+                <div className="data-list">
+                  <div className="data-list-row"><span className="data-list-label">{completionGovernanceCopy.workerPromptContracts}</span><span className="data-list-value mono">{planningContracts.length}</span></div>
+                  {unblockTasks.length > 0 ? (
+                    <div className="data-list-row"><span className="data-list-label">{completionGovernanceCopy.unblockTasks}</span><span className="data-list-value mono">{unblockTasks.length}</span></div>
+                  ) : null}
+                  {continuationOnIncomplete.length > 0 ? (
+                    <div className="data-list-row"><span className="data-list-label">{completionGovernanceCopy.onIncomplete}</span><span className="data-list-value mono">{continuationOnIncomplete.join(" / ")}</span></div>
+                  ) : null}
+                  {continuationOnBlocked.length > 0 ? (
+                    <div className="data-list-row"><span className="data-list-label">{completionGovernanceCopy.onBlocked}</span><span className="data-list-value mono">{continuationOnBlocked.join(" / ")}</span></div>
+                  ) : null}
+                  {doneChecks.length > 0 ? (
+                    <div className="data-list-row"><span className="data-list-label">{completionGovernanceCopy.doneChecks}</span><span className="data-list-value mono">{doneChecks.join(" / ")}</span></div>
+                  ) : null}
+                  {unblockOwners.length > 0 ? (
+                    <div className="data-list-row"><span className="data-list-label">{completionGovernanceCopy.unblockOwner}</span><span className="data-list-value mono">{unblockOwners.join(" / ")}</span></div>
+                  ) : null}
+                  {unblockModes.length > 0 ? (
+                    <div className="data-list-row"><span className="data-list-label">{completionGovernanceCopy.unblockMode}</span><span className="data-list-value mono">{unblockModes.join(" / ")}</span></div>
+                  ) : null}
+                  {unblockTriggers.length > 0 ? (
+                    <div className="data-list-row"><span className="data-list-label">{completionGovernanceCopy.unblockTrigger}</span><span className="data-list-value mono">{unblockTriggers.join(" / ")}</span></div>
+                  ) : null}
+                </div>
+                <div className="muted text-xs">{completionGovernanceCopy.advisoryNote}</div>
+              </div>
+            ) : null}
           </CardBody>
         </Card>
 
diff --git a/apps/desktop/src/pages/run_detail_page_controls.test.tsx b/apps/desktop/src/pages/run_detail_page_controls.test.tsx
@@ -22,6 +22,7 @@ vi.mock("../lib/api", () => ({
   fetchEvents: vi.fn(),
   fetchDiff: vi.fn(),
   fetchReports: vi.fn(),
+  fetchArtifact: vi.fn(),
   fetchOperatorCopilotBrief: vi.fn(),
   fetchToolCalls: vi.fn(),
   fetchChainSpec: vi.fn(),
@@ -47,6 +48,7 @@ import {
   fetchEvents,
   fetchDiff,
   fetchReports,
+  fetchArtifact,
   fetchOperatorCopilotBrief,
   fetchToolCalls,
   fetchChainSpec,
@@ -95,6 +97,7 @@ describe("RunDetailPage p0 controls", () => {
     vi.mocked(fetchEvents).mockReset();
     vi.mocked(fetchDiff).mockReset();
     vi.mocked(fetchReports).mockReset();
+    vi.mocked(fetchArtifact).mockReset();
     vi.mocked(fetchToolCalls).mockReset();
     vi.mocked(fetchChainSpec).mockReset();
     vi.mocked(fetchAgentStatus).mockReset();
@@ -121,6 +124,7 @@ describe("RunDetailPage p0 controls", () => {
     ] as any);
     vi.mocked(fetchDiff).mockResolvedValue({ diff: "" } as any);
     vi.mocked(fetchReports).mockResolvedValue([] as any);
+    vi.mocked(fetchArtifact).mockResolvedValue({ data: [] } as any);
     vi.mocked(fetchOperatorCopilotBrief).mockResolvedValue({
       report_type: "operator_copilot_brief",
       generated_at: "2026-03-31T12:00:00Z",
@@ -255,12 +259,57 @@ describe("RunDetailPage p0 controls", () => {
   });
 
   it("renders locale-aware operator labels on run detail when zh-CN is requested", async () => {
+    vi.mocked(fetchRun).mockResolvedValueOnce(
+      makeRun({
+        manifest: {
+          artifacts: [
+            { name: "planning_worker_prompt_contracts", path: "artifacts/planning_worker_prompt_contracts.json" },
+            { name: "planning_unblock_tasks", path: "artifacts/planning_unblock_tasks.json" },
+          ],
+        },
+      }),
+    );
+    vi.mocked(fetchArtifact)
+      .mockResolvedValueOnce({
+        data: [
+          {
+            prompt_contract_id: "worker-zh",
+            continuation_policy: {
+              on_incomplete: "reply_auditor_reprompt_and_continue_same_session",
+              on_blocked: "spawn_independent_temporary_unblock_task",
+            },
+            done_definition: { acceptance_checks: ["repo_hygiene", "test_report"] },
+          },
+        ],
+      } as any)
+      .mockResolvedValueOnce({
+        data: [
+          {
+            unblock_task_id: "unblock-zh",
+            owner: "L0",
+            mode: "independent_temporary_task",
+            trigger: "spawn_independent_temporary_unblock_task",
+          },
+        ],
+      } as any);
+
     render(<RunDetailPage runId="run-zh" onBack={vi.fn()} locale="zh-CN" />);
 
     expect(await screen.findByText("AI 操作员副驾驶")).toBeInTheDocument();
     expect(screen.getByText("Run 总览")).toBeInTheDocument();
     expect(screen.getByText("执行角色")).toBeInTheDocument();
     expect(screen.getByText("证据与可追溯性")).toBeInTheDocument();
+    expect(screen.getByText("完成治理摘要")).toBeInTheDocument();
+    expect(screen.queryByText("Worker prompt contracts")).toBeNull();
+    expect(screen.getByText("工作者提示合约")).toBeInTheDocument();
+    expect(screen.getByText("未完成时")).toBeInTheDocument();
+    expect(screen.getByText("阻塞时")).toBeInTheDocument();
+    expect(screen.getByText("解阻塞任务")).toBeInTheDocument();
+    expect(
+      screen.getByText(
+        "这些摘要来自持久化的工作者提示合约和解阻塞任务；它们只提供参考，`task_contract` 仍然掌握执行权威。",
+      ),
+    ).toBeInTheDocument();
     expect(screen.getByRole("button", { name: "运行中" })).toHaveAttribute("title", "暂停实时更新");
     expect(screen.getByRole("button", { name: /事件时间线（1）/ })).toBeInTheDocument();
     expect(screen.getByRole("button", { name: "回放对比" })).toBeInTheDocument();
@@ -320,8 +369,37 @@ describe("RunDetailPage p0 controls", () => {
             },
           },
         },
+        manifest: {
+          artifacts: [
+            { name: "planning_worker_prompt_contracts", path: "artifacts/planning_worker_prompt_contracts.json" },
+            { name: "planning_unblock_tasks", path: "artifacts/planning_unblock_tasks.json" },
+          ],
+        },
       }),
     );
+    vi.mocked(fetchArtifact)
+      .mockResolvedValueOnce({
+        data: [
+          {
+            prompt_contract_id: "worker-1",
+            continuation_policy: {
+              on_incomplete: "reply_auditor_reprompt_and_continue_same_session",
+              on_blocked: "spawn_independent_temporary_unblock_task",
+            },
+            done_definition: { acceptance_checks: ["repo_hygiene", "test_report"] },
+          },
+        ],
+      } as any)
+      .mockResolvedValueOnce({
+        data: [
+          {
+            unblock_task_id: "unblock-worker-1",
+            owner: "L0",
+            mode: "independent_temporary_task",
+            trigger: "spawn_independent_temporary_unblock_task",
+          },
+        ],
+      } as any);
 
     render(<RunDetailPage runId="run-binding" onBack={vi.fn()} />);
 
@@ -338,6 +416,13 @@ describe("RunDetailPage p0 controls", () => {
         "Read-only note: this mirrors the persisted binding summary. task_contract still owns execution authority.",
       ),
     ).toBeInTheDocument();
+    expect(screen.getByText("Completion governance")).toBeInTheDocument();
+    expect(screen.getByText("Worker prompt contracts")).toBeInTheDocument();
+    expect(screen.getByText("On incomplete")).toBeInTheDocument();
+    expect(screen.getByText("On blocked")).toBeInTheDocument();
+    expect(screen.getByText("Unblock tasks")).toBeInTheDocument();
+    expect(screen.getByText("Unblock owner")).toBeInTheDocument();
+    expect(screen.getByText("L0")).toBeInTheDocument();
   });
 
   it("recovers from error state after retry load", async () => {
@@ -703,4 +788,114 @@ describe("RunDetailPage p0 controls", () => {
     expect(screen.getByText("new diff payload")).toBeInTheDocument();
     expect(screen.queryByText("old diff payload")).toBeNull();
   });
+
+  it("ignores stale artifact summaries when runId switches during artifact loads", async () => {
+    const oldPlanning = createDeferred<{ data: Array<Record<string, unknown>> }>();
+
+    vi.mocked(fetchRun)
+      .mockResolvedValueOnce(
+        makeRun({
+          run_id: "run-old",
+          task_id: "task-old",
+          manifest: {
+            artifacts: [
+              { name: "planning_worker_prompt_contracts", path: "artifacts/planning_worker_prompt_contracts.json" },
+              { name: "planning_unblock_tasks", path: "artifacts/planning_unblock_tasks.json" },
+            ],
+          },
+        }),
+      )
+      .mockResolvedValueOnce(
+        makeRun({
+          run_id: "run-new",
+          task_id: "task-new",
+          manifest: {
+            artifacts: [
+              { name: "planning_worker_prompt_contracts", path: "artifacts/planning_worker_prompt_contracts.json" },
+              { name: "planning_unblock_tasks", path: "artifacts/planning_unblock_tasks.json" },
+            ],
+          },
+        }),
+      );
+    vi.mocked(fetchEvents)
+      .mockResolvedValueOnce([{ ts: "2026-02-19T00:00:01Z", event: "OLD_EVENT", level: "INFO" }] as any)
+      .mockResolvedValueOnce([{ ts: "2026-02-19T00:00:02Z", event: "NEW_EVENT", level: "INFO" }] as any);
+    vi.mocked(fetchArtifact).mockImplementation((requestedRunId, artifactName) => {
+      if (requestedRunId === "run-old" && artifactName === "planning_worker_prompt_contracts.json") {
+        return oldPlanning.promise as Promise<any>;
+      }
+      if (requestedRunId === "run-old" && artifactName === "planning_unblock_tasks.json") {
+        return Promise.resolve({
+          data: [
+            {
+              unblock_task_id: "unblock-old",
+              owner: "old-owner",
+              mode: "old-mode",
+              trigger: "old-trigger",
+            },
+          ],
+        } as any);
+      }
+      if (requestedRunId === "run-new" && artifactName === "planning_worker_prompt_contracts.json") {
+        return Promise.resolve({
+          data: [
+            {
+              prompt_contract_id: "worker-new",
+              continuation_policy: {
+                on_incomplete: "new-incomplete",
+                on_blocked: "new-blocked",
+              },
+              done_definition: { acceptance_checks: ["new-check"] },
+            },
+          ],
+        } as any);
+      }
+      if (requestedRunId === "run-new" && artifactName === "planning_unblock_tasks.json") {
+        return Promise.resolve({
+          data: [
+            {
+              unblock_task_id: "unblock-new",
+              owner: "new-owner",
+              mode: "new-mode",
+              trigger: "new-trigger",
+            },
+          ],
+        } as any);
+      }
+      return Promise.resolve({ data: [] } as any);
+    });
+
+    const { rerender } = render(<RunDetailPage runId="run-old" onBack={vi.fn()} />);
+    await waitFor(() => {
+      expect(fetchArtifact).toHaveBeenCalledWith("run-old", "planning_worker_prompt_contracts.json");
+    });
+
+    rerender(<RunDetailPage runId="run-new" onBack={vi.fn()} />);
+    expect(await screen.findByRole("heading", { name: "run-new" })).toBeInTheDocument();
+    await waitFor(() => {
+      expect(screen.getByText("new-owner")).toBeInTheDocument();
+      expect(screen.getByText("new-incomplete")).toBeInTheDocument();
+    });
+
+    await act(async () => {
+      oldPlanning.resolve({
+        data: [
+          {
+            prompt_contract_id: "worker-old",
+            continuation_policy: {
+              on_incomplete: "old-incomplete",
+              on_blocked: "old-blocked",
+            },
+            done_definition: { acceptance_checks: ["old-check"] },
+          },
+        ],
+      });
+      await Promise.resolve();
+    });
+
+    expect(screen.getByText("new-owner")).toBeInTheDocument();
+    expect(screen.getByText("new-incomplete")).toBeInTheDocument();
+    expect(screen.queryByText("old-incomplete")).toBeNull();
+    expect(screen.queryByText("old-owner")).toBeNull();
+  });
 });
diff --git a/packages/frontend-shared/uiCopy.ts b/packages/frontend-shared/uiCopy.ts
