codex-slides-known-errors

name	codex-slides-known-errors
description	Diagnose and recover from Codex Slides plugin, MCP, Browser handoff, local runtime, durable run, project resume, rendering, Design Files, export, and version-contract failures. Use when a tool fails, a run stalls, a project appears stale, or Codex and the Browser disagree.

Codex Slides Known Errors

Classify the failure before retrying. Preserve the same project id and run id; do not recreate a deck merely because a Browser tab closed or a wait timed out.

Runtime and installation

• Plugin version contract fails: .codex-plugin/plugin.json must start with the exact root package.json version plus +codex.. The desktop package must use the same product version.
• App is unreachable: inspect CODEX_SLIDES_URL and CODEX_SLIDES_LOG. The local MCP launcher may need to prepare dependencies or a standalone build.
• Installed skill or tool inventory looks stale: reinstall/upgrade the plugin and start a new Codex task so the versioned plugin cache is refreshed.

Durable runs

• Another run is active: inspect it with get_project_run. Wait, cancel it explicitly, or allow a Deck Agent request to remain in the visible queue.
• Wait timed out: the run was not cancelled. Continue with wait_project_run or reopen its browserHandoff.
• Run id is missing after completion: this indicates an old runtime without terminal runHistory; refresh the plugin/runtime before retrying the task.
• Run is stopping: do not start a conflicting render. Poll until it becomes cancelled, then continue.

Browser handoff and project resume

• Use the exact returned browserHandoff.url; do not reconstruct a project URL.
• Keep all focus parameters: slide, panel, version, mode, checkpoint, conversation, and run.
• A clarify/research project may route through /?resume=<id>. The continuation query must survive that redirect.
• Presenter mode needs a user gesture for its second window. A presenter deep link opens the Play menu at the correct slide instead of bypassing popup protection.

Rendering and project state

• A partially rendered or paused deck is resumable. Read the project and start a durable render run for the existing project.
• If Codex state and Browser state differ, read /runs/get_project as the canonical snapshot, then reload the same Browser handoff.
• Do not report success for slides whose status is error or whose persisted image cannot be loaded.

Design Files and export

• Resolve Design Files through list_design_files; never guess an absolute path.
• Keep project files distinct from staged materials.
• Export the current or explicitly selected immutable version only after visual verification. Speaker notes are off-canvas but must remain present in PPTX.