# Task: 修复 AI 设计确认生成任务失败

## Identity

- Task ID: 20260814-design-generation-runtime-7d3a
- Mode: Feature
- Branch: codex/20260814-design-generation-runtime-7d3a-design-generation-runtime
- Worktree: D:\Datas\OthersProjects\makelore-design-generation-runtime-7d3a
- Base commit: 88f9ee8708beeb1ab45ca741807f6cca0f075ac9
- Owner: codex
- Status: Ready for Integration

## Scope

- Diagnose and fix the AI Canvas confirmation path where `confirm_generation` ends with `Agent Runtime is temporarily unavailable` and no workspace generation task appears.
- Keep the fix inside the Renderer API -> Main Host route -> persistent Agent Gateway Session boundary.
- Add focused regression coverage for the failing confirmation path and task/event projection affected by the fix.
- Do not change unrelated Agent prompts, project publishing, galleries, or server implementation.

## Intent And Constraints

- Preserve ADR-001 ownership: conversation state is scoped by Workspace + Conversation, while tasks and assets are Workspace-owned.
- Treat the screenshot as evidence of a runtime failure before task creation, not proof that the right-hand task list itself is broken.
- Verify the current client and server Gateway/WebSocket contracts before changing payloads or error handling.
- Prefer the smallest contract-compatible fix and retain Main ownership of backend access, credentials, sessions, and event streams.
- The repository `main` worktree is owned by integration task `20260813-sync-push-main-9c2f71`; this feature remains isolated and will be handed off as ready for integration.

## Outcome

- Confirmed that the client only consumed Run events over WebSocket while still submitting `turn.submit` through REST, and that it did not recognize the Gateway-level `agent_runtime_unavailable` code.
- Added Main-owned bidirectional Gateway command submission: an open Conversation WebSocket sends `command.submit`, correlates `command.accepted` by `request_id`, and continues to complete the Run from streamed events.
- Added a five-second transport-only fallback to the existing REST command endpoint using the same `client_command_id`; Gateway business errors are not retried through REST.
- Mapped `agent_runtime_unavailable` to a safe Chinese 503 response.
- Reconciled failed confirmations by immutable `quote_id`. If the Design service committed a Generation Task before the Gateway Run failed, the client refreshes Workspace tasks and the captured Conversation without repeating confirmation; if no task exists, the original error remains visible.
- Split confirmation reconciliation by ownership: Quote/task refresh remains Workspace-wide even after switching Conversations, while applying a Conversation or clearing its error/pending state requires matching Workspace-load and Conversation-selection generations. An old A -> B -> A response cannot overwrite the newer Conversation.
- Updated `README.md` to describe the bidirectional Gateway path and Quote-based task reconciliation.

## Verification

- Red loop before implementation:
  - `corepack pnpm exec vitest run tests/unit/works-square-design-workspace.test.ts -t "submits a confirmed Quote|maps a generic Agent Runtime"` -> 2 deterministic failures: REST `/commands` was still used and `agent_runtime_unavailable` projected as 502/English.
  - `corepack pnpm exec vitest run tests/unit/image-workspace-store.test.ts -t "recovers a committed generation task"` -> deterministic failure because the task list was not reconciled after a failed Run.
  - `corepack pnpm exec vitest run tests/unit/image-workspace-store.test.ts -t "does not let a failed ABA confirmation"` -> deterministic failure before the generation guard because the stale confirmation returned success after A -> B -> A.
  - `corepack pnpm exec vitest run tests/unit/image-workspace-store.test.ts -t "keeps reconciling Workspace tasks"` -> deterministic failure before splitting the guards because switching Conversation A -> B skipped the Workspace task refresh.
- `corepack pnpm exec vitest run tests/unit/works-square-design-workspace.test.ts tests/unit/image-workspace-store.test.ts tests/unit/image-canvas-page.test.tsx` -> 3 files, 74 tests passed.
- `corepack pnpm run typecheck` -> passed.
- `corepack pnpm run lint:check` -> passed with 0 errors and 6 pre-existing warnings outside the changed files.
- `corepack pnpm test` -> 156 files, 1687 tests passed. An earlier run executed concurrently with the production build and transiently missed an unrelated AI Hardware form label; its isolated rerun passed before the clean full-suite reruns.
- `corepack pnpm run build:vite` -> Renderer, Electron Main, and Preload production builds passed; existing chunk-size and mixed import warnings remain.
- Independent Sol reviewer -> PASS after two review/fix rounds; no blocking issue remains in WebSocket command correlation, idempotent fallback, Quote recovery, Conversation switching, or ABA handling.
- No shared Electron E2E fixture for AI Canvas confirmation was found under `e2e` or `tests`; no live authenticated production smoke was run.

## Follow-ups

- After integration, run one authenticated production confirmation smoke and verify the task appears by `quote_id` without `/runs/{run_id}` polling while the WebSocket remains connected.
- If production still returns `agent_runtime_unavailable` and no task exists after reconciliation, inspect the matching server Gateway Run/worker logs. The code is a generic safety boundary for Runtime resolve, lease, database, event validation, or unexpected production-tool failures; the client cannot create the protected task directly.
- Improve server-side correlation/traceback logging for the generic Runtime safety boundary; current logging records only the unexpected exception type, which is insufficient to distinguish the underlying production failure.

## Promotion Candidates

- Integration owner should update canonical AI Canvas architecture/current-state memory to record that connected Agent commands and events are bidirectional over the Conversation WebSocket, with idempotent REST fallback only for transport failure.
- Integration owner should record Quote-based confirmation reconciliation: Generation Tasks remain Workspace-owned and may need REST recovery when the task transaction commits before a terminal Gateway failure.