codex-slides-known-errors

1# Codex Slides Known Errors
2 
3Classify the failure before retrying. Preserve the same project id and run id;
4do not recreate a deck merely because a Browser tab closed or a wait timed out.
5 
6## Runtime and installation
7 
8- **Plugin version contract fails:** `.codex-plugin/plugin.json` must start with
9  the exact root `package.json` version plus `+codex.`. The desktop package must
10  use the same product version.
11- **App is unreachable:** inspect `CODEX_SLIDES_URL` and `CODEX_SLIDES_LOG`.
12  The local MCP launcher may need to prepare dependencies or a standalone build.
13- **Installed skill or tool inventory looks stale:** reinstall/upgrade the
14  plugin and start a new Codex task so the versioned plugin cache is refreshed.
15 
16## Durable runs
17 
18- **Another run is active:** inspect it with `get_project_run`. Wait, cancel it
19  explicitly, or allow a Deck Agent request to remain in the visible queue.
20- **Wait timed out:** the run was not cancelled. Continue with
21  `wait_project_run` or reopen its `browserHandoff`.
22- **Run id is missing after completion:** this indicates an old runtime without
23  terminal `runHistory`; refresh the plugin/runtime before retrying the task.
24- **Run is stopping:** do not start a conflicting render. Poll until it becomes
25  `cancelled`, then continue.
26 
27## Browser handoff and project resume
28 
29- Use the exact returned `browserHandoff.url`; do not reconstruct a project URL.
30- Keep all focus parameters: `slide`, `panel`, `version`, `mode`, `checkpoint`,
31…